Package 'DendroSync'

Title: A Set of Tools for Calculating Spatial Synchrony Between Tree-Ring Chronologies
Description: Provides functions for the calculation and plotting of synchrony in tree growth from tree-ring width chronologies (TRW index). It combines variance-covariance (VCOV) mixed modelling with functions that quantify the degree to which the TRW chronologies contain a common temporal signal. It also implements temporal trends in spatial synchrony using a moving window. These methods can also be used with other kind of ecological variables that have temporal autocorrelation corrected.
Authors: Josu G. Alday (https://orcid.org/0000-0001-7510-8655), Tatiana A. Shestakova, Victor Resco de Dios (https://orcid.org/0000-0002-5721-1656), Jordi Voltas (https://orcid.org/0000-0003-4051-1158)
Maintainer: Josu G. Alday <[email protected]>
License: GPL-2
Version: 0.1.3
Built: 2025-01-22 03:41:00 UTC
Source: https://bitbucket.org/josucham/dendrosync

Help Index


Between-group synchrony for a homoscedastic unstructured model

Description

The function calculates the between-group synchrony (a^) and standard error (SE) for a homoscedastic unstructured model or full model (mUN).

Usage

bet.aSE(model)

Arguments

model

a class "lme" unstructured model (mUN) produced by dendro.varcov with homoscedastic equals TRUE.

Details

The function calculates between-group synchrony for a homoscedastic unstructured model (mUN).

Value

The function returns a matrix containing between-group synchrony and SE for each combination of varGroup levels. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate between-group synchrony and SE
 # for an unstructured homocedastic model of conifersIP data:
 data(conifersIP)
 
 #Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = TRUE)
 summary(ModHm)
   
 #Obtain the unstructured model between-group synchrony and SE
 # for each varGroup stratum.
 bet.aSE(ModHm$mUN)#Unstructure

Between-group synchrony for a heteroscedastic unstructured model

Description

The function calculates the between-group synchrony (a^) and standard error (SE) for a heteroscedastic unstructured model (mHeUN).

Usage

bet.het.aSE(model)

Arguments

model

a class "lme" unstructured model (mHeUN) produced by dendro.varcov with homoscedastic equals FALSE.

Details

The function calculates between-group synchrony for a heteroscedastic unstructured model (mHeUN).

Value

The function returns a matrix containing between-group synchrony and SE for each combination of varGroup levels. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate between-group synchrony and SE 
 ##for a heteroscedastic unstructured model for conifersIP data:
 data(conifersIP)
 
 #Fit the heteroscedastic set of varcov models (mBE, mHeNE, mHeCS, mHeUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = FALSE)
 
 #between-group synchrony and SE for each varGroup stratum combination
 # in heteroscedastic unstructured models.
 bet.het.aSE(ModHt$mHeUN)#Unstructured model

Iberian Peninsula tree-ring width dataset

Description

This dataset presents tree-ring width chronologies of residual indices published in Shestakova et al. (2016). The dataset contains 30 tree-ring width chronologies of conifer species from the Iberian Peninsula for the period 1950-1999. Tree species are represented by Abies alba Mill., Pinus nigra subsp. salzmannii (Dunal) Franco and Pinus sylvestris L. The sampling sites are distributed across three subregions (north, centre and south) of the Iberian Peninsula. Site chronologies are obtained by cross-dating tree-ring width series and posterior detrending and autocorrelation removal with the Friedman supersmoother spline and autoregressive modeling.

Usage

data(conifersIP)

Format

A data.frame containing 30 tree-ring chronologies of residual indices for the period 1950-1999. The dataset includes three species (Abies alba, Pinus nigra, Pinus sylvestris) that are distributed across three regions (north, centre and south) in accordance with the latitudinal position of each sampling site. conifersIP has following variables:

  • Year: year of tree-ring formation (1950-1999)

  • Region: geographical region for Iberian Peninsula: north, centre, south

  • Species: tree species: Abies alba, Pinus nigra, Pinus sylvestris

  • Code: specific name of tree-ring width chronology

  • TRW: residual indices of tree-ring width chronologies

References

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.


Between-group synchrony for homoscedastic compound symmetry model

Description

The function calculates the between-group synchrony (a^) and standard error (SE) for homoscedastic compound symmetry model (mCS).

Usage

csbet.aSE(model)

Arguments

model

a class "lme" compound symmetry model (mCS) produced by dendro.varcov with homoscedastic equals TRUE.

Details

The function calculates between-group synchrony for homoscedastic compound symmetry model (mCS).

Value

The function returns a matrix containing between-group synchrony and SE for each combination of varGroup levels. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate between-group homoscedastic synchrony and SE
 # for compound symmetry homocedastic model of conifersIP data:
 data(conifersIP)
 
 #Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = TRUE)
 summary(ModHm)
   
 #Obtain the compound symmetry model between-group synchrony and SE
 # for each varGroup stratum.
 csbet.aSE (ModHm$mCS)#compound symmetry

Between-group synchrony for heteroscedastic compound symmetry model

Description

The function calculates the between-group synchrony (a^) and standard error (SE) for heteroscedastic compound symmetry model (mHeCS).

Usage

csbet.het.aSE(model)

Arguments

model

a class "lme" compound symmetry model (mHeCS) produced by dendro.varcov with homoscedastic equals FALSE.

Details

The function calculates between-group synchrony for heteroscedastic compound symmetry models (mHeCS).

Value

The function returns a matrix containing between-group synchrony and SE for each combination of varGroup levels. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate between-group synchrony and SE 
 ##for heteroscedastic compound symmetry model for conifersIP data:
 data(conifersIP)
 
 #Fit the heteroscedastic set of varcov models (mBE, mHeNE, mHeCS, mHeUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = FALSE)
 
 #between-group synchrony and SE for each varGroup stratum combination
 # in heteroscedastic compound symmetry models.
 csbet.het.aSE(ModHt$mHeCS)

Within-group synchrony for homoscedastic compound symmetry model

Description

The function calculates the within-group synchrony (a^) and standard error (SE) for homoscedastic compound symmetry models (mCS).

Usage

cswi.aSE(model)

Arguments

model

a class "lme" compound symmetry model (mCS) produced by dendro.varcov with homoscedastic equals TRUE.

Details

The function calculates within-group synchrony for homoscedastic compound symmetry model (mCS).

Value

The function returns a matrix containing within-group synchrony and SE for each combinations of varGroup levels. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate within-group homoscedastic synchrony and SE
 # for compound symmetry homocedastic model of conifersIP data:
 data(conifersIP)
 
 #Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = TRUE)
 summary(ModHm)
   
 #Obtain the compound symmetry model within-group synchrony and SE
 # for each varGroup stratum.
 cswi.aSE(ModHm$mCS)#compound symmetry

Within-group synchrony for heteroscedastic compound symmetry mixed models

Description

The function calculates for each varGroup stratum the synchrony (a^) and standard error (SE) for heteroscedastic compound symmetry models (mHeCS).

Usage

cswi.het.aSE (model)

Arguments

model

a class "lme" model produced by dendro.varcov with homoscedastic equals FALSE.

Details

The function calculates the within-group synchrony values for each varGroup stratum based on the metodology described in Shestakova et al. (2014) and Shestakova et al. (2016). Note that this function is designed to work only in heteroscedastic compound symmetry mixed models (i.e. mHeCS).

Value

The function returns a matrix containing within-group synchrony and SE for each level of varGroup. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate within-group heterosdecastic synchrony and SE for conifersIP data:
 data(conifersIP)
 
 #Fit the heteroscedastic set of varcov models (mBE, mHeNE, mHeCS, mHeUN)
 # using taxonomic grouping criteria (i.e. Species)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = FALSE)
 summary(ModHt)
   
 #Obtain the heteroscedastic compound symmetry 
 #within-group synchrony and SE for each varGroup stratum.
 cswi.het.aSE(ModHt$mHeCS)

Fit variance-covariance mixed models on tree-ring chronologies

Description

The function calculates variance-covariance (VCOV) mixed models from a data.frame with tree-ring width index and years for each chronology following the methodology described in Shestakova et al. (2014). The mixed models relate tree-ring width (Y) against specific names of tree-ring width chronologies (A), using years and grouping variable as random factors to characterize the strength of the common signal across the grouping variable. First, a linear mixed-effect model with null positive-definite matrix structure or broad evaluation is fitted and the subsequent models are consequently derived from it using the function update. When a data.frame with tree-ring width index has NAs the models are fitted with na.action = na.omit. Simultaneously, complete.cases is applied to guarantee that rows have no missing values across the entire data.frame.

Usage

dendro.varcov(formula, varTime = "", varGroup = "", data, 
                      homoscedastic = TRUE, null.mod = FALSE, all.mod = FALSE)

Arguments

formula

a model formula such as Y ~ A, where Y is usually tree-ring width and A will be a factor variable such as the specific names of tree-ring width chronologies (conifersIP) or ~1 for a null model.

varTime

a character specifying the time variable to consider in calculating synchrony estimates. Models with varTime variable with less than 10 different time-points 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.

homoscedastic

logical if TRUE models do not included an optional varFunc object. If FALSE models will include a one-sided formula describing the within-group heteroscedasticity structure (varIdent).

null.mod

logical if TRUE only broad evaluation model will be fitted. Default FALSE.

all.mod

logical if TRUE all homoscedastic and heteroscedastic model types will be fitted. Default FALSE.

Details

The function fits a set of variance-covariance mixed models following Shestakova et al. (2014). A total of 7 different variance-covariance mixed models can be fitted: a null positive-definite matrix structure (mBE), and the homoscedastic and heteroscedastic versions of a diagonal positive-definite matrix structure (mNE, mHeNE), a positive-definite matrix with compound symmetry structure (mCS, mHeCS) and a general positive-definite matrix structure (mUN, mHeUN). Note that if null.mod is TRUE the function only fits broad evaluation model (mBE), this is set to FALSE by default. If all.mod is TRUE the function fits heteroscedastic and homoscesdastic versions of all models. This is set to FALSE by default, because for large-datasets it may take a long time to converge.

Value

The function returns a list containing the following components:

  • for null.mod = TRUE:

mBE

an object of class "lme" representing the linear mixed-effects model fit of null positive-definite matrix structure or broad evaluation. See lmeObject for the components of the fit.

  • for homoscedastic = TRUE:

mNE

an object of class "lme" representing the linear mixed-effects model fit of a diagonal positive-definite matrix structure or narrow evaluation. See lmeObject for the components of the fit.

mCS

an object of class "lme" representing the linear mixed-effects model fit of a positive-definite matrix with compound symmetry structure. See lmeObject for the components of the fit.

mUN

an object of class "lme" representing the linear mixed-effects model fit of a general positive-definite matrix structure or unstructured. See lmeObject for the components of the fit.

  • for homoscedastic = FALSE:

mHeNE

an object of class "lme" representing the linear mixed-effects model fit of the heteroscedastic variant of a diagonal positive-definite matrix structure or narrow evaluation. See lmeObject for the components of the fit.

mHeCS

an object of class "lme" representing the linear mixed-effects model fit of the heteroscedastic variant of a positive-definite matrix with compound symmetry structure. See lmeObject for the components of the fit.

mHeUN

an object of class "lme" representing the linear mixed-effects model fit of the heteroscedastic variant of a general positive-definite matrix structure or unstructured. See lmeObject for the components of the fit.

  • for all.mod = TRUE:

The function returns the homoscedastic and heteroscedastic versions of all fitted models.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

lmeObject, na.action, complete.cases

Examples

## Calculate variance-covariance models on Iberian Peninsula conifers
 # chronologies using two different grouping strategies.
 # Tree-ring width chronologies are grouped according to taxonomic (i.e. Species)
 # or geographic (i.e. Region) criteria.
 #User-defined homoscedastic or heteroscedastic variances can be fitted.
 data(conifersIP)
 
 #Chop the data from 1960 to 1989.
 conif.30 <- conifersIP[conifersIP$Year>1959 & conifersIP$Year<1990,]
 summary(conif.30$Year)
 
 ##Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conif.30, homoscedastic = TRUE)
 
 summary(ModHm)# Class and length of list elements
 ModHm
 ModHm[2]#mNE fitted model results
 
 ##Fit the heteroscedastic set of varcov models (mBE, mHeNE, mHeCS, mHeUN) 
 # using geographic grouping criteria (ie. Region)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                        data = conif.30, homoscedastic = FALSE)
 
 summary(ModHt)# Class and length of list elements
 ModHt
 ModHt[3]#mHeCS fitted model results

Within-group synchrony for homoscedastic models

Description

The function calculates for each varGroup stratum the within-group synchrony (a^) and standard error (SE). However, it only works for homoscedastic broad evaluation, narrow evaluation and unstructured models (mBE, mNE, mUN).

Usage

gen.aSE(model)

Arguments

model

a class "lme" model produced by dendro.varcov with homoscedastic equals TRUE.

Details

The function calculates the within-group synchrony values for each varGroup stratum based on the metodology described in Shestakova et al. (2014) and Shestakova et al. (2016). Note that this function is designed to work only in 3 homoscedastic models (mBE, mNE, mUN).

Value

The function returns a matrix containing the synchrony and SE for each level of varGroup. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate within-group homoscedastic synchrony and SE for conifersIP data:
 data(conifersIP)
 
 #Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN) 
 # using taxonomic grouping criteria (ie. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                         data = conifersIP, homoscedastic = TRUE)
 summary(ModHm)
   
 #Obtain the within-group synchrony and SE for each varGroup stratum.
 gen.aSE(ModHm$mBE)#Broad evaluation
 gen.aSE(ModHm$mUN)#Unstructured

Within-group synchrony for heteroscedastic mixed models

Description

The function calculates for each varGroup stratum the synchrony (a^) and standard error (SE), but only for heteroscedastic unstructured and narrow evaluation mixed models (mHeNE, mHeUN).

Usage

gen.het.aSE (model)

Arguments

model

a class "lme" model produced by dendro.varcov with homoscedastic equals FALSE.

Details

The function calculates the within-group synchrony values for each varGroup stratum based on the metodology described in Shestakova et al. (2014) and Shestakova et al. (2016). Note that this function is designed to work only in heteroscedastic narrow evaluation and unstructured mixed models (ie. mHeNE and mHeUN).

Value

The function returns a matrix containing within-group synchrony and SE for each level of varGroup. This function is used internally in sync.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

sync for a clear description of synchrony evaluation.

Examples

## Calculate within-group heterosdecastic synchrony and SE for conifersIP data:
 data(conifersIP)
 
 #Fit the heteroscedastic set of varcov models (mBE, mHeNE, mHeCS, mHeUN)
 # using taxonomic grouping criteria (i.e. Species)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = FALSE)
 summary(ModHt)
   
 #Obtain the heteroscedastic within-group synchrony and SE for each varGroup stratum.
 gen.het.aSE(ModHt$mHeNE)#Narrow evaluation model
 gen.het.aSE(ModHt$mHeUN)#Unstructured model

Variances per varGroup stratum for heteroscedastic models

Description

The function obtains the heteroscedastic variances for each varGroup elements for a selected model (mHeCS, mHeUN, mHeNE).

Usage

het.var(model)

Arguments

model

a class "lme" model produced by dendro.varcov with homoscedastic equals FALSE.

Details

The function extracts the variances for each varGroup stratum using the within-group heteroscedastic structure of the fitted models (varIdent constant variance per stratum). Note that this function only works for heteroscedastic models: mHeCS, mHeNE,mHeUN.

Value

The function returns a numeric vector containing the variance per each level of varGroup. They are used internally to calculate synchrony (sync).

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

Examples

## Calculate within-group heteroscedastic variances for conifersIP data:
 data(conifersIP)
 
 #Fit the heteroscedastic set of models (mBE, mHeCS, mHeNE, mHeUN)
 # using taxonomic grouping criteria (i.e. Species)
 ModHt <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = FALSE)
 
 #Obtain the within-group variances for the model of interest
 het.var(ModHt$mHeCS)#Heterogeneous variant of compound symmetry model
 het.var(ModHt$mHeUN)#Heterogeneous unstructured model

Function to calculate goodness-of-fit statistics for variance-covariance models

Description

The function provides a table to compare fitted variance-covariance (VCOV) mixed models by AIC, AICc, BIC and LogLik. The restricted log-likelihood (LogLik) statistics for different models can be compared by Chi-square test, while Akaike information criterion (AIC), corrected Akaike information criterion (AICc) and Bayesian information criterion (BIC) are in the smaller-is-better form.

Usage

mod.table(modelList)

Arguments

modelList

a list of variance-covariance (VCOV) mixed models of the type as produced by dendro.varcov.

Details

The function returns a table to compare the fitted variance-covariance (VCOV) mixed models to the same data based on information criteria. The smaller AIC, AICc or BIC, the better fit. Also, LogLik value is included. AICc is calculated according to the formula AIC + 2*npar*(nobs/(nobs-npar-2)), where npar represents the number of parameters and nobs the number of observations in the fitted model.

Value

The function returns a data.frame with rows corresponding to the objects and columns containing the following components:

n

the number of observations used in the model fit.

df

the number of parameters in the fitted model.

AIC

Akaike's Information Criterion of the fitted model.

AICc

corrected Akaike's Information Criterion of the fitted model.

BIC

Bayesian Information Criterion of the fitted model.

LogLik

log-likelihood of the fitted model

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

References

Hurvich, C.M. & Tsai, C.L. (1989). Regression and time series model selection in small samples. Biometrika 76: 297-307.

See Also

AIC, BIC, logLik

Examples

## Compare homoscedastic variance-covariance models on Iberian Peninsula
 # conifer ring chronologies using taxonomic grouping criteria (i.e. Species).
 data(conifersIP)
 ModHmSp <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                          data = conifersIP, homoscedastic = TRUE)
 
 mod.table(ModHmSp)# a data.frame containing information criterion values

 ## Compare homoscedastic variance-covariance models on Iberian Peninsula conifers
 # ring chronologies using geographic criteria (ie. Region).
 ModHmGoe <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                           data = conifersIP, homoscedastic = TRUE)
 
 mod.table(ModHmGoe)

Calculate within- and between-group synchrony

Description

The function calculates spatial synchrony from a list of fitted mixed models with variance-covariance structures of the type as produced by dendro.varcov. Within- and between- varGroup level synchrony are calculated, quantifying the degree to which the values of N chronologies contain a common temporal signal. Different models allow for the estimation of intraclass correlations either at the intragroup or intergroup level. The underlying idea is to split the mean correlation estimated between all possible pairs of chronologies drawn from the whole dataset into: (i) a mean correlation between pairs of chronologies for every group; and (ii) a mean correlation between pairs of chronologies for pairs of groups.

Usage

sync (modelList, modname = c("mBE", "mNE", "mCS", "mUN", "mHeNE",
                                    "mHeCS", "mHeUN"), trend.mBE = FALSE)

Arguments

modelList

a list of the type as produced by dendro.varcov.

modname

a character string of "mBE", "mNE", "mCS", "mUN", "mHeNE", "mHeCS" or "mHeUN", specifying the variance-covariance structures selected for syncrony evaluation.

trend.mBE

a logical specifying if a broad evaluation model (mBE) output for each grouping level is reported. This is a special mBE output to plot synchrony trends with sync.trend.plot. Default FALSE.

Details

The function calculates the within- and between-group synchrony. For the more general (unstructured) model, the correlation of pairs of chronologies i and i* belonging to group r is:

rho(Wi,Wi)=cov(Wi,Wi)/sqrt(Var(Wi)Var(Wi))=sigma2yr/sigma2yr+sigma2erho(Wi,Wi*) = cov(Wi,Wi*)/sqrt(Var(Wi)*Var(Wi*)) = sigma^2yr/sigma^2yr+sigma^2e

Where Wi is tree-ring width of ith chronology, sigma^2yr is a covariance between observations Wi and Wi* belonging to a group r, sigma^2e is a random deviation within the rth group. Conversely, the correlation of pairs of chronologies i and i* belonging to groups r and r* is:

rho(Wi,Wi)=cov(Wi,Wi)/sqrt(Var(Wi)Var(Wi))=rho(Wi,Wi*) = cov(Wi,Wi*)/sqrt(Var(Wi)*Var(Wi*)) =

sigma2yr/sqrt((sigma2yr+sigma2e)+(sigma2yr+sigma2e))sigma^2yr*/sqrt((sigma^2yr+sigma^2e)+(sigma^2yr*+sigma^2e))

Note that if no modname is provided a warning message appears indicating that synchrony will be only calculated for the first modname vector element, i.e. broad evaluation model (mBE).

Value

The function returns a list containing the following components:

  • for within-group synchrony:

Modname

a column indicating the variance-covariance mixed models fit type:

  • mBE: null (or broad evaluation) structure.

  • mNE: homoscedastic variant of banded main diagonal (or narrow evaluation) structure.

  • mCS: homoscedastic variant of compound symmetry structure.

  • mUN: homoscedastic variant of unstructured (or full) structure.

  • mHeNE: heteroscedastic variant of banded main diagonal (or narrow evaluation) structure.

  • mHeCS: heteroscedastic variant of compound symmetry structure.

  • mHeUN: heteroscedastic variant of unstructured (or full) structure.

a_Group

a column representing the within-group synchrony.

SE_Group

standard error of each observation.

  • for between-group synchrony:

Modname

a column indicating the model fit type. See previous desription.

GroupName

a column indicating between-group varGroup pairwise combinations r and r*.

a_betw_Grp

a column indicating between-group varGroup synchrony.

SE_betw_Grp

standard error of each observation.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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.

See Also

dendro.varcov for models details.

Examples

## Calculate synchrony for null.model (broad evaluation, mBE) and homoscedastic variant
 # of unstructured model (or full, mUN) for conifersIP data, 
 # and heteroscedastic variant for 1970-1999 period.
 data(conifersIP)
 
 ##Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN) 
 #using taxonomic grouping criteria (i.e. Species)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                        data = conifersIP, homoscedastic = TRUE)
 
 summary(ModHm)# Class and length of list elements
 
 #Synchrony for mBE and mUN models
 sync(ModHm, modname = "mBE")
 sync(ModHm, modname = "mUN")
 
 ##Chop the data from 1970 to 1999.
 conif.30 <- conifersIP[conifersIP$Year>1969 & conifersIP$Year<2000,]
 summary(conif.30$Year)
 
 #Fit the heteroscedastic set of variance covariance mixed models (mBE, mHeNE, mHeCS, mHeUN)
 # using taxonomic grouping criteria (ie. Species)
 ModHt30 <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Species", 
                          data = conif.30, homoscedastic = FALSE)
 sync(ModHt30, modname = "mBE")
 sync(ModHt30, modname = "mHeUN")

Plot within- and between-group synchrony

Description

The function creates dot plots of within- and between-group synchrony as produced by sync from a selected model produced by dendro.varcov. Note that broad evaluation model (mBE) can not be plotted since it produces only one value per model.

Usage

sync.plot (syncList)

Arguments

syncList

a list of the type as produced by sync.

Details

The function makes a dot plots for within- and between-group synchrony for a user defined varGroup and varTime period in dendro.varcov.

Value

Dotplot

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

Examples

## Plot homoscedastic narrow evaluation (mNE) and unstructured model (mUN)
 # synchronies for conifersIP data:
 data(conifersIP)
     
 ##Fit the homoscedastic set of varcov models (mBE, mNE, mCS, mUN)
 # using geographic grouping criteria (ie. Region)
 ModHm <- dendro.varcov(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                        data = conifersIP, homoscedastic = TRUE)
 
 sync.plot(sync(ModHm, modname = "mNE"))
 sync.plot(sync(ModHm, modname = "mUN"))

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.

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).

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).

SE

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.

SE

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.

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

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

## 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
 
## End(Not run)

Plot temporal trends of synchrony

Description

The function creates a line chart showing temporal trends of spatial synchrony from data.frame of the type as produced by sync.trend.

Usage

sync.trend.plot (sync.trend.data)

Arguments

sync.trend.data

a data.frame of the type as produced by sync.trend.

Details

The function makes a line chart showing synchrony trends across years from a data.frame produced by sync.trend. Within- or between- group synchrony and SE are indicated for a selected time window. If synchrony is defined using using null.mod = TRUE (sync.trend) only general synchrony is ploted. If synchrony is defined using using null.mod = FALSE (sync.trend) different synchronies for each group variable (varGroup) are fitted with different colours for each stratum.

Value

Line chart

Author(s)

Josu G. Alday, Tatiana A. Shestakova, Victor Resco de Dios, Jordi Voltas

Examples

## Calculate temporal trends of 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
 sync.trend.plot(mBE.trend)# Broad evaluation synchrony linechart

## 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 synchrony for each time window.
 sync.trend.plot(geo.trend)#Selected heteroscedastic between-group trends by AIC
 
 ##Fit heteroscedastic betwen-group trends (mBE, mHeNE, mHeCS, mHeUN) 
 # using geographic grouping criteria (i.e. Region) and AICc
 geo.het.trend <- sync.trend(TRW ~ Code, varTime = "Year", varGroup = "Region", 
                    data = conifersIP, window = 30, lag = 5, null.mod = FALSE, 
                    selection.method = c("AICc"), homoscedastic = FALSE, between.group = TRUE)
 
 geo.het.trend
 sync.trend.plot(geo.het.trend)#Selected heteroscedastic between-group trends by AICc
 
 ##Fit homoscedastic and heteroscedastic 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"),
                    null.mod = F, all.mod = TRUE)
 geo.tot.trend
 #Selected homoscedastic and heteroscedastic within-group trends by BIC
 sync.trend.plot(geo.tot.trend)
 
## End(Not run)