dplR (version 1.8.0)

xdate.floater: 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, nyrs = NULL, prewhiten = TRUE,
              ar.order.max = NULL, biweight = TRUE,
              method = c("spearman", "pearson", "kendall"),
              make.plot = TRUE, return.rwl = TRUE, verbose = TRUE)
# S3 method for floater
print(x, ...)
# S3 method for floater
plot(x, ...)

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.

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.

nyrs

NULL or a number greater than zero. If not NULL, each series is divided by a smoothing spline with this rigidity (see caps) to remove low-frequency variation, as detrend does with method = "Spline". A value of 1 or less is taken as a proportion of each series' length. Unlike the hanning filter, the spline removes no years from the ends of a series. Cannot be combined with n.

prewhiten

logical flag. If TRUE (the default) each series is whitened using ar prior to correlation.

ar.order.max

NULL or a positive integer giving the maximum order of the ar model used to prewhiten. Prewhitening removes as many years from the start of each series as the order of the model. If NULL, the order is chosen by AIC up to the ar default, which on long series can be 20 or more. Requires prewhiten = TRUE.

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.

Author

Andy Bunn. Patched and improved by Mikko Korpela.

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.

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")