R: Compute Correlations between Series

corr.rwl.seg {dplR} | R Documentation

## Compute Correlations between Series

### Description

Computes the correlation between each tree-ring series in a rwl object.

### Usage

    corr.rwl.seg(rwl, seg.length = 50, bin.floor = 100, n = NULL,
                 prewhiten = TRUE, pcrit = 0.05, biweight = TRUE,
                 method = c("spearman", "pearson","kendall"),
                 make.plot = TRUE, label.cex = 1, floor.plus1 = FALSE,
                 master = NULL,
                 master.yrs = as.numeric(if (is.null(dim(master))) {
                                  names(master)
                              } else {
                                  rownames(master)
                              }),
                 ...)

### Arguments

`rwl` | a `data.frame` with series as columns and years as rows such as that produced by `read.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`.
`pcrit` | a number between 0 and 1 giving the critical value for the correlation test.
`biweight` | `logical` flag. If `TRUE` then a robust mean is calculated using `tbrm`.
`method` | Can be either `"pearson"`, `"kendall"`, or `"spearman"` which indicates the correlation coefficient to be used. Defaults to `"spearman"`. See `cor.test`.
`make.plot` | `logical flag` indicating whether to make a plot.
`label.cex` | `numeric` scalar for the series labels on the plot. Passed to `axis.cex` in `axis`.
`floor.plus1` | `logical` flag. If `TRUE`, one year is added to the base location of the first segment (e.g., 1601, 1701, 1801 AD).
`master` | `NULL`, a `numeric` `vector` or a `matrix`-like object of `numeric` values, including a `data.frame`. If `NULL`, a number of master chronologies, one for each series in `rwl`, is built from `rwl` using the leave-one-out principle. If a `vector`, the function uses this as the master chronology. If a `matrix` or `data.frame`, this object is used for building the master chronology (no leave-one-out).
`master.yrs` | a `numeric` vector giving the years of `series`. Defaults to `names` or `rownames` of `master` coerced to `numeric` type.
`...` | other arguments passed to plot.

### Details

This function calculates correlation serially between each tree-ring series and a master chronology built from all the other series in the `rwl` object (leave-one-out principle). Optionally, the user may give a `master` chronology (a `vector`) as an argument. In the latter case, the same master chronology is used for all the series in the `rwl` object. The user can also choose to give a `master` `data.frame` (series as columns, years as rows), from which a single master chronology is built.

Correlations are done for each segment of the series where segments are lagged by half the segment length (e.g., 100-year segments would be overlapped by 50-years). The first segment is placed according to `bin.floor`. The minimum bin year is calculated as `ceiling(min.yr/bin.floor)*bin.floor` where `min.yr` is the first year in either the `rwl` object or the user-specified `master` chronology, whichever is smaller. For example if the first year is 626 and `bin.floor` is 100 then the first bin would start in 700. If `bin.floor` is 10 then the first bin would start in 630.

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. For now, correlations are Spearman’s rho calculated via `cor.test` using `method = "spearman"`.

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

The function is typically invoked to produce a plot where each segment for each series is colored by its correlation to the master chronology. Green segments are those that do not overlap completely with the width of the bin. Blue segments are those that correlate above the user-specified critical value. Red segments are those that correlate below the user-specified critical value and might indicate a dating problem.

### Value

A `list` containing matrices `spearman.rho`, `p.val`, `overall`, `bins`, `rwi`, vector `avg.seg.rho`, numeric `seg.lag`, `seg.length`, `pcrit`, `label.cex`. An additional `character` `flags` is also returned if any segments fall below the critical value. Matrix `spearman.rho` contains the correlations for each series by bin. Matrix `p.val` contains the p-values on the correlation for each series by bin. Matrix `overall` contains the average correlation and p-value for each series. Matrix `bins` contains the years encapsulated by each bin. The vector `avg.seg.rho` contains the average correlation for each bin. Matrix `rwi` contains the detrended rwl data, the numerics `seg.lag`, `seg.length`, `pcrit`, `label.cex` are from the oroginal call and used to pass into `plot.crs`.

### Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

### See Also

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

### Examples

    library(utils)
    data(co021)
    crs <- corr.rwl.seg(co021, seg.length = 100, label.cex = 1.25)
    names(crs)
    ## Average correlation and p-value for the first few series
    head(crs$overall)
    ## Average correlation for each bin
    crs$avg.seg.rho

[Package dplR version 1.7.2 Index]