COPRA – Constructing Proxy Records From Age Models
Version 1.16, last mod. 29-Jun-2022 23:24:01
(MATLAB® and Octave Toolbox)
General Notes
COPRA is a depth-age modeling program that
creates chronologies with uncertainties and can transform
age-uncertainties to proxy-uncertainties.
Installation
Download install.m
(for MATLAB older than R2014: install.m)
and execute it from the MATLAB or Octave console:
install
This script automatically installs the toolbox in the user's toolbox folder
(usually a folder called matlab in the home directory) and registers
it for regular use. After installation, COPRA is available in every MATLAB/Octave
session — you do not need to be in the COPRA folder to use it.
Work in your own project directory and keep your data files wherever is convenient.
To uninstall COPRA:
copraclean
Requirements
MATLAB R2010a or newer, or GNU Octave (command-line only, see below).
GUI Layout Toolbox (only needed for the graphical interface in MATLAB;
the command-line interface works without it).
The easiest way to install it is via the provided script —
download layoutInstall.m
(for MATLAB older than R2014: layoutInstall.m)
and run:
Note: Starting with R2014b, MATLAB uses a new graphics engine and the GUI Layout
Toolbox has known compatibility issues, which may cause errors in the COPRA GUI.
The command-line interface is unaffected.
Octave users: install the required packages once from the Octave console:
pkg install -forge io statistics
Then load the statistics package at the start of each session:
pkg load statistics
If copra is not found after installation, add the path manually:
addpath('/path/to/copra/installation')
Usage
In MATLAB (or Octave) use one of the following:
Graphical interface: copraGUI
Command-line: copra
Workflow overview
Whether using the GUI or the command line, COPRA follows the same sequence of steps:
Load data.
Provide an age–depth file and a proxy file (plain text, .txt or
.csv). Optionally include a layer count file if a section of the core
has been constrained by counting annual layers.
Full format specifications are in README.txt in the COPRA installation folder.
Review and edit age–depth data.
COPRA detects age reversals automatically. In the GUI you can interactively
remove outlier dating points, increase selected error bars, and mark hiatuses
(graphically by crosshair, or numerically). All modifications can be reset.
Run the Monte Carlo simulation.
COPRA draws M (default: 2000) random age–depth realisations consistent
with the dating uncertainties, enforces monotonicity, and interpolates each
realisation onto the proxy sampling depths.
Choose the interpolation method: pchip (default, recommended),
linear, or spline.
Note: Spline and cubic interpolation can produce non-monotonic curves for
cores with irregular accumulation, leading to very long computation times.
PCHIP is strongly recommended in most cases.
Adding layer-counted sections also increases computation time substantially;
when testing, start with a small number of layer-counted years (e.g. 10).
Inspect the age model.
The ensemble is displayed as a spaghetti plot, mean, median, or grayscale
(selectable in the GUI options panel, or as an argument to plotagemodel).
Construct the proxy record.
The proxy is mapped through each MC realisation onto the time axis, yielding
a time-uncertain and a time-certain output (see Outputs below).
Export results.
From the GUI export panel, or automatically at the end of a command-line run,
COPRA writes results to an output/ folder in the current working directory.
GUI panels at a glance
The GUI is arranged in six numbered panels, worked through left-to-right:
Panel
Function
1 – Input data
Load age–depth, proxy, and (optionally) layer count files;
set interpolation method, sample name, proxy label, and number of MC samples;
press Continue.
2 – Modify age–depth data
Remove points, increase error bars, add hiatuses (graphically or numerically),
reset changes; press Construct Agemodel to run the MC simulation.
3 – Age model plot
Displays the MC ensemble; press Construct Proxy Record to continue.
4 – Proxy record plot
Shows the proxy time series with age and proxy uncertainty bands.
5 – Options
Set confidence intervals for age and proxy (default 95%), choose plot types,
press Refresh to redraw.
6 – Export
Export results table, age model plot, proxy record plot, log file,
and data structure (.mat).
Command-line usage
String flags control the interpolation method and interaction mode:
copra % interactive, PCHIP interpolation (defaults)
copra('li') % linear interpolation
copra('pc') % PCHIP interpolation
copra('sp') % spline interpolation
copra('sil') % silent mode (no user prompts)
Capture output variables:
[T_unc, T_cert, d] = copra;
Pass parameters via the data structure to skip interactive input:
d.M = 5000; % number of MC samples
d.interp_method = 'pchip';
d.hia_depth = [142, 280]; % known hiatuses at depth 142 mm and 280 mm
[T_unc, T_cert, d] = copra(d);
Reload a previous run from a saved .mat file:
copra('output/mysample.mat')
% or from the workspace:
copra(d)
Outputs
Variable
Contents
T_unc
Time-uncertain result: depth × proxy × age matrix across all MC realisations.
T_cert
Time-certain result: columns are mean age, proxy value, age error (std), proxy error (std).
d
Full data structure with all inputs, parameters, and results. Save as .mat
to reload later without re-running the simulation.
Files written to output/: results table (.txt),
age model and proxy record figures (jpg/png/pdf/eps/fig/tif/bmp),
log file (.m), data structure (.mat).
Breitenbach, S. F. M., Rehfeld, K., Goswami, B., Baldini, J. U. L.,
Ridley, H. E., Kennett, D., Prufer, K., Aquino, V. V., Asmerom, Y.,
Polyak, V. J., Cheng, H., Kurths, J., Marwan, N.:
COnstructing Proxy Records from Age models (COPRA),
Climate of the Past, 8, 2012, 1765-1779 doi:10.5194/cp-8-1765-2012.
Authors
Norbert Marwan, Daniel Juncu, Kira Rehfeld, Bedartha Goswami, Sebastian Breitenbach
