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 by pressing the [Calibrate] button. 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 [Run] button, the OxCal program is run on the server and a results table or plot is opened (see viewing output).

14C Date

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:

Time →

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:

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

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:

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:

[⌫] [Cut] [Copy] [Paste]

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:

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:

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.


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


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

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


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:


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:


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:


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:


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


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