sync.trend: Calculate temporal trends of synchrony

Description

The function calculates temporal trends of spatial synchrony from a data.frame with tree-ring width chronologies using a moving window as described in Shestakova et al. (2016). This method splits the time variable (varTime) in 30 years windows plus a 5 years lag, and in each window the within- or between-group level (varGroup) synchronies are calculated. The function can also be used to find synchrony with similar time series data.frame from other fields.

Usage

sync.trend (formula, varTime="", varGroup="", data,  window = 30, lag = 5, 
                    null.mod = TRUE, selection.method = c("AIC", "AICc", "BIC"), 
                    all.mod = FALSE, homoscedastic = TRUE, between.group = FALSE)

Arguments

formula

a formula a typical model formula such as Y ~ A, where Y is usually tree-ring width and A may be a grouping factor such as the specific names of tree-ring width chronologies (conifersIP).

varTime

a character specifying the time variable to consider in calculating synchrony estimates. Models with less than 10 different time-points may produce unreliable results.

varGroup

a character grouping variable. In dendrochronological studies different grouping strategies can be used. We used here two strategies following taxonomic (i.e. species) or geographic (i.e. region) criteria.

data

a data.frame with tree-ring chronologies, years and grouping variables as columns.

window

an integer specifying the window size (i.e. number of years) to be used to calculate synchrony. Must be greater than 20 (>=20). Defaults to 20.

lag

an integer specifying the lag that the window is moving (i.e. number of vrTirs moving window) to be used to calculate synchrony. Must be greater than 1 (>=1). Defaults to 5.

null.mod

a logical specifying if only the null model for general synchrony is fitted (broad evaluation, mBE). Default TRUE.

selection.method

a character string of "AIC", "AICc" or "BIC", specifying the information criterion used for model selection.

all.mod

a logical specifying if all homoscedastic and heteroscedastic models should be fitted. Default FALSE.

homoscedastic

a logical specifying if models should be an optional varFunc object or one-sided formula describing the within-group heteroscedasticity structure. Default TRUE

between.group

a logical specifying if between-group synchrony is displayed instead of whitin-group synchrony. Default FALSE.

Value

The function returns a data.frame containing the following components:

for null.mod TRUE:

a_Group

a column representing the within-group synchrony (mBE).

standard error of each observation.

Windlag

a column representing the lag of the window used to split the time variable. A 0 value means that lag is 0, and then the defined time window starts from minimun varTime value.

varTime

a column representing the varTime variable.

for null.mod FALSE:

Modname

a column indicating the best model fit and the information criterion used.

GroupName

a column indicating levels of the varGroup for each time-window selected.

a_Group

a column indicating within-group synchrony for each varGroup level at time-window selected.

a_betw_Grp

a column indicating between-group synchrony for each varGroup level at time-window selected. Only if between.group is set to TRUE.

standard error of each observation.

Windlag

a column representing the lag of the window used to split the time variable. A 0 value means that lag is 0, and then the defined time window starts from minimun varTime value.

varTime

a column representing the varTime variable window mean point.

Details

The function fits by default ("null.mod=T") the null model for general synchrony (broad evaluation, mBE) for a specified time window size and lag. If "null.mod=F" the function calculates homoscedastic or heteroscedastic versions of variance-covariance (VCOV) mixed models available (mBE, mNE, mCS, mUN, mHeNE, mHeCS, mHeUN; dendro.varcov) for each time window size and lag selected. In each window the best model is chosen based on the minimum information criterion selected between "AIC", "AICc" or "BIC". When no selection.method is defined by default AIC is used. If "all.mod=T" the functions fits the homoscedastic and heteroscedastic versions of the 7 models (this is a higly time consuming process).

References

Shestakova, T.A., Aguilera, M., Ferrio, J.P., Gutierrez, E. & Voltas, J. (2014). Unravelling spatiotemporal tree-ring signals in Mediterranean oaks: a variance-covariance modelling approach of carbon and oxygen isotope ratios. Tree Physiology 34: 819-838.

Shestakova, T.A., Gutierrez, E., Kirdyanov, A.V., Camarero, J.J., Genova, M., Knorre, A.A., Linares, J.C., Resco de Dios, V., Sanchez-Salguero, R. & Voltas, J. (2016). Forests synchronize their growth in contrasting Eurasian regions in response to climate warming. Proceedings of the National Academy of Sciences of the United States of America 113: 662-667.

Examples

Run this code

# NOT RUN {
## Calculate  temporal trends of spatial synchrony for conifersIP data:
 data(conifersIP)
 
 ##Fit the null.model temporal trend (mBE) 
 #using taxonomic grouping criteria (i.e. Species)
 mBE.trend <- sync.trend(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                          data = conifersIP, null.mod = TRUE, window = 30, lag = 5)
 
 mBE.trend# it returns a data.frame

# }
# NOT RUN {
 ##Fit homoscedastic within-group trends (mBE, mNE, mCS, mUN) 
 # using geographic grouping criteria (i.e. Region)
 geo.trend <- sync.trend(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                         data = conifersIP, window = 30, lag = 5, 
                         null.mod = FALSE, homoscedastic = TRUE)
                         
 geo.trend#a data.frame with varGroup syncrony for each time window.
 
 ##Fit heteroscedastic between-group trends (mBE, mHeNE, mHeCS, mHeUN) 
 #using geographic grouping criteria (i.e. Region) and BIC
 geo.het.trend <- sync.trend(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                             data = conifersIP, window = 30, lag = 5, null.mod = FALSE, 
                             selection.method = c("BIC"), homoscedastic = FALSE, 
                             between.group = TRUE)
 geo.het.trend
 
 ##Fit homoscedastic and heterocedastic within-group trends
 # using taxonomic grouping criteria (i.e. Species) and BIC
 geo.tot.trend <- sync.trend(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                             data = conifersIP, window = 30, lag = 5, 
                             selection.method = c("BIC"), all.mod = TRUE)
 geo.tot.trend
 
# }
# NOT RUN {
# }

Run the code above in your browser using DataLab