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.
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"))
A data.frame containing the following columns (each row
corresponds to one position of the window):
the first year in the window. Not returned if
running.window is FALSE or called as
rwi.stats or rwi.stats.legacy.
the middle year in the window, rounded down. Not
returned if running.window is FALSE or called as
rwi.stats or rwi.stats.legacy.
the last year in the window. Not returned if
running.window is FALSE or called as
rwi.stats or rwi.stats.legacy.
the number of cores
the number of trees
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
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
number of within-tree correlations computed
number of between-tree correlations computed
the mean of all the correlations between different cores
the mean of the correlations between series from the same tree over all trees
the mean interseries correlation between all series from different trees
the effective number of cores (takes into account the number of within-tree correlations in each tree)
the effective signal calculated as
rbar.bt / (rbar.wt + (1-rbar.wt) / c.eff)
the expressed population signal calculated using the average
number of trees as
n * rbar.eff / ((n - 1) * rbar.eff + 1)
the signal to noise ratio calculated using the average
number of trees as
n * rbar.eff / (1-rbar.eff)
a data.frame with detrended and standardized ring
width indices as columns and years as rows such as that produced by
detrend.
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))).
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".
Can be either "pearson", "kendall", or
"spearman" which indicates the correlation coefficient to be
used. Defaults to "spearman". See cor.
NULL or an integral value giving the filter length
for the hanning filter used for removal of low
frequency variation.
logical flag. If TRUE each series is
whitened using ar.
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).
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.
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.
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.
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.
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.
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
Mikko Korpela, based on rwi.stats.legacy by Andy
Bunn
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’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).
Note that Buras (2017) cautions against using the expressed population signal as a statistic to determine the whether a chronology correctly represents the population signal of a data set. He reccomends the use of subsample signal strength (sss) over EPS.
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.
Buras, A. (2017) A comment on the Expressed Population Signal. Dendrochronologia 44:130-132.
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–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.
detrend, cor,
read.ids, rwi.stats,
corr.rwl.seg
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
Run the code above in your browser using DataLab