dcc: Response and correlation function analysis

In treeclim: Numerical Calibration of Proxy-Climate Relationships

Response and correlation function analysis

Description

This function calculates (potentially moving or evolving) response and correlation functions from tree-ring chronologies and monthly climatic data. For the moving case, the calculation is performed repeatedly for consecutive time windows. Function parameters may be bootstrapped to calculate their significance and confidence intervals.

Usage

dcc(
  chrono,
  climate,
  selection = -6:9,
  method = "response",
  dynamic = "static",
  moving,
  win_size = 25,
  win_offset = 1,
  start_last = TRUE,
  timespan = NULL,
  var_names = NULL,
  ci = 0.05,
  boot = "stationary",
  sb = TRUE
)

Arguments

chrono	data.frame containing a tree-ring chronologies, e.g. as obtained by chron of package dplR.
climate	either a data.frame or matrix with climatic data in monthly resolution, with year, month and climate parameters in columns (all columns except year and month will be recognized as parameters for response or correlation functions), or a single data.frame or matrix in 13-column format (see below), or a (potentially named) list of one or several of the latter.
selection	either a numeric vector, a modifier, or a chain of modifiers specifying the parameter selection for the model (see Details).
method	character string specifying the calculation method. Possible values are “response” and “correlation”. Partial strings are ok.
dynamic	character; should the analyis be carried out in a static, moving, or evolving fashion. One of c("static", "moving", "evolving"). Defaults to "static". Partial strings are ok.
moving	deprecated, use dynamic instead.
win_size	integer giving the window size for each recalculation in years for a moving analysis, and the initial window size for an evolving analysis.
win_offset	integer giving the number of years between each window start in years.
start_last	logical flag indicating whether the first window should start at the rear end (youngest part of the series) or not.
timespan	integer vector of length 2 specifying the time interval (in years) to be considered for analysis. Defaults to the maximum possible interval.
var_names	character vector with variable names. Defaults to corresponding column names of parameter climate if given as data.frame, or its names if given as list.
ci	numerical value to set the test level for significance test (values 0.01, 0.05 and 0.1 are allowed); the confidence intervals are adapted accordingly.
boot	character indicating which bootstrap method should be used, one of c("stationary", "std", "exact")
sb	logical flag indicating whether textual status bar for moving case should be suppressed. Suppression is recommended for e.g. Sweave files.

Details

This function builds upon and extents the functionality of programme DENDROCLIM2002 (Biondi and Waikul, 2004), and will calculate bootstrapped (and non-bootstrapped) moving and static response and correlation functions in a similar fashion as described in the above mentioned paper. Important extensions include a very flexible parameter selection model (see below), the possibility to use an unlimited number of climate parameters, and the option to use exact bootstrapping.

Input chronology data can be a data.frame such as produced by function chron of package dplR. It has to be a data.frame with at least one column containing the tree-ring indices, and the corresponding years as rownames.

For climatic input data, there are three possibilities: Firstly, input climatic data can be a data.frame or matrix consisting of at least 3 rows for years, months and at least one climate parameter in the given order. Secondly, input climatic data can be a single data.frame or matrix in the style of the original DENDROCLIM2002 input data, i.e. one parameter with 12 months in one row, where the first column represents the year. Or thirdly, input climatic data can be a (potentially named) list of one or several of the latter described data.frame or matrices. If named list is provided, potentially provided variable names through argument var_names are ignored. As an internal format dispatcher checks the format automatically, it is absolutely necessary that in all three cases, only complete years (months 1-12) are provided. It is not possible to mix different formats in one go.

Parameters can be selected with the 'selection' parameter in two different ways:

• simple selections: as an example -6:9 selects from all climate variables all months from previous year's June (-6, previous year's months are specified as negative integers) to current years September (9, months of the current year are specified as positive integers) as model parameters. Months from the previous year and the year before that can be selected using treeclim-shifters like ..(6) to refer to July of the year before the previous year.

• using modifiers: More complex parameter selections can be obtained by the modifiers provided in treeclim: .range, .mean, and .sum. These modifiers can also be chained to create complex selections. See treeclim-modifiers for details.

For the exclusion of months, the convenience function exclude_from (or short exfr) is provided.

1000 bootstrap samples are taken from the original distributions of climate and tree-ring data, either using the stationary bootstrap (Politis and Romano 1994, boot = "stationary") or classical bootstrap (DENDROCLIM2002-style, boot = "std"). The stationary bootstrap mimics the stationary properties of the original time series in the resampled time series by resampling within blocks. Within each block, the number of observations is random and has a geometric distribution. Consequently, the choice of the distribution parameter will affect the autocorrelation structure of the resampled time series. Optimal (expected) block length is chosen according to Politis and White (2004). In the case of response function analysis, an eigen decomposition of the standardized predictor matrix is performed. Nonrelevant eigenvectors are removed using the PVP criterion (Guiot, 1990), principal component scores are then calculated from the matrices of reduced eigenvectors and standardized climatic predictors. Response coefficients are found via singular value decomposition, and tested for significance using the 95% percentile range method (Dixon, 2001). In case of correlation function analysis, the coefficients are Pearson's correlation coefficients. The same method for significance testing is applied.

There is also the option to use exact bootstrapping like implemented in seascorr (Meko et al. 2011, boot = "exact"). In this case, circulant embedding is used to simulate the tree-ring data 1000 times as time series with the same frequency characteristics like the original time-series (Percival & Constantine, 2006). Empirical non-exceedence probabilities are used to test the coefficients of the response/correlation function with the original data for significance. For the exact bootstrapping case, no confidence intervals for the response/correlation coefficients can be computed.

Value

'dcc' returns an 'object' of class '"tc_dcc"'.

The functions 'summary' and 'plot' are used to obtain and print a summary of the results, and to create a plot. The function 'coef' can be used to extract the coefficients.

An object of class '"tc_dcc"' is a list containing at least the following components:

call	the call made to function 'dcc'
coef	the coefficients, themselves being an object of class 'tc_coef' for the static case, and of class 'tc_mcoef' for the moving case. Objects of class 'tc_coef' are single data.frames, while objects of class 'tc_mcoef' are lists of seperate data.frames for the coefficients (element 'coef'), upper and lower confidence interval (elements 'ci_upper' and 'ci_lower'), and significance flags (element 'significant')
design	the design matrix on which this call to 'dcc' operates
truncated	the input data truncated to the common timespan or the specified timespan
original	the original input data, with the climate data being recast into a single data.frame

Author(s)

Christian Zang; the original MATLAB code for exact bootstrapping was written by Dave Meko

References

Biondi, F & Waikul, K (2004) DENDROCLIM2002: A C++ program for statistical calibration of climate signals in tree-ring chronologies. Computers & Geosciences 30:303-311

Dixon, PM (2001) Bootstrap resampling. In: El-Shaarawi, AH, Piegorsch, WW (Eds.), The Encyclopedia of Environmetrics. Wiley, New York.

Guiot, J (1991) The boostrapped response function. Tree-Ring Bulletin 51:39-41

Meko DM, Touchan R, Anchukaitis KJ (2011) Seascorr: A MATLAB program for identifying the seasonal climate signal in an annual tree-ring time series. Computers \& Geosciences 37:1234-241

Percival DB, Constantine WLB (2006) Exact simulation of Gaussian Time Series from Nonparametric Spectral Estimates with Application to Bootstrapping. Statistics and Computing 16:25-35

Patton, A. and D.N. Politis and H. White (2009), "CORRECTION TO 'Automatic block-length selection for the dependent bootstrap' by D. Politis and H. White", Econometric Reviews 28(4), 372-375.

Politis, D.N. and H. White (2004), Automatic block-length selection for the dependent bootstrap, Econometric Reviews 23(1), 53-70.

Examples

## Not run: 
dc_resp <- dcc(muc_spruce, muc_clim)

## End(Not run)

treeclim documentation built on March 18, 2022, 7:22 p.m.