DOI: 10.5061/dryad.p8cz8w9wg
title: Data and code for: Nonlinear life table response analysis: Decomposing nonlinear and nonadditive population growth responses to changes in environmental drivers

description: Life table response experiments (LTREs) decompose differences in
 population growth rate between environments into separate contributions
 from each underlying demographic rate. However, most LTRE analyses make
 the unrealistic assumption that the relationships between demographic
 rates and environmental drivers are linear and independent, which may
 result in diminished accuracy when these assumptions are violated. In this
 study, we compare the relative efficacy of linear and second-order LTRE
 analyses in capturing changes in population growth rate caused by
 environmental driver changes. To explore this question, we analyze
 demographic data collected for three long-lived plant
 species: Ardisia escallonioides (Pascarella & Horvitz,
 1998), Silene acaulis, and Bistorta vivipara (Doak & Morris,
 2010). This repository includes data files containing vital rate
 (survival, growth, reproduction) observations or models for our three case
 studies, as well as an R script in which we use these demographic data to
 calculate linear and second-order LTRE approximations of changes in
 population growth rate for each system and generate the figures we present
 in our paper.
description: # 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/.