File Formats and Directory Structure

The directories used by the program are based around both the program_directory (where the program is installed) and the user_directory (where you store your input or model definition files). In a typical installation the program_directory would be C:\Programs\OxCal and the user_directory would be C:\My Documents\OxCal. These are used as follows:
contains the programs and calibration data
contains the manual
example files
contains your input files
has subdirectories grouping results data
results of 'quick' calculations
results from Eg_plot1
Files of various different types are used by the program and can be distinguished by their file extensions.

Calibration data files (*.dta or *.14c) are dealt with in the section on calibration data. Input (model definition) files (*.14i) are covered in the CQL command summary and log files (*.14l) are simple text files (with the exception of Relate.14l - see below). The four remaining file types are probability data files (*.14d or *.14s), plot organiser files (*.14p), viewer files (*.14v) and MCMC relationship files (Relate.14l).

File Names

All data file names are made up of three parts. The first part (two letters) is made up on the basis of position within the model. The second part (six letters) is made up in the following way: The file name extension depends on the type of file.
data files before analysis (simple calibration etc)
data files after analysis (including stratigraphic information)
plot organiser files (include references to data files)
viewer files (actual plots)
input or model definition files
log files (including relationship file)
Groningen data files
Seattle data files

Configuration File

All of the configuration information (including the strings used by the program) are stored in a file Oxcal3.ini in your Windows directory. If the settings of the program become corrupted for some reason delete this file and this will set everything back to the installed configuration.

Data Files

The basic data format is very simple and consists of lines of data with the format:
Calendar_age     Probability
or if calibration curve data is included (as it usually is for radiocarbon dates):
Calendar_age     Probability    14C_Age    error
The former is all that is required if you wish to produce a prior probability distribution in some other way. The resolution used internally will be the smallest gap between any two successive points and the distribution should be given in `oldest first' order.

Additional information is also included in files by lines starting with special characters.

" reference
As for calibration data files this gives the reference for any data
$ title
Gives the title for the data plot and the label used in multiple plots
# date error
Gives the date and error of a radiocarbon date (used for the gaussian curve)
! comment
Gives the title and other comment material for the plot
_ sigma from width
Gives range data for a particular sigma (or probability) confidence limit with a starting calendar age and width - if the width is -1 the range is treated as an `older than' range and if the width is zero it is treated as a `younger than' range
This data file gives relative ages rather than absolute calendar ages
* nx ny minx miny maxx maxy
This file contains a correlation plot with nx by ny points covering the given range - the data will then be a list of probabilities (one per line) starting at minx, miny given as rows (in x)
. minx maxx
Can be used to enlarge the range of a plot to encompass the range given
^ value
if value is greater than 1 gives the number of events; otherwise gives the maximum of the normalised curve
% n [value]
If no value is given will set an internal register to n; if a value is given it will be printed (as a percentage) in a multiple-plot only if the internal register is equal to n

To edit the data files produced right mouse click on the relevant icon in the plot organiser (see section on graphical display).

Plot Organiser Files

These are really only differentiated from data files in that they are allowed to contain some extra elements. In normal use the plot file will provide the framework for a multiple plot with references to the data files which actually contain the probability distributions. It is fairly easy to alter the plot files using the plot organiser window in order to change the order of plots, add extra page breaks, and alter labels.

Any of the special lines above might be found in a plot file but in addition the following are used:

Forces a page break at this point
| type
The next distribution is of a given type
< filename
Read in a data file (delete when finished with plot)
{ filename
Read in a data file (do not delete it with the plot)
> label
Plot a label at this point
Draws a solid horizontal line across the page
Draws a dotted horizontal line across the page
( comment
append this comment to the next label
) comment
append this to the comment below the last label
[ name
start a structure bracket with the appropriate name
finish a structure bracket
~ value
define the value for the overall agreement
& value
define the value for the agreement of this group
Looking at a few plot files should allow you to become familiar with the structure and alter them in any way you might want.

Viewer Files

These are binary files containing all of the plot information for a plot or many pages of plots. They cannot be manipulated except using the OxCal viewer program. From this, the graphics of the plots can be pasted into other applications, page by page.

Relationship Files

These are normally produced by the program and should not be tampered with. If, however, you are worried about exactly what the program is doing you can look at these files to check that the relationships have been correctly defined. To read the file simply double click on the icon in the plot organiser.

The format of the relationship file is fairly simple. Each distribution is introduced with a header line:

$ refno gap error name
The reference number is used in all of the relationships. The gaps are used for specific purposes (eg sequencing) - they usually represent a period after the event in which nothing else can occur - refer to command summary for details. The filename is used for the prior distribution (with an extension .14d and for the sample distribution with an extension .14s.

Following such a header there are then a number of lines (can be zero) giving the relationship of this event to the others. The relationships allowed are:

greater than
less than
greater than a boundary
less than a boundary
equal to
=no1 - no2
equal to no1 - no2
=no1 + no2
equal to no1 + no2
=no1 * no2
gives a correlation plot between two distributions
spans a distribution (for spans of phases)
equal to or greater than (for finding the ends of phases)
equal to or less than (for finding the starts of phases)
spans a distribution (only lower end affected)
spans a distribution (only upper end affected)
asks is this greater than?
asks is this less than?
asks does this span?
approximately greater than (used in V_SEQ)
approximately less than (used in V_SEQ)
approximately equal to
approximately equal to
asks is this approximately equal to
asks is this approximately equal to
asks is this equal to
request for information
order event
Without giving the entire code it is difficult to explain exactly what each of these does. The reason for much of the complexity is that the program is intended to be able to handle even the most obscure of nestings (such as wiggle matched sequences within variable sequences).

If you are in any doubt as to whether the program is working correctly for some complicated configuration, set up a simple example with calendar dates rather than radiocarbon dates and use correlation and difference plots to follow what the program is doing.