Skip to content

Crossdating & COFECHA

Crossdating checks that every ring is assigned to its correct calendar year by correlating each series, segment by segment, against a master built from the other series. dplPy offers a dplR-faithful xdate, a COFECHA emulation (xdate(preset="COFECHA")), a COFECHA-style batch report, and floating-series dating.

xdate: segment correlations and flags

import dplpy as dpl

rwl = dpl.readers("ca533.rwl", header=True)
result = dpl.xdate(rwl)
result["seg_corr"]     # per-series, per-segment correlations
result["flags"]        # A/B flags per series

xdate returns a dictionary — seg_corr (a series × segment correlation table), overall (each series' correlation with the master), flags, bins, n_problems, and a summary (see below). By default it follows dplR's corr.rwl.seg:

  • Prewhitening with a Yule-Walker AR model (prewhiten=True).
  • Spearman correlation (corr="spearman").
  • A biweight leave-one-out master — each series is compared against the mean of the others, so a misdated series cannot prop up its own correlation.
  • Overlapping segments of slide_period years (default 50), stepped by half that, with bins floored to bin_floor (default 100).

The summary header

At the top of its output xdate prints a compact, COFECHA-style summary of the collection — number of dated series, master span, total rings, series intercorrelation, mean sensitivity, the count of possible-problem segments, and mean series length — and returns the same values in result["summary"] for programmatic use. Under preset="COFECHA" the intercorrelation and mean sensitivity are length-weighted, matching COFECHA's box.

Reading the flags

The two flags are mutually exclusive, COFECHA-style:

  • B flag — the segment correlates better at a non-dated lag than where it is dated (its best lag ≠ 0), hinting at a possible dating shift. dplPy's B flag follows COFECHA (it fires whenever the best match is at a non-zero lag, with no extra margin). dplR 1.8.0's corr.rwl.seg runs the same lag search (lag.max, reporting best.lag and best.rho), but keeps its returned flags significance-only rather than raising a separate B flag; dplPy promotes that lag result to an explicit B flag, on in both the default and COFECHA modes.
  • A flag — the dated (lag-0) position is the best match, but its correlation is still not significant at p_val (default 0.05): a weak but correctly-placed segment. An A flag's best lag is therefore always 0.

dplR 1.8.0 computes a per-segment lag search (best.lag / best.rho) but still flags on significance alone; dplPy splits its flags into A (lag 0 is best) and B (a better lag exists), so a segment is never both. The per-segment lag table is printed for both flag kinds.

Set plot=True (or call xdate_plot) for a dplR-style crossdating plot, or use series_corr to drill into one series.

The plot shows significance only — read the text flags too

dplPy's crossdating plot colours a segment red purely on significance (the A screen) and does not mark B (lag) flags. A B-flagged segment that still dates significantly is drawn blue, so it can look fine on the plot even though xdate() reports it as a possible dating shift. (dplR 1.8.0's plot.crs does now tint lag segments when corr.rwl.seg is run with lag.max > 0; dplPy keeps the lag flags in the text report for now.) Always read the text flag report alongside the plot to catch B flags.

COFECHA emulation

Passing preset="COFECHA" switches xdate to emulate the COFECHA program instead of dplR:

result = dpl.xdate(rwl, preset="COFECHA")

Pass the raw ring-width frame: unlike the default path (which expects detrended RWI), the COFECHA preset detrends the series itself — so do not call detrend first. The preset changes the crossdating machinery to match COFECHA:

  • a rigid cubic-spline detrend (32-yr, ratios) of the raw series,
  • spline variance stabilization of the detrended series,
  • Burg (maximum-entropy) AR prewhitening,
  • an arithmetic, z-scored leave-one-out master,
  • Pearson correlation,
  • COFECHA segment anchoring and t-based critical values, and
  • "omit absent rings" handling.

The dplR-faithful default is unchanged; the preset is an opt-in second mode.

xdate_report: COFECHA-style batch reports

xdate_report runs one or more ITRDB files through crossdating and writes a formatted, COFECHA-style .txt report with per-series and per-segment correlations and a length-weighted summary:

report = dpl.xdate_report("ca533.rwl", preset="COFECHA")

It accepts a .rwl path, a list of them, or an already-loaded ring-width DataFrame (pass name= to label an in-memory frame); takes the same slide_period / bin_floor / p_val settings as xdate; and offers both a dplR-faithful and a preset="COFECHA" mode. The output= argument controls where the report goes — "screen" prints it, "file" writes a <name>.txt, and "both" (the default) does both — and the report text is always returned in the result dictionary.

Diagnostics for one series

series_corr reports the correlation of a single named series against the master segment by segment (useful when xdate flags a series and you want to see where), and interseries_corr returns the overall interseries correlation of the collection — the same headline number COFECHA reports.

dpl.series_corr(rwl, series_name="CAM011")
dpl.interseries_corr(rwl)

Dating a floating series

xdate_floater places an undated (floating) series — a beam, a remnant log — against a dated reference collection by sliding it across every offset and scoring the fit:

placed = dpl.xdate_floater(reference_rwl, floating_series, series_name="beam1")
placed["best"]      # best-fit calendar placement and its statistics

It is based on dplR's xdate.floater and extended with the t statistic and additional crossdating statistics of Wilson (2026); the best placement is chosen by highest t (see the reference for the two documented departures from dplR).

dplR vs COFECHA at a glance

Default (preset=None) preset="COFECHA"
Emulates dplR corr.rwl.seg COFECHA
Correlation Spearman Pearson
Prewhitening Yule-Walker AR Burg (max-entropy) AR
Master biweight, leave-one-out arithmetic, z-scored, leave-one-out
Critical value p-value (p_val) COFECHA t-based table
A flag yes (matches dplR) yes
B flag (lag shift) yes (COFECHA-style) yes

See the Crossdating reference for every parameter.