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.
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 xdate.report
format(x, type = c("text", "markdown", "html"),
bins.per.page = 20, ...)
# S3 method for xdate.report
print(x, ...)
write.xdate.report(x, fname, type = NULL, ...)
xdate.report returns an object of class "xdate.report", a
list with elements
as given or found.
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.
a character matrix, series by segment, of
"A", "B" or "", or NULL if nothing was
crossdated.
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.
the result of corr.rwl.seg, or NULL.
a data.frame of the series left out of the
crossdating and why.
the result of rwl.check, or NULL.
the changes made to fit the data.
the settings asked for and used.
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.
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".
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.
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.
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.
logical flag. If TRUE each filtered
series is prewhitened with an ar model.
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.
a number between 0 and 1 giving the critical value for the one-tailed correlation test. The default, 0.01, is COFECHA’s.
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.
the correlation coefficient, "pearson" (the
default, as in COFECHA), "spearman" or
"kendall".
logical flag. If TRUE the master is a
robust mean computed with tbrm.
logical flag. If TRUE the report
includes the errors and warnings from rwl.check.
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.
the title printed on each part. Defaults to the file name without its extension, or the name of the object.
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.
the name of the file to write.
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.
Andy Bunn.
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.
Holmes, R. L. (1983) Computer-assisted quality control in tree-ring dating and measurement. Tree-Ring Bulletin, 43, 69–78.
corr.rwl.seg, rwl.check,
ccf.series.rwl, xskel.ccf.plot
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)
if (FALSE) {
utils::browseURL(fn.html)
}
unlink(c(fn, fn.md, fn.html))
Run the code above in your browser using DataLab