README: Data and code for: Nonlinear life table response experiment analysis: decomposing nonlinear and nonadditive population growth responses to changes in environmental drivers

---

Access this dataset and code on Dryad: https://doi.org/10.5061/dryad.p8cz8w9wg

Overview

The goal of the manuscript (O'Connell et al., 2024) supported by the data and code described here was to compare linear and second-order life table response experiment (LTRE) analyses in order to determine whether a second-order (i.e., nonlinear) LTRE better captures observed changes in population growth rate relative to the more commonly used linear approach. To investigate this question, we analyzed demographic data for three long-lived plant species: Ardisia escallonioides, Silene acaulis, and Bistorta vivipara. This repository contains data and vital rate models files for each of these three species as well as an R script where we calculate the linear and second-order LTRE values and generate the figures we present in our paper. See below for further details on the data and code.

Description of data files

Producing linear and second-order LTRE approximations requires demographic datasets that include either vital rate observations (i.e., observations of survival, growth, and reproduction for individual organisms or averaged across classes in a structured population model) or vital rate model parameters determined in previous analyses of a demographic dataset. Because our analysis is focused on understanding how population growth rate changes in response to changing environmental conditions, data on these environmental drivers are also needed. Below we describe the contents of each data file required to reproduce our analyses; we also define all tabular data variables and provide their units, where applicable.

Ardisia escallonioides:

The data file for our Ardisia case study ("ardisia_input.RData") contains vital rate observations for each size class at various levels of forest canopy percent openness (the relevant environmental driver). These values were extracted from the projection matrices reported in Pascarella & Horvitz (1998). In this RData file, there are four data tables (corresponding to the four vital rates relevant to this system: survival, growth, fecundity (fec), and reversion (revert)), each of which includes the following four columns:

   size: categorical label of size class (juvenile, preadult, small, medium, and large)

   patchtype: observed value of percent canopy openness (the single environmental driver in this system)

   rate: vital rate name (survival, growth, fecundity, or reversion to smaller size class)

   value: observed vital rate value as reported by Pascarella & Horvitz (1998)

Bistorta vivipara & Silene acaulis:

The data files for our Bistorta and Silene case studies ("bistort_input.RData" and "silene_input.RData", respectively) contain vital rate model parameters first calculated by Doak & Morris (2010) and reported in the Supplementary Information of their paper, along with observations of the environmental drivers relevant to these two species: mean July temperature, snow-free period, and precipitation.

The data tables "bistort_driver_limits" and "sil_driver_limits" define the mean, minimum, and maximum driver conditions for our analysis based on field observations of the study populations. The column descriptions and units (where relevant) are as follows:

   region: study region label; 1-4 (see Doak & Morris, 2010, for study site map)

   population: study population label within each region

   unique_pop_ID: unique population identifier for this species

   mtj_mean: mean value of mean July temperature across five-year study period (degrees C)

   mtj_min: minimum value of mean July temperature across five-year study period (degrees C)

   mtj_max: maximum value of mean July temperature across five-year study period (degrees C)

   sp_mean: mean value of snow-free period across five-year study period (days)

   sp_min: minimum value of snow-free period across five-year study period (days)

   sp_max: maximum value of snow-free period across five-year study period (days)

   pre_mean: mean value of annual precipitation across five-year study period (mm; Bistorta only)

   pre_min: minimum value of annual precipitation across five-year study period (mm; Bistorta only)

   pre_max: maximum value of annual precipitation across five-year study period (mm; Bistorta only)

The data tables "bistort_drivers" and "sil_drivers" provide mean values of the environmental drivers at each population of both species. These tables include the following columns:

   region: study region label

   pop: population label within each region

   snowfree: mean value of snow-free period across five-year study period (days)

   mtj: mean value of mean July temperature across five-year study period (degrees C)

   pre: mean value of annual precipitation across five-year study period (mm; Bistorta only)

Lastly, the data table "sildata" provides additional data needed to generate a new fruits per unit area model for Silene acaulis, as described in further detail in the Supporting Information of our paper. This table includes the following columns:

   size: size class (s=small; m=medium; l=large)

   SP: observed snow-free period (days)

   MTJ: observed mean July temperature (degrees C)

   frtsarea: fruits per unit area (number of fruits/cm^2)

Full details on data collection for each of these species can be found in the original studies, references for which are provided below.

Description of code

The R script "R-code_OConnell_et_al.R" takes the data inputs above and generates linear and second-order LTRE approximations of change in population growth rate for a given set of environmental driver ranges. We have written the code for all three case studies separately, but each follows the order of operations described below.

Loading the data: Loading the three Rdata files listed above is required in order to run all sections of the code. The R script must and data input files must be located in the same file directory in order for the inputs to be loaded properly.

Getting vital rate models: For each case study, the first step after loading the data is to produce driver-dependent vital rate models that will generate vital rate values (and subsequently populate a projection matrix) for a given environmental driver value(s). This is conducted by running the code sub-sections labeled "a. System parameters & vital rate models".

Estimating changes in population growth rate: The next step is to run the functions corresponding to the individual terms in the linear and second-order LTRE approximations in Box 1 of our paper. The easiest way to do this is by executing the code sub-sections labeled "b. Functions to calculate first- and second-order LTRE estimates of change in growth rate" and then running the functions beginning with "full.decomp.(species)" for each case study, which generates the results we present in our paper.

Plotting results: The final section of the code produces the figures in our paper. To recreate these figures, the code in section 4 (beginning on line 2560) should be executed after running sections 1-3 (the three case studies). However, because these sections can take a long time to run (up to a few hours for the Bistorta vivipara case in particular, which has a large number of vital rates and therefore requires many more calculations), we have also provided a file ("all_output.RData") that contains the output of the R code run for each of the three case studies. Loading this file and then running the code for the plots allows the figures to be generated without needing to first run the R functions that calculate the LTRE approximation values.

All code was written using R v. 4.1.2 (R Core Team, 2022). Required packages are listed in the script beginning on line 27.

References

Doak, D. F., & Morris, W. F. (2010). Demographic compensation and tipping points in climate-induced range shifts. Nature, 467(7318), 959–962. https://doi.org/10.1038/nature09439

Pascarella, J. B., & Horvitz, C. C. (1998). Hurricane Disturbance and the Population Dynamics of a Tropical Understory Shrub: Megamatrix Elasticity Analysis. Ecology, 79(2), 547-563. https://doi.org/10.1890/0012-9658(1998)079[0547:HDATPD]2.0.CO;2

R Core Team (2022). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. https://www.R-project.org/.