DendroSync (version 0.1.4)

dendro.varcov: 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.

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:

all.mod

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

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.

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

# NOT RUN {
## 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
       
                   
# }