dplR (version 1.6.8)

rwi.stats.running: (Running Window) Statistics on Detrended Ring-Width Series

Description

These functions calculate descriptive statistics on a data.frame of (usually) ring-width indices. The statistics are optionally computed in a running window with adjustable length and overlap. The data can be filtered so that the comparisons are made to on just high-frequency data.

Usage

rwi.stats.running(rwi, ids = NULL, period = c("max", "common"),
                  method = c("spearman", "pearson","kendall"),
                  prewhiten=FALSE,n=NULL,
                  running.window = TRUE,
                  window.length = min(50, nrow(rwi)),
                  window.overlap = floor(window.length / 2),
                  first.start = NULL,
                  min.corr.overlap = min(30, window.length),
                  round.decimals = 3,
                  zero.is.missing = TRUE)
rwi.stats(rwi, ids=NULL, period=c("max", "common"), 
          method = c("spearman", "pearson","kendall"), …)
rwi.stats.legacy(rwi, ids=NULL, period=c("max", "common"))

Arguments

rwi

a data.frame with detrended and standardized ring width indices as columns and years as rows such as that produced by detrend.

ids

an optional data.frame with column one named "tree" giving a numeric ID for each tree and column two named "core" giving a numeric ID for each core. Defaults to one core per tree as data.frame(tree=1:ncol(rwi), core=rep(1, ncol(rwi))).

period

a character string, either "common" or "max" indicating whether correlations should be limited to complete observations over the period common to all cores (i.e. rows common to all samples) or the maximum pairwise overlap. Defaults to "max".

method

Can be either "pearson", "kendall", or "spearman" which indicates the correlation coefficient to be used. Defaults to "spearman". See cor.

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.

running.window

logical flag indicating whether to use a running window (TRUE, the default) or to ignore the other window parameters and effectively use one window covering all years (FALSE).

window.length

numeric value indicating the length of the running window in years. The default is 50 years or the number of years (rows) in rwi, whichever is smaller.

window.overlap

numeric value indicating the overlap of consecutive window positions, i.e. the number of common years. The default is half of the window length, rounded down.

first.start

an optional numeric value setting the position of the first window. Must be a value between 1 and n.years-window.length+1, where n.years is the number of years in rwi. The default value NULL lets the function make the decision using some heuristic rules.

min.corr.overlap

numeric value setting the minimum number of common years in any pair of ring-width series required for their correlation to be included in the calculations. Smaller overlaps are considered to yield unreliable correlation values which are ignored. Defaults to the minimum of 30 and the length of the window. One way to lift the restriction and include all correlations is to set min.corr.overlap = 0.

round.decimals

non-negative integer numeric value setting the desired number of decimal places in the results. Use NA, NULL or a negative number for no rounding.

zero.is.missing

logical flag indicating whether to treat zeros as missing values (TRUE, the default) or to include them in computation (FALSE).

…

arguments passed on to rwi.stats.running

Value

A data.frame containing the following columns (each row corresponds to one position of the window):

start.year

the first year in the window. Not returned if running.window is FALSE or called as rwi.stats or rwi.stats.legacy.

mid.year

the middle year in the window, rounded down. Not returned if running.window is FALSE or called as rwi.stats or rwi.stats.legacy.

end.year

the last year in the window. Not returned if running.window is FALSE or called as rwi.stats or rwi.stats.legacy.

n.cores

the number of cores

n.trees

the number of trees

n

the average number of trees (for each year, a tree needs at least one non-NA core in order to be counted). Not returned in the results of rwi.stats.legacy

n.tot

total number of correlations calculated as n.wt + n.bt.

Equal to n.cores * (n.cores-1)/2 if there is overlap between all samples

n.wt

number of within-tree correlations computed

n.bt

number of between-tree correlations computed

rbar.tot

the mean of all the correlations between different cores

rbar.wt

the mean of the correlations between series from the same tree over all trees

rbar.bt

the mean interseries correlation between all series from different trees

c.eff

the effective number of cores (takes into account the number of within-tree correlations in each tree)

rbar.eff

the effective signal calculated as rbar.bt / (rbar.wt + (1-rbar.wt) / c.eff)

eps

the expressed population signal calculated using the average number of trees as n * rbar.eff / ((n - 1) * rbar.eff + 1)

snr

the signal to noise ratio calculated using the average number of trees as n * rbar.eff / (1-rbar.eff)

Details

This calculates a variety of descriptive statistics commonly used in dendrochronology.

The function rwi.stats is a wrapper that calls rwi.stats.running with running.window = FALSE. The results may differ from those prior to dplR 1.5.3, where the former rwi.stats (now renamed to rwi.stats.legacy) was replaced with a call to rwi.stats.running.

For correctly calculating the statistics on within and between series variability, an appropriate mask (parameter ids) must be provided that identifies each series with a tree as it is common for dendrochronologists to take more than one core per tree. The function read.ids is helpful for creating a mask based on the series ID.

If ids has duplicate tree/core combinations, the corresponding series are averaged before any statistics are computed. The value of the parameter zero.is.missing is relevant in the averaging: TRUE ensures that zeros don<U+2019>t contribute to the average. The default value of zero.is.missing is TRUE. The default prior to dplR 1.5.3 was FALSE. If the parameter is set to FALSE, the user will be warned in case zeros are present. Duplicate tree/core combinations are not detected by rwi.stats.legacy.

Row names of ids may be used for matching the IDs with series in rwi. In this case, the number of rows in ids is allowed to exceed the number of series. If some names of rwi are missing from the row names of ids, the rows of ids are assumed to be in the same order as the columns of rwi, and the dimensions must match. The latter is also the way that rwi.stats.legacy handles ids, i.e. names are ignored and dimensions must match.

Note that period = "common" can produce NaN for many of the stats if there is no common overlap period among the cores. This happens especially in chronologies with floating subfossil samples (e.g., ca533).

Some of the statistics are specific to dendrochronology (e.g., the effective number of cores or the expressed population signal). Users unfamiliar with these should see Cook and Kairiukstis (1990) and Fritts (2001) for further details for computational details on the output. The signal-to-noise ratio is calculated following Cook and Pederson (2011).

If desired, the rwi can be filtered in the same manner as the family of cross-dating functions using prewhiten and n. See the help page for corr.rwl.seg for more details.

References

Cook, E. R. and Kairiukstis, L. A., editors (1990) Methods of Dendrochronology: Applications in the Environmental Sciences. Springer. ISBN-13: 978-0-7923-0586-6.

Cook, E. R. and Pederson, N. (2011) Uncertainty, Emergence, and Statistics in Dendrochronology. In Hughes, M. K., Swetnam, T. W., and Diaz, H. F., editors, Dendroclimatology: Progress and Prospects, pages 77<U+2013>112. Springer. ISBN-13: 978-1-4020-4010-8.

Fritts, H. C. (2001) Tree Rings and Climate. Blackburn. ISBN-13: 978-1-930665-39-2.

See Also

detrend, cor, read.ids, rwi.stats, corr.rwl.seg

Examples

# NOT RUN {
library(utils)
data(gp.rwl)
data(gp.po)
gp.rwi <- cms(rwl = gp.rwl, po = gp.po)
gp.ids <- read.ids(gp.rwl, stc = c(0, 2, 1))
# On a running window
rwi.stats.running(gp.rwi, gp.ids)
## With no running window (i.e. running.window = FALSE)
rwi.stats(gp.rwi, gp.ids)
## Restrict to common overlap (in this case 1899 to 1987)
rwi.stats(gp.rwi, gp.ids, period="common")
rwi.stats.legacy(gp.rwi, gp.ids) # rwi.stats prior to dplR 1.5.3

# }
# NOT RUN {
  library(graphics)
  def.par <- par(no.readonly=TRUE)
  ## Plot the chronology showing a potential cutoff year based on EPS
  eps.cut <- 0.92 # An arbitrary EPS cutoff for demonstration
  gp.crn <- chron(gp.rwi)
  ## Running stats on the rwi with an window
  foo <- rwi.stats.running(gp.rwi, gp.ids, window.length = 80)
  yrs <- time(gp.crn)
  bar <- data.frame(yrs = c(min(yrs), foo$mid.year, max(yrs)),
                    eps = c(NA, foo$eps, NA))
  par(mar = c(2, 2, 2, 2), mgp = c(1.1, 0.1, 0), tcl = 0.25,
      mfcol = c(2, 1), xaxs='i')
  plot(yrs, gp.crn[, 1], type = "n", xlab = "Year",
       ylab = "RWI", axes=FALSE)
  cutoff <- max(bar$yrs[bar$eps < eps.cut], na.rm = TRUE)
  xx <- c(500, 500, cutoff, cutoff)
  yy <- c(-1, 3, 3, -1)
  polygon(xx, yy, col = "grey80")
  abline(h = 1, lwd = 1.5)
  lines(yrs, gp.crn[, 1], col = "grey50")
  lines(yrs, ffcsaps(gp.crn[, 1], nyrs = 32), col = "red", lwd = 2)
  axis(1); axis(2); axis(3);
  par(new = TRUE)
  ## Add EPS
  plot(bar$yrs, bar$eps, type = "b", xlab = "", ylab = "",
       axes = FALSE, pch = 20, col = "blue")
  axis(4, at = pretty(foo$eps))
  mtext("EPS", side = 4, line = 1.1)
  box()
  ## Second plot is the chronology after the cutoff only
  ## Chronology is rebuilt using just years after cutoff but
  ## that difference is essentially nil.
  yr.mask <- yrs > cutoff
  yrs2 <- yrs[yr.mask]
  gp.crn2 <- chron(gp.rwi[yr.mask, ])
  plot(yrs2, gp.crn2[, 1], type = "n",
       xlab = "Year", ylab = "RWI", axes=FALSE)
  abline(h = 1, lwd = 1.5)
  lines(yrs2, gp.crn2[, 1], col = "grey50")
  lines(yrs2, ffcsaps(gp.crn2[, 1], nyrs = 32),
        col = "red", lwd = 2)
  axis(1); axis(2); axis(3); axis(4)
  box()
  par(def.par)
# }