xdate.report: COFECHA-Style Crossdating Report

In dplR: Dendrochronology Program Library in R

COFECHA-Style Crossdating Report

Description

Builds a crossdating report in the layout of the COFECHA output carried by the International Tree-Ring Data Bank (ITRDB) correlation-stats files: a summary header, the correlation of each series by segment with ‘A’ and ‘B’ flags, descriptive statistics for each series, and the findings of rwl.check, with a record of how the report was made.

Usage

xdate.report(x, seg.length = 50, bin.floor = 100, nyrs = 32,
             prewhiten = TRUE, ar.order.max = 3,
             pcrit = 0.01, lag.max = 10,
             method = c("pearson", "spearman", "kendall"),
             biweight = TRUE, check = TRUE, meta = list(),
             title = NULL)

## S3 method for class 'xdate.report'
format(x, type = c("text", "markdown", "html"),
       bins.per.page = 20, ...)

## S3 method for class 'xdate.report'
print(x, ...)

write.xdate.report(x, fname, type = NULL, ...)

Arguments

x	an rwl object, or the path to a file that read.rwl can read. For format, print and write.xdate.report, an object of class "xdate.report".
seg.length	an even integral value giving the length of the segments in years. Reduced, with a note in the report, when the record is too short for it.
bin.floor	a non-negative integral value giving the base for locating the first segment, as in corr.rwl.seg. Stepped down to 50, 10 and then 0, with a note, if no segment can be tested at the value given.
nyrs	NULL or a number greater than zero giving the rigidity of the smoothing spline each series is divided by before correlating, as in corr.rwl.seg. The default is COFECHA’s 32 years.
prewhiten	logical flag. If TRUE each filtered series is prewhitened with an ar model.
ar.order.max	NULL or a positive integer giving the largest order of the ar model used to prewhiten. The default, 3, is lower than corr.rwl.seg’s: after the spline, AIC chooses an order near 20, and prewhitening loses that many years at the start of every series. NULL leaves the order to AIC.
pcrit	a number between 0 and 1 giving the critical value for the one-tailed correlation test. The default, 0.01, is COFECHA’s.
lag.max	the largest shift, in years, at which each segment is also correlated with the master. Reduced if it is not less than the segment length.
method	the correlation coefficient, "pearson" (the default, as in COFECHA), "spearman" or "kendall".
biweight	logical flag. If TRUE the master is a robust mean computed with tbrm.
check	logical flag. If TRUE the report includes the errors and warnings from rwl.check.
meta	a list of fields for the report header, any of site.name, site.location, species, investigators, latitude, longitude, elevation, checked.by and chronology.file. site.name and species are taken from the header of a Tucson file when they are not given.
title	the title printed on each part. Defaults to the file name without its extension, or the name of the object.
type	the layout: "text", the fixed-width layout of the ITRDB files; "markdown", headings and tables for a page that renders; or "html", a single self-contained page with plain tables, the flagged segments shaded and a small inline stylesheet. For write.xdate.report, NULL chooses Markdown for a file name ending in ‘.md’ or ‘.markdown’, HTML for ‘.html’ or ‘.htm’, and text otherwise.
fname	the name of the file to write.
bins.per.page	the number of segments printed side by side in the correlation table before it continues on a new page, as COFECHA does.
...	further arguments to format: print and write.xdate.report pass bins.per.page on, and print also type.

Details

The segment correlations and flags come from corr.rwl.seg with lag.max set: each segment of each series is correlated with a leave-one-out master, at its dated position and at every shift up to lag.max years. A segment is flagged ‘B’ when some other position correlates better than the dated one, and ‘A’ when the dated position is the best tested but its correlation is under the critical value. With Pearson correlation the critical value printed in the report is exactly the one the test uses. Lags follow COFECHA: a negative lag means rings are probably missing from the series. The report lists each flagged segment with its lag and the gain in correlation, because a B flag is a hypothesis to check on the wood, and the size of the gain says how seriously to take it. A B flag whose best correlation is itself under the critical value is marked “weak at every lag”: the segment does not crossdate anywhere in the window, the shift only wins among weak correlations, and it is better read as a low correlation than as a dating error. The letter stays B, as COFECHA’s rule has it. See corr.rwl.seg for how to read the lags along a series.

The report differs from COFECHA in three ways, and says so in its notes. A segment is tested only where the series and the master cover all of it, at every lag, so series may show fewer segments than in COFECHA, which also tests partial segments at the ends of a series, and no flag can be raised at the ends of the record. The filtered block of the descriptive statistics describes the series that dplR correlated, which is not COFECHA’s filtered series, and is labelled “dplR filtered”. The correlation with the master is computed by dplR and usually differs from COFECHA’s in the second decimal place.

A series whose spline cannot be fitted, because it has internal NA values or its spline is not all positive, is described but left out of the crossdating, and the report names it and says why. With fewer than three series that can be crossdated there is no master, and the report gives the descriptive statistics alone.

The averages in the summary and in the totals row are weighted by the number of years in each series, as COFECHA’s are.

The report records how it was made: the dplR and R versions, the time, the MD5 checksum of the measurement file when x is a path, the filtering, the master, the correlation and the segments, and every setting that had to be changed to fit the data.

Value

xdate.report returns an object of class "xdate.report", a list with elements

title, file, meta	as given or found.
stats	a data.frame with one row per series: the descriptive statistics, the number of segments tested and flagged, the correlation with the master, and whether the series was crossdated.
flags	a character matrix, series by segment, of "A", "B" or "", or NULL if nothing was crossdated.
flagged	a data.frame with one row per flagged segment, in series then segment order, as in the report's flagged segments table, or NULL if nothing was crossdated. It has no rows if nothing was flagged. Its columns are seq and series (the series' number and name), from and to (the segment's first and last years), flag ("A" or "B"), r.dated (the correlation at the dated position), best.lag (the lag that correlates best; negative means missing rings), r.lag and gain (the correlation at best.lag and its gain over r.dated, NA for an A flag), weak (TRUE for a B flag that is under the critical value even at its best lag) and note.
crs	the result of corr.rwl.seg, or NULL.
excluded	a data.frame of the series left out of the crossdating and why.
check	the result of rwl.check, or NULL.
notes	the changes made to fit the data.
settings	the settings asked for and used.
provenance	the dplR and R versions, the time, and the file and its checksum.

format returns the report as a character vector, one element per line. print prints it and returns x invisibly. write.xdate.report writes it to fname and returns fname invisibly.

Author(s)

Andy Bunn.

References

Holmes, R. L. (1983) Computer-assisted quality control in tree-ring dating and measurement. Tree-Ring Bulletin, 43, 69–78.

See Also

corr.rwl.seg, rwl.check, ccf.series.rwl, xskel.ccf.plot

Examples

library(utils)
data(co021)
## The fault planted in the other crossdating examples: the 1500 ring
## deleted from series 641143
dat <- co021
x <- dat$"641143"
names(x) <- rownames(dat)
dat$"641143" <- delete.ring(x, year = 1500)
rpt <- xdate.report(dat, meta = list(site.name = "Schulman Old Tree No. 1",
                                     species = "PSME"))
rpt
## The flagged segments, as data
rpt$flagged
## Save it as fixed-width text, as Markdown, or as HTML
fn <- tempfile(fileext = ".txt")
write.xdate.report(rpt, fn)
fn.md <- tempfile(fileext = ".md")
write.xdate.report(rpt, fn.md)
head(readLines(fn.md), 12)
fn.html <- tempfile(fileext = ".html")
write.xdate.report(rpt, fn.html)
## Not run: 
utils::browseURL(fn.html)

## End(Not run)
unlink(c(fn, fn.md, fn.html))

dplR documentation built on Oct. 1, 2026, 9:07 a.m.