dplR (version 1.8.0)

ccf.series.rwl: Cross-Correlation between a Series and a Master Chronology

Description

Computes cross-correlations between a tree-ring series and a master chronology built from a rwl object at user-specified lags and segments.

Usage

ccf.series.rwl(rwl, series, series.yrs = as.numeric(names(series)),
               seg.length = 50, bin.floor = 100, n = NULL,
               nyrs = NULL, prewhiten = TRUE, ar.order.max = NULL,
               biweight = TRUE, pcrit = 0.05,
               lag.max = 5, make.plot = TRUE,
               floor.plus1 = FALSE, series.x = FALSE, ...)

Value

A list containing matrices ccf and

bins. Matrix ccf contains the correlations between the series and the master chronology at the lags window given by lag.max. Matrix bins contains the years encapsulated by each bin.

Arguments

rwl

a data.frame with series as columns and years as rows such as that produced by read.rwl.

series

a numeric or character vector. Usually a tree-ring series. If the length of the value is 1, the corresponding column of rwl is selected (by name or position) as the series and ignored when building the master chronology. Otherwise, the value must be numeric.

series.yrs

a numeric vector giving the years of series. Defaults to as.numeric(names(series)). Ignored if series is an index to a column of rwl.

seg.length

an even integral value giving length of segments in years (e.g., 20, 50, 100 years).

bin.floor

a non-negative integral value giving the base for locating the first segment (e.g., 1600, 1700, 1800 AD). Typically 0, 10, 50, 100, etc.

n

NULL or an integral value giving the filter length for the hanning filter used for removal of low frequency variation.

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 each series is whitened using ar.

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 then a robust mean is calculated using tbrm.

pcrit

a number between 0 and 1 giving the critical value for the correlation test.

lag.max

an integral value giving the maximum lag at which to calculate the ccf.

make.plot

logical flag indicating whether to make a plot.

floor.plus1

logical flag. If TRUE, one year is added to the base location of the first segment (e.g., 1601, 1701, 1801 AD).

series.x

logical flag indicating whether to make the series the x argument to ccf. See Details.

...

other arguments passed to plot.

Author

Andy Bunn. Patched and improved by Mikko Korpela.

Details

This function calculates the cross-correlation function between a tree-ring series and a master chronology built from rwl looking at correlations lagged positively and negatively using ccf at overlapping segments set by seg.length. For instance, with lag.max set to 5, cross-correlations would be calculated at for each segment with the master lagged at k = -5:5 years.

The cross correlations are calculated calling ccf as
ccf(x=master, y=series, lag.max=lag.max, plot=FALSE) if series.x is FALSE and as ccf(x=series, y=master, lag.max=lag.max, plot=FALSE) if series.x is TRUE. This argument was introduced in dplR version 1.7.0. Different users have different expectations about how missing or extra rings are notated. If series.x = FALSE the behavior will be like COFECHA where a missing ring in a series produces a negative lag in the plot rather than a positive lag.

Correlations are calculated for the first segment, then the second segment and so on. Correlations are only calculated for segments with complete overlap with the master chronology.

Each series (including those in the rwl object) is optionally detrended as the residuals from a hanning filter with weight n. The filter is not applied if n is NULL. Detrending can also be done via prewhitening where the residuals of an ar model are added to each series mean. This is the default. The master chronology is computed as the mean of the rwl object using tbrm if biweight is TRUE and rowMeans if not. Note that detrending typically changes the length of the series. E.g., a hanning filter will shorten the series on either end by floor(n/2). The prewhitening default will change the series length based on the ar model fit. The effects of detrending can be seen with series.rwl.plot.

References

Bunn, A. G. (2010) Statistical and visual crossdating in R using the dplR library. Dendrochronologia, 28(4), 251–258.

See Also

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

Examples

library(utils)
data(co021)
dat <- co021
## Create a missing ring: delete the 1500 ring of series 641143 and
## drop the original from the master.  Dated from the bark, every ring
## before 1500 now sits one year late.
flagged <- dat$"641143"
names(flagged) <- rownames(dat)
flagged <- delete.ring(flagged, year = 1500)
dat$"641143" <- NULL
ccf.100 <- ccf.series.rwl(rwl = dat, series = flagged, seg.length = 100)
if (FALSE) {
flagged2 <- co021$"641143"
names(flagged2) <- rownames(dat)
ccf.100.1 <- ccf.series.rwl(rwl = dat, seg.length = 100,
                            series = flagged2)
## Select series by name or column position
ccf.100.2 <- ccf.series.rwl(rwl = co021, seg.length = 100,
                            series = "641143")
ccf.100.3 <- ccf.series.rwl(rwl = co021, seg.length = 100,
                            series = which(colnames(co021) == "641143"))
identical(ccf.100.1, ccf.100.2) # TRUE
identical(ccf.100.2, ccf.100.3) # TRUE
}