OxCal > Input of information

Input of information

• Calibrating a single date
• Viewing the calibration curve
• Getting started with multi-plots
• File handling
• Save to and open from your local computer
• Editing your input file
• Views of the input file
• Inserting commands
• Tools for helping with input files
• Importing from a spreadsheet
• Linking from a web-site/database

Calibrating a single date

When using a server based or standalone versions of OxCal you can calibrate a single date from a simplified dialogue by pressing the [Calibrate] button. This enables you to enter a lab identifier (or other label) the radiocarbon date (in ¹⁴C BP or F14C) and the uncertainty. By pressing the [Run] button, the OxCal program is run on the server and a results table or plot is opened (see viewing output).

The calibration curve can be selected using the [Options] button in the dialog box - or the [View > Options] menu item at the top of the window. If one of the post-bomb curves is selected the program will switch over to take input in the form of F14C (Reimer et al. 2004) and to display the curve against this quantity.

Viewing the calibration curve

Also you can press the [View curve] button from the calibration dialogue ([Calibrate] button) to generate a plot of a calibration curve calibration curve. You can set the curve to be shown here - and this will also be used for any subsequence quick calibrations. For details of how to adjust the plot see viewing output.

To view the curve you can also simply run an empty run file. If you include in the run file other calibration data-sets the curves for these will also be shown on the plot. This facility is useful for comparing calibration curves.

Getting started with multi-plots

In order to calibrate several radiocarbon dates at once either press the [New project] button when the program first opens or select [File > New] from the menu.

The input window that is then opened has a menu pane on the left hand side and an input file viewer on the right. To enter the dates for calibration click on the [Insert] button at the top of the input window, select [R_Date] and you will be prompted for the details of a date to be entered. When you have entered these details press the [Insert] button. This will insert the command for calibrating a radiocarbon date into the file and you can see this in the input window. Enter as many data points as you wish and then press [Cancel]. Once you have entered all of your dates you will see something like:

You are now ready to run the analysis which you do by pressing [File > Run] at the top of the input window (or in the top menu). This will prompt you for a filename (which you can leave as 'Untitled.oxcal'), run the calibrations and this will open the table window to show a table with the results of the calibration.

You can also run the calibrations by pressing the [Run] button at the top of the input window.

Once the analysis has been complete, you can use these two buttons to swap back and forth between the input and output windows as you wish.

In some cases you may wish to paste the data from a spreadsheet. This is easily done: arrange the spreadsheet so that the results are in three columns (Name, Date, Error) and then press [Tools > Import] and paste the contents of the spreadsheet into the blank input dialogue. Press the [Ok] button. This should import all of the radiocarbon dates for analysis (see import tool).

File handling

See also file formats.

Overview of file structure

When you run calibration of the type described above the program creates a file for you called 'Untitled.oxcal' which has the commands for your analysis. When the program is run three further files are created:

• Untitled.log - which contains a text version of the output
• Untitled.txt - which contains a tab delimited tabular output
• Untitled.js - which is the ECMA-Script encoded version of the output used for tables and plots.

You can view all of these files by pressing [File > Open] this puts up a file viewer which shows a row labelled 'Untitled' with four icons. These allow you to access the files or delete them all:

• Input file
• Output file (table or plot)
• Text file
• Log file
• Delete all four files

Naming your input file

Obviously you may not wish to always overwrite the previous analysis. Whenever you run a new analysis a file dialog opens which allows you to name the project. All of the files for that analysis will then be shown in a separate row in the file dialog (which you access through [File > Open]).

File manager

You can open the file manager by pressing [File > Manager]. This opens a dialog similar to that for [File > Open] but also showing all of the other relevant files for your projects (comparison curves, priors and saved graphics). Both this and the file open dialog allow you to create new folders (sub-directories) or rename existing projects and files (double click on the file label).

Saving and running your input file

From the main input screen you can save your input file (to the current file name) either by pressing [File > Save] or [File > Run]. When you run an analysis the table window will normally open.

If the analysis is more complex and might take some time. If you try to open the output for an analysis that is still active you can see that this is the case because it is shown as active in the file dialog:

• Program active

If the analysis might take some time a status dialog will be shown before the table.

Creating other files

In addition to input files, the other types of file you might wish to create are:

• Prior probability files (for use with the Prior command)
• Radiocarbon calibration record files (for use with the Curve command)

These can be created from the file dialog or file manager. If you are using the file dialog, you need to select the relevant file type from the selection box at the top. The file manager has a special section for prior and curve files on the right. You just need to press the [+New] icon to open up an editor. The files created are shown in the file dialog and will be accessible when the program runs. The main calibration data files are stored elsewhere and should be used for proper calibration - however other data sets may be used for comparison purposes to get alternative estimates of age.

Prior probability files have a simple format. They should have two columns which are separated by a tab or other white space. The first item on each row should be the primary parameter (usually the calendar date) and the second column is the probability. The program will automatically normalise the values. See also file formats.

Calibration data-sets in their simplest form have a three column format (calendar date, bp, uncertainty) again separated by white-space. You can also have a special line which contains a reference for the data-set that will appear in the output. This line should start with ## (double hash). Any line starting with a single # will be ignored as a comment line. See also file formats.

Both forms of file can be entered by pasting data from a spreadsheet.

To use the files you can either enter their names in the Curve or Prior command, or you can use the [File > Insert] menu item.

Important note: OxCal will also accept calibration files in Calib format but for the above simplified formats the dates should be given in OxCal's internal date format. The is one plus the number of years from the start of AD1 or the end of 1BC. For example 2001.0 is the start of the year AD2001 and -1999.0 is the start of the year 2000BC. So the middle of 1950 (taken to be the datum for cal BP) is 1950.5 in OxCal's internal format. See the section on the Calendar for more details.

Save to and open from your local computer

You may often wish to save your files onto your local computer where they can be stored in the long term. OxCal servers are likely to put a time limit on file storage to prevent them from becoming cluttered with old files. To save an input file to your local computer use the [File > Save as] menu item and then instead of pressing the [Save] button press [Download]. If you have installed the program locally this file can then be analysed on your own computer which may get over any server restrictions on CPU time.

The [File > Open] menu item can be used to open input files (.oxcal) from your own computer by using the [Upload] button. You can also upload input files from previous version of the program (.14i) or output files (.js).

Editing your input file

Obviously you may wish to alter an input file, repeat elements et cetera and so there are facilities built into the input editor for this. To select an item in the input pane simply click on it. Any subsequent insertions will go just before this item. If you wish to select more than one item you can click, hold the mouse button down and then release it over a later item. All selected items will turn blue. You can then use the [Edit] menu items [Cut], [Copy], [Paste] and [Delete] to operate on all of the items together. The menu item [Edit > Edit] will put up a editing dialogue box with the code for the selected items. The same box can be displayed by double clicking on an item.

There are also shortcut buttons displayed at the top of the editing window which perform the same actions:

You can also drag and drop items. To do this you click down on the label of the item you wish to move and hold the mouse button down; if you then release it over the bullet point associated with another item the selected item will be inserted before it.

[Edit > Undo] and [Edit > Redo] allow you to undo changes and repeat them again if you make a mistake and inadvertently delete important data.

The other way to edit an input file is to edit the code directly. This can be done by pressing [View > Code]. In this mode none of the other editing function work. You may wish to copy the code to another text editor (such as Notepad or TextEdit) to perform more complicated editing processes such as find and replace.

Views of the input file

Three viewing modes for the input files. These are selected from the [View] menu and are:

• Model (default): this view gives a schematic view of the input data with sequences in the order oldest first.
• List: a simple list view with the oldest first in sequences.
• Code: the actual OxCal input code; to check your code or to convert old OxCal code (versions 1-3) to the new version (4), redisplay in one of the other modes before running the code.

There are shortcut buttons to switch between these views at the bottom of the input window.

The model view can be altered to show in reverse (youngest first) to be consistent with stratigraphic relationships. You can toggle between the two orders using the [↕︎] button aa the bottom of the window, or by using [View > ↕Model]. You can tell the order by the "Time" arrow shown on the right of the input window in model view.

Inserting commands

Any command can be inserted into an OxCal run file using the [Insert] button. There are 5 main categories:

• [Events...] This is the default group and includes R_Date etc.
• [Modifiers...] These are commands which add properties to existing commands and are inserted by selecting the item to modify.
• [Plot...] Commands associated with plotting rather than modelling.
• [Models...] Commands associated with models.
• [Queries...] Commands that can be used to extract information from models.

By pressing [Others...] you can also get a full list of possible commands. Selecting any command will provide a dialog box to enter the parameters.

In addition the two commands Curve and Prior can be inserted with the relevant file information using [File > Insert] from the input window.

A full list of commands and a description of their use is given in the command reference.

Tools for helping with input files

Given the range of commands available in OxCal it is often easier to use one of the tools to generate at least part of your model and then input the specific data afterwards or using the import dialogue. All tools for model building are found under the [Tools] menu and are then split into several categories.

Options

This tool available under [Tools > Options] allows you to select the options for the analysis. The options are:

• Resolution: in years for histograms; for high resolution work set this to 1 or less
• Calibration
  • Curve: this can also be set for specific samples in the file - but a default curve can be set here
  • Curve file: this is the name of the file used for the curve
  • Cubic interpolation: determines the type of interpolation used between data-points in a calibration data-set
  • Include raw curve: determines whether the raw data points are included in the .js output file; doing this slows down plotting but allows this data to be shown on the calibration curve plots
  • Use F14C space: as a default all calibrations are performed by comparing radiocarbon concentration ratios (as in F14C); turning this option off will perform calibrations by comparing BP dates instead; there should be very minimal effect unless the uncertainty terms are large
• Log reporting: whether dates are reported in cal BC/AD (OxCal internal format) or converted to cal BP in the log file and for the C_Date() and C_Simulate() functions
• Ranges: whether floruits are chosen (rarely advised) and which probability levels are reported in the log file
• Advanced:
  • Convergence data: whether this is included in the output file (which increases file size)
  • Uniform span prior: sets whether two additional factors are applied to force the overall span of the dates to have a uniform prior
  • MCMC iterations (k): usually automatically determined by convergence tests; this can be used to set a higher value
  • Ensembles: how many ensembles are saved for age-depth or KDE models

Curves

This tool helps you to specify the standard calibration curves. There are four main categories:

• Atmospheric: the NH (IntCal) or SH (SHCal) calibration curves.
• Bomb: the curves for post-1950 covering different regions. If choosing one of these you should usually also set the resolution to 0.2.
• Marine: for marine samples; here a ΔR reservoir must be set.
• Mixed: for mixed marine and atmospheric curves, most often used for humans with mixed diet.

You can also use the [File > Insert] menu item to switch to a comparison curve.

Models

The model help should be useful for people starting to set up models for the first time as most of the code is generated automatically and then can be subsequently edited. The models catered for here are:

• Phases: these are groups of events which are all form one coherent group in some context but for which there is no information on the internal ordering; the program will generate code for multiple phases; you need to enter:
• • the number of groups
  • whether they are contiguous (that is one starts as the previous one ends), sequential (that is one starts after the previous one has ended with a possible gap) or overlapping (one phase might start before the previous one has ended).
  • you then need to populate the phases with dated events which is most easily achieved using the [Tools > Import] function or using [Insert] to insert them individually.
• Sequences: these are essentially the same as phases except it is now assumed that all of the events within each group have a predefined order
• R_Date combination: allows you to enter a series of dates for combination; the assumption is that they are all exactly the same age; the program prompts for a name for the group, any extra uncertainty and then the dates to be combined in a three column format (Name, Date (BP), Uncertainty) separated in a number of possible ways (selectable)
• Tree-ring sequence: this model covers the situation (most often found with tree rings) where you know the exact gap between subsequent events; the program prompts with a dialogue which expects input in a four column format (Name, Date (BP), Uncertainty, Gap) separated in a number of ways (selectable); dates should be entered oldest first.
• Deposition model: this series of models covers dates distributed through a sedimentary sequence and should be entered from top down; the elements to be entered are:
• • the data for the sequence in four column format (Name, Date (BP), Uncertainty, Depth)
  • whether the flexible 'Poisson' deposition model is to be selected - if this is not selected the deposition is assumed to be uniform
  • the 'k' parameter; the higher this is the more rigid the model; if it is 0 then the dates are entered in a simple sequence but with depth information included
  • the separator used for the data (Tab, Comma ... etc.)
• Exponential distribution: this assumes that unlike in the normal phase, where the dates are assumed to be roughly uniformly distributed they are exponentially distributed; the choices are:
• • Rise (frequency of dated events increasing over time)
  • Fall (frequency falling)
  • Ordered (if all of the events are in a predefined order)
  • The central phase or sequence then needs to be populated with events.
• Ramped distribution: this is just like the exponential distribution except that the underlying prior is a triangular ramp instead of an exponential
• Normal distribution: the dated events are assumed to be normally distributed; they can either be ordered in a sequence or unordered in a phase.
• Outlier model: this is used with outlier analysis. The outlier model should normally be at the start and one of the example models can be chosen and inserted, or the parameters can be altered by hand.

Import

The final tool is the import utility (see next section).

Importing from a spreadsheet

The import tool (menu item [Tools > Import] of the input utility of the input editor) can be used with any of the commands to import data from a spreadsheet or database. The data should be arranged in columns. For the default R_Date command three columns are required (Name, Date, Uncertainty).

Other commands can also be selected from a drop-down box which becomes visible when you open the import dialogue. You will be prompted for the relevant columns. The data separator (tab, space, comma etc.) can be selected from another drop-down menu.

Once the data has been entered, press the [Insert] button to insert the data into the existing model.

The analysis can then be performed by selecting [File > Run]. Once the analysis has finished you may wish to use the [View > Tab delimited] option of the output utility to paste the results of the analysis back into a spreadsheet or you can use the [File > Save as] menu in the table window to save the data in spreadsheet format (.csv).

Linking from a web-site/database

You can link to the program directly from another web-site/database. The URL for the link should be of the form:

OxCal.html?Command=R_Date("OxA-3000",3000,30);

To be safe you may wish to replace the quote marks with %22 and you will certainly need to replace = with %3D (in other words escape the command string) as in:

OxCal.html?Command=R_Date(%22OxA-3000%22,3000,30);

The first time you follow such a link you will need to log onto the system, thereafter the calibration should be performed immediately. You can calibrate multiple dates in this way:

OxCal.html?Command=R_Date("OxA-3000",3000,30);R_Date("OxA-3001",3060,30);R_Date("OxA-3002",3100,30);

and can in principle perform any of OxCal's functions, such as specifying a marine calibration curve:

OxCal.html?Command=Curve("Marine04");Delta_R(100,20);R_Date("OxA-3000",3000,30);

You can also link to the input window which allows the you to edit the data before running:

OxCal.html?Mode=Input&Command=Plot(){R_Date("OxA-3000",3000,30);R_Date("OxA-3001",3060,30);R_Date("OxA-3002",3100,30);};