OxCal > Input of information

Input of information



Calibrating a single date

When using a server based or standalone versions of OxCal you can calibrate a single date from a simplified dialogue from the plotting utility (menu item @). This enables you to enter a lab identifier (or other label) the radiocarbon date (in 14C BP or F14C) and the uncertainty. By pressing the [Calibrate] 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. 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.

In some standalone versions the first time you run the OxCal program there may be some delay and so the first calibration/view curve operation you do may have to be repeated.


Viewing the calibration curve

Also you can press the [View curve] button from the opening dialogue (menu item @) of the plotting utility to generate a plot of the currently selected calibration curve. For details of how to adjust the plot see viewing output. If no plot appears see the installation page for details of the compatible browsers and SVG viewers.

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 data-sets.


Getting started with multi-plots

In order to calibrate several radiocarbon dates at once click on the 'Projects...' button which opens up a dialog showing any existing projects. Press the [+New] item to open a blank input window for you to enter your data for analysis. Alternatively, you can just 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] item in the left hand pane and you will be prompted for the details of a date to be entered. When you have entered these details press the button:

This will insert the command for calibrating a radiocarbon date into the file and you can see this in the right hand side. Once you have entered all of your dates you will see something like:


Plot()
R_Date("OxA-1200", 1287, 27)
R_Date("OxA-1201", 1234, 27)
R_Date("OxA-1201", 1289, 26)

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

You can also run the calibrations by pressing the forward button at the top right hand side:

and you can also return to your input file from the output viewer using the button at the top left hand side of that page:

Once the analysis has been complete, you can use these two buttons to swap back and forth between the input and output. The program will only run again if the input file is altered.

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 button:

And this should import all of the radiocarbon dates for analysis (see import tool)

The program includes context sensitive tips on the menus etc. which can be switched on and off by pressing the help button:

which is found at the top right hand corner of the left window pane.


File handling

See also file formats.

Overview of file structure

When you run a quick analysis 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:

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:

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 you will be transferred over to the output viewer. You can return to the input by pressing the back button:

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:

If the analysis might take some time the output viewer will display a status page.

Creating other files

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

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:

CutCopyPaste

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

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

There are shortcut buttons to switch between these views:

Model viewReverse orderList viewCode view

Inserting commands

Any command can be inserted into an OxCal run file using the [Insert] menu item. Just select from the drop down list of commands and enter the parameters for which you are prompted. There are also shortcuts to different types of input command shown underneath the insert dialogue.

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

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:

Curves

This tool helps you to specify the standard calibration curves. The top section allows the choice of the default calibration curve and the lower section allows you to specify a mixture between two curves for mixed reservoir dating. 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:

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. Note that this does not work with the code view.

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] option 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);};