xdate.floater: Crossdate an undated series

In dplR: Dendrochronology Program Library in R

Crossdate an undated series

Description

Pulls an undated (or misdated) series through a dated rwl object in order to establish possible dates for the series.

Usage

xdate.floater(rwl, series, series.name = "Unknown", min.overlap = 50,
              n = NULL, prewhiten = TRUE, biweight = TRUE,
              method = c("spearman", "pearson", "kendall"),
              make.plot = TRUE, return.rwl = TRUE, verbose = TRUE)

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

## S3 method for class 'floater'
plot(x, ...)

Arguments

rwl	a data.frame with series as columns and years as rows such as that produced by read.rwl.
series	a numeric vector of ring widths, e.g. a single column from an rwl object.
series.name	a character string giving a name for the undated series. Defaults to "Unknown".
min.overlap	a positive integer giving the minimum number of years of overlap required between the series and the master chronology at each search position. Defaults to 50.
n	NULL or a positive integer giving the filter length for the hanning filter used for removal of low frequency variation prior to correlation. NULL skips the filter.
prewhiten	logical flag. If TRUE (the default) each series is whitened using ar prior to correlation.
biweight	logical flag. If TRUE (the default) a robust mean is used when building the master chronology via tbrm.
method	the correlation coefficient to use. One of "spearman" (default), "pearson", or "kendall". See cor.test.
make.plot	logical flag. If TRUE (the default) a two-panel plot is produced showing the segments and the correlation surface. See Details.
return.rwl	logical flag. If TRUE (the default) a "floater" list object is returned. If FALSE only the correlation statistics data.frame is returned.
verbose	logical flag. If TRUE (the default) a brief summary is printed to the console.
x	a "floater" object produced by xdate.floater.
...	additional arguments — currently ignored.

Details

The undated series is slid along the master chronology built from rwl (using the leave-one-out principle) and the correlation between the series and the master is computed at each position with sufficient overlap. The position with the highest correlation gives the proposed dates.

Both series and master are optionally prewhitened and/or smoothed with a Hanning filter before correlation, consistent with the approach used in corr.series.seg.

The two-panel plot (produced when make.plot = TRUE, or by calling plot() on the returned object) shows: (1) a segment plot of the master series with the floater at its best-fit position highlighted in green; and (2) the correlation at each end-year searched, overlaid with a dashed significance line and a light-blue polygon showing the 5th–95th percentile band of the typical interseries correlation in the master chronology. The dark-blue horizontal line shows the median interseries correlation. The best-fit position is marked with green points and a dashed segment.

Value

If return.rwl = TRUE (the default), an object of class "floater" is returned. This is a named list with the following elements:

series.name	the name given to the undated series.
floaterCorStats	a data.frame with columns first, last, r, p, and n giving the start year, end year, correlation, p-value, and sample size at each search position.
rwlCombined	an rwl object containing the dated master series combined with the undated series placed at its best-fit dates.
rwlOut	an rwl object containing only the undated series at its best-fit dates.

If return.rwl = FALSE, only the floaterCorStats data.frame is returned.

Note

This function is experimental and may change in future releases. Users should always verify proposed dates visually and against the physical wood.

The choice of min.overlap affects both which search positions are evaluated and the reliability of the correlations at those positions. A short min.overlap allows the series to be placed near the edges of the master chronology where little overlap exists, producing correlations based on few observations that may be spuriously high. A very long min.overlap restricts the search to positions where the series is well inside the master, which is statistically conservative but can cause the function to miss the correct dates entirely if the true position lies near an edge, or to produce wrong dates if the best correlation within the constrained search window happens to be a false match. As a rule, min.overlap should be long enough to produce a stable correlation (50 years is a common starting point for annual tree-ring data) but no longer than roughly half the length of the undated series. The dashed significance line in the plot is calculated from the overlap length at each position and provides a useful guide: positions with short overlaps will have high significance thresholds and should be interpreted with caution.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

corr.series.seg, ccf.series.rwl, skel.plot, series.rwl.plot

Examples

library(utils)
data(co021)
summary(co021)

# Remove a series and try to recover its dates
foo <- co021[, "645232"]
bar <- co021
bar$"645232" <- NULL
out <- xdate.floater(bar, foo, min.overlap = 50, series.name = "645232")
print(out)

# A longer series. With min.overlap = 100 the correct dates are recovered.
# With min.overlap = 200 the search window is so constrained that the true
# position is excluded and the function returns the best match within the
# remaining positions, which is a false fit. Compare the two results.
foo <- co021[, "646118"]
bar <- co021
bar$"646118" <- NULL
out <- xdate.floater(bar, foo, min.overlap = 100, series.name = "646118")
out <- xdate.floater(bar, foo, min.overlap = 200, series.name = "646118")

dplR documentation built on May 21, 2026, 9:07 a.m.