IntChron integration tool

The IntChron integration tool is intended to be used for the viewing, management and analysis of structured chronological information. 

• Data model
• Projects
• Records
• Data series
  
• Project data series
• Bibliography
• Parameters
• Options

• Wndowing system
• Data display options
  
• Searching
  

Data model

The tool is purely web-based and most operations are performed in the clients browser rather than on the server.  The only exceptions are file storage and radiocarbon calibration/analysis using OxCal.

Each instance of the tool works on a single IntChron project, but can also be used to merge data from different projects if required.  The information is stored in JSON format as described in the schema and is based on a linked data model.  Data can be stored:

• as local JSON files (which can be uploaded and downloaded)
• as files stored on the IntChron server (also the OxCal server)
  
• on websites and accessed as url
• dynamically served from web-based databases

If you wish to store data on the IntChron server or access databases available through IntChron you need to log in to the system.  This can be done using [File > Login] and the [File] menu also has options for new users and forgotten passwords.  The usernames and passwords are shared with OxCal.

Projects

Overall organization

See the project schema for details of the file format.  A project holds information on:

• Records:normally geographically located sites/records for which information is held
  
• Data series:these are stored within the record structure
  
• Project data series:these are data series not directly associated with records
  
• Bibliography:this is a compilation of all the references for the project
  
• Parameters:these specify parameters not given in the schema relevant to the project - or sets extra details on how standard parameters are displayed
• Options:these are global options which affect the way information is displayed and interpreted

Working with project files

To create a new project use [File > New] this will create a new unnamed project which you can work on and to which you can import information.

To save the project you can either save it on the IntChron server using [File > Save as]  (which will require you to log on) or you can download it using [File > Download] which will allow you to save the whole project or parts of in.  If you are saving on the server you will be asked for a project name which will be used to create a new directory.  This needs to be a new name - if you are not sure what already exists use [File > Open] to view your home directory.   If you download the project you can select only parts of it to download which enables projects to be split.

Projects stored on the server are within a folder (directory) with the project name and are called "index.json".  If you wish to open a project stored on the server do [File > Open] navigate to the directory and select the "index.json" file.  It is also possible to have projects as single JSON files which have been uploaded - they are opened in the same way.

If you wish to open a project which you have as a file you can use [File > Upload] this will give you a dialog to upload the project file - and can either be used to open the file as a new project or to merge the data into an existing one.  This enables projects to be combined.

Records

See the record schema for details of the file format.  Records contain much of the information in many projects and they are intended to be used for specific geographical locations/sites.  To view the records use [View > Records/Sites].  This shows the list of records.

To create a new record manually press the [+ Record] button and you will be asked for the record name.  This should be a single word - typically the core code or a brief form of the site name. Spaces in the record name will be replaced by underscores to ensure these are single words.

The record has three tabs:

• Information - this holds the main information about the record
  
• Data series - this holds specific data content
  
• References - this is a list of references relevant to the record as a whole
  

To edit the record double click on the tabs or click on the edit icon ⊘.  This enables you to enter location information and other information about the site.  There is a location dialog for much of this information which enables conversion of location information from other formats  such as UTM, IARU or NGR within the UK into longitude and latitude which is what is used in IntChron.  This is where you can enter information about the site and region.

There are also some key record parameters which are used by tools within IntChron which should be set:

• z_type (z  type): one of depth (cores), height (speleothems), layers (ice/varves) or rings (dendrochronological) or rarely time.
• z_basis (z  basis): which can be original, composite or event-free (optional)
  
• z_units (z_units): either a unit of length (mm,cm,m) or rings; all lengths are stored in m but presented and exchanged in the format given
• t_source (Timescale): this is the ultimate source for the the timescale
  
• suppress_t (Suppress t): this is used when plotting data to prevent plots against time (optional)
  
• suppress_z (Suppress z): this is used when plotting data to prevent plots against depth (optional)
  

It is also useful in many cases to give information about the environment and the elevation but this will depend on the application.  There is space also for general text notes but these should be kept brief normally - if extensive documentation is required this would be better stored in files under data series.

The data series tab is where most of the data is normally stored see below.

To add references for the record click on the References tab - make sure you are in edit mode and click on [New Reference].   See details on reference entry below.

If you wish to add a lot of records in a single operation or wish to modify parameters of records in bulk you can use the [Import/Export] button on the Records/Sites window.  This will give you a window in which you can enter the data (with the correct headers) from a spreadsheet.   This will however, bypass the checks on values in the normal process so do check the results.

When you have records with location information you can use the [Map] button in the individual records window to show the location of the record or the [Map] button in the top menu to show all your records on a map.  When plotting multiple records the map is linked so you can pull up a specific record's data by clicking on the location within the map.

Each record has a color associated with it which can be set manually.  From the Records/Sites window you can also color all the records on a number of different criteria.

Data series

See the data schema for details of the file format.  Data series can be entered for a record using the "Data Series" tab.  To add an additional series you go into edit mode and then press [Add to Data Series] which will prompt for a new series name.  Each data series should have a unique name (within that record).

The data content of each series is dependent on the type so the first thing is to select the type of series which will set up the entries to be included.  Most series headers include some common elements:

• series_type (Series type): this is the type of the data series
• series (Series): this is the unique name of the series
• header_list (Headers): this can be used to add additional header items if not already included
• parameter_list (Parameters): this can be used to add/remove columns for the data table
• refs (References): a list of references relevant to the data series
• data (Data): the actual data table
  

Unless the data is being imported in some other way the easiest way to import/export data is using the [Import/Export] button which enables you to copy/paste the data between a spreadsheet and the application with a number of formatting options.

The header_list and parameter_list both work in the same way.  They are a list of parameter names with comma separation.  If rather than add a parameter you with to remove one you can start the name with a tilde - so for a data set which normally has the parameter material you can put ~material in the parameter_list to remove that column.

Changes to the data series are shown in the record.  If you wish to save the changes you need to save the record or the project.

Note that the sample (Sample) parameter is particularly important as it enables the same sample to be identified in different data series and a well designed naming convention should be used.

Project data series

See the series schema for details of the file format.  These are essentially the same as data series within records but they exist at the project level.  These series can be shown by using [View > Project data].  Editing is similar as for records and data series.  The main difference is that project series can be stored as independent files (as can records) in the linked data model.

Bibliography

For any data set the associate references are very important as are the linkages between the data and the associate references.  This tool includes elements to keep track of references.  The references are stored at project level in a bibliography the format of which is given in the bibilography schema.  This is essentially based on the BibTeX system and references from an IntChron project can be conveniently exported to and imported from BibTeX.

To see the bibliography use [View > Bibliography]. This gives a list of citations with a check list of those with URL and DOI data.  If you hover your mouse over a citation you will see the full reference. The list is hyperlinked (where possible) to the original reference resource. If you want a simple list to view use the [Display] button on the bibliography which will output a full text formatted list of the references with links provided.

In the normal citation view there is a search icon on the right.  Pressing this will pull up a list of data resources within the project relevant to this reference.

Within the bibliography using [Import/Export] enable you to import/export references either in BibTeX format (for all references) or as a simple list of DOIs (where available).  This enables whole bibliographies to be added simply.  The bibliographic tool uses the CrossRef API and so can get full details from DOIs as long as they are within the CrossRef database.

In addition to the project bibliography,   The references are listed in individual records and data series.  To add a reference in any of these places go into edit mode and press the [New Reference] link.  This will pull up the bibliography tool.  There are several methods of data entry:

• If the publications are already in the project - simply select those you wish to include from the list of citations
• If the publication is not already included then press [Search] (this will be automatic if the bibliography is empty)
• In the "Search for" box enter the doi if you know it - this will be simplest
• If you have some elements of the title or authors and the year - enter these in "Search for" and "Year filter" dialogs
  
• If you have a full text version of the reference enter that in the "Search for" box
  
• Press [Search] again and see what is found - if what you are looking for is there select it in the same way and press [Ok]
• If the search does not give what you want - or you know it is unlikely to be available online press [New]
• Enter the first author's surname, the year and the title and the select the type
• Fill in the details by hand using BibTeX conventions and check the full reference at the bottom for any issues then press [Ok]
  

For many people it may be easier rather than entering publications by hand to export them in BibTeX format from elsewhere and then import them into the bibliography.

Reference details (if you are logged in) are stored in a central IntChron database of references which should speed up some processes rather than relying always on CrossRef.

The is a project level option accessible under [Edit > Bibliography > Clean] which will delete references in the bibliography but not in the project.  This will take effect when the project is next saved.

Parameters

Some parameters that you may wish to using in a project are not defined within the IntChron schema and in this case, ideally you should define them in the parameters section of the project.  The parameters can be viewed using [View > Parameters].  This also allows you to define how new (or existing) parameters are displayed and plotted.  It also allows you to set optional values.  So for example if you wish all your records to only have a ore-defined list of environment values this can be set there.

The details of the settings are given in the project schema.

Options

In addition to data which is relevant to the dataset the project stores a few global level options and these can be seen using [View > Options]  this gives:

• name (Name): the name of the project
• t_units (Time units): the format for time used in the project
• t_from (From): the start date of the project (used for plotting and data retrieval purposes)
• t_to (To): the end date of the project
• t_autorange (Auto): whether t_from and t_to are set automatically or fixed
• z_units (z units): the default for z units where not set at record level
• z_style (z style): the same for the format in when z and z_range are shown
• reversex (Reverse x axis): whether x axes are reversed
  
• reversey (Reverse y axis): whether y axes are reversed
• ondemand (Load on demand): if set will only load linked data when requested rather than on opening
• record_parameters (Record parameters): allows you to add extra meta-data parameters for records
  
• series (Series options): an array of special settings for series

Many of these options are simply saved versions of changes made in other ways.  The reversex option can be used if you prefer to plot time from young to old (left to right).

The series (Series options) allow you to set additional default pararmeters and headings for data series at the project level - this saves having to do it specifically within each data series.

Windowing system

The tool is based on a windowing system and a generic tool for data manipulation.  Windows can generally be opened using the [View] menu or by following links within the data.  Each window can be closed using the (x) button, minimized using the (-) button or maximized using the (+) button.  There is a footer bar which shows open windows and can be used to switch between windows if they are minimized or not visible.

Windows can be moved by clicking and dragging on the top bar.  They can be resized by clicking and dragging the bottom right corner.

Data objects can be edited either by double clicking on them or by using the edit icon ⊘ which toggles between edit and read mode.

Data display options

The way data is displayed can be set most easily through the Edit menu.  [Edit > Time] allows you to set the preferred format for dates (essentially all parameters like t, t_from, t_to etc).  [Edit > Depth/Height] allows you to specify which units are used for z parameters.  This is used in tables and in plots.  Note that internally all t-type parameters are stored in fractional astronomical years and all z parameters in m (except for layers and rings which are dimensionless).  This is to ensure that data does not require knowledge of the options set for interpretation.

Searching

There are various ways of searching for data within the IntChron tool.  Note that all searches are done within the data held in the browser and do not involve calls the the data source.

There are four main search modes which can be found through [Edit > Search] and these are:

• Data: this is for individual data entries within data series (at the record or project level)
  
• Records: this is for records themselves
  
• Samples: this enables all the data on particular samples to be aggregated - and where appropriate averaged; this is based on the sample (Sample) parameter which needs to be consistent between datasets
  
• Series: this is used for finding data series

The results of the searches are hyperlinked and so if you search for records for example you can then link to their associated data.  All of the search tools allow you to set which parameters are returned, the query used to filter the search and to order the results in relation to particular parameters.  You can choose whether or not to only return distinct results.  There is a helper tool for setting up the queries - they are ultimately written in javascript not SQL but are generally very flexible.

Finally there is a search option included in the bibliography as explained above.