R: Cross-Correlation between a Series and a Master Chronology

ccf.series.rwl {dplR} | R Documentation

## 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,
                   prewhiten = TRUE, biweight = TRUE, pcrit = 0.05,
                   lag.max = 5, make.plot = TRUE,
                   floor.plus1 = FALSE, series.x = FALSE, ...)

### 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.
`prewhiten` | `logical` flag. If `TRUE` each series is whitened using `ar`.
`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.

### 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 `switch.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. See the crossdating vignette `xdate-dplR`for more information.

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`.

### 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.

### Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

### 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 by deleting a year of growth in a random series
    flagged <- dat$"641143"
    flagged <- c(NA, flagged[-325])
    names(flagged) <- rownames(dat)
    dat$"641143" <- NULL
    ccf.100 <- ccf.series.rwl(rwl = dat, series = flagged, seg.length = 100)
    ## Not run:
    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

    ## End(Not run)

[Package dplR version 1.7.1 Index]