---
title: "Lathyrus vernus function-based age-by-stage MPMs"
author: Richard P. Shefferson, Shun Kurokawa, and Johan Ehrlén
output: rmarkdown::html_vignette
bibliography: Lefko3Tutorial.bib
vignette: >
  %\VignetteIndexEntry{Lathyrus vernus function-based age-by-stage MPMs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



  <p style="text-indent: 20px">This document was built in Markdown in R 4.0.4 and compiled on 01 April 2021. It covers package `lefko3` version 3.4.0. Please note that this vignette was written with space considerations in mind. To reduce output size, we have prevented some statements from running if they produce long stretches of output. Examples include most `summary()` calls. In these cases, we include hashtagged versions of these calls, and our text assumes that the user runs these statements without hashtags.</p>

## CASE STUDIES OF SWEDISH *Lathyrus vernus* POPULATION

  <p style="text-indent: 20px">In this vignette, we use the `lathyrus` dataset to illustrate the estimation of **age-by-stage function-based MPMs**. Please see the other vignettes included in package `lefko3`, as well as further vignettes posted online on <a href = "http://www.sheffersonlab.com/projects">the projects page</a> of the Shefferson lab website, for further demonstrations of raw MPMs, function-based MPMs, IPMs, and age-by-stage MPMs.

### ORGANISM AND POPULATION

  <p style="text-indent: 20px">*Lathyrus vernus* (family Fabaceae) is a long-lived forest herb, native to Europe and large parts of northern Asia. Individuals increase slowly in size and usually flower only after 10-15 years of vegetative growth. Flowering individuals have an average conditional lifespan of 44.3 years [@ehrlen_how_2002]. *Lathyrus vernus* lacks organs for vegetative spread and individuals are well delimited [@ehrlen_assessing_2002]. One or several erect shoots of up to 40 cm height emerge from a subterranean rhizome in March-April. Flowering occurs about four weeks after shoot emergence. Shoot growth is determinate, and the number of flowers is determined in the previous year [@ehrlen_storage_2001]. Individuals may not produce aboveground structures every year but can remain dormant in one season. *Lathyrus vernus* is self-compatible but requires visits from bumble-bees to produce seeds. Individuals produce few, large seeds and establishment from seeds is relatively frequent [@ehrlen_seedling_1996]. The pre-dispersal seed predator *Bruchus atomarius* often consumes a large fraction of developing seeds, and roe deer (*Capreolus capreolus*) sometimes consume the shoots [@ehrlen_timing_2009].</p>
  
  <p style="text-indent: 20px">Data for this study were collected from six permanent plots in a population of *L. vernus* located in a deciduous forest in the Tullgarn area, SE Sweden (58.9496 N, 17.6097 E), during 1988–1991 [@ehrlen_demography_1995]. The six plots were relatively similar with regard to soil type, elevation, slope, and canopy cover. Within each plot, all individuals were marked with numbered tags that remained over the study period, and their locations were carefully mapped. New individuals were included in the study in each year. Individuals were recorded at least three times every growth season. At the time of shoot emergence, we recorded whether individuals were alive and produced above-ground shoots, and if shoots had been grazed. During flowering, we recorded flower number and the height and diameter of all shoots. At fruit maturation, we counted the number of intact and damaged seeds. To derive a measure of above-ground size for each individual, we calculated the volume of each shoot as $\pi × (\frac{1}{2} diameter)^2 × height$, and summed the volumes of all shoots. This measure is closely correlated with the dry mass of aboveground tissues ($R^2 = 0.924$, $P < 0.001$, $n = 50$, log-transformed values; Ehrlén 1995). Size of individuals that had been grazed was estimated based on measures of shoot diameter in grazed shoots, and the relationship between shoot diameter and shoot height in non-grazed individuals. Only individuals with an aboveground volume of more than 230 mm<sup>3</sup> flowered and produced fruits during this study. Individuals that lacked aboveground structures in one season but reappeared in the following year were considered dormant. Individuals that lacked aboveground structures in two subsequent seasons were considered dead from the year in which they first lacked aboveground structures. Probabilities of seeds surviving to the next year, and of being present as seedlings or seeds in the soil seed bank, were derived from separate yearly sowing experiments in separate plots adjacent to each subplot [@ehrlen_seedling_1996].</p>

### OVERALL GOALS AND INITIAL CONSIDERATIONS
  
  <p style="text-indent: 20px">Our goal in this exercise will be to produce ahistorical, age-by-stage function-based matrices using the *Lathyrus* dataset. To spice things up, we will use a slightly different approach to size classification, using the natural log of size instead of the normal size shown in the dataset. Our reasoning has to do with the fact that volume is used as the size metric here, and so should have an allometric relationship to some vital rates (note that all size metrics have allometric relationships, but this is clearer when size is based on something more strongly related to mass, as is volume). We will also create both reproductive or non-reproductive stages of the same size classes.</p>

  <p style="text-indent: 20px">The dataset that we have provided is organized in horizontal format, meaning that each row holds all of the data for a single, unique individual, and columns correspond to individual condition in particular observation times (which we refer to as *years* here, since there was one main census in each year). The original Excel spreadsheet used to keep the dataset has a repeating pattern to these columns, with each year having a similarly arranged group of variables. Package `lefko3` includes functions to handle data in horizontal format based on these patterns, as well as functions to handle vertically formatted data (i.e. data for individuals is broken up across rows, where each row is a unique combination of individual and year in time *t*).</p>

<img src = "lathscreen1.png" width = "700"></img>
**Figure 8.1.** Organization of the *Lathyrus* dataset, as viewed in Microsoft Excel.

  <p style="text-indent: 20px">This dataset includes information on 1,119 individuals, so there are 1,119 rows with data (not counting the header). There are 38 columns. The first two columns are variables giving identifying information about each individual (`SUBPLOT` refers to the patch, and `GENET` refers to individual identity), with each individual's data entirely restricted to one row. This is followed by four sets of nine columns, each named `VolumeXX`, `lnVolXX`, `FCODEXX`, `FlowXX`, `IntactseedXX`, `Dead19XX`, `DormantXX`, `Missing19XX`, and `SeedlingXX`, where `XX` corresponds to the year of observation and with years organized consecutively. Thus, columns 3-11 refer to year 1988, columns 12-20 refer to year 1989, etc. For `lefko3` to handle this dataset correctly, we need to know the exact number of years used, which is 4 years here (includes all years from and including 1988 to 1991), we need the columns to be repeated in the same order for each year, and we need years in consecutive order with no extra columns between them.</p>

  <p style="text-indent: 20px">First, let's clear memory and load the dataset.</p>

```r
rm(list=ls(all=TRUE))
library(lefko3)
data(lathyrus)
#summary(lathyrus)
```

#### Step 1. Life history model development

  <p style="text-indent: 20px">To begin, we need to create a **stageframe** for this dataset. A stageframe is a data frame that describes all stages in the life history of the organism, in a way usable by the functions in this package and using stage names and classifications that completely match those used in the dataset. It needs to include complete descriptions of all stages that occur in the dataset, with each stage defined uniquely. Since this object can be used for automated classification of individuals, all sizes, reproductive states, and other characteristics defining each stage in the dataset need to be accounted for explicitly. This can be difficult if a few data points exist outside the range of sizes specified in the stageframe, so great care must be taken to include all size values and values of other descriptor variables occurring within the dataset. The final description of each stage occurring in the dataset must not completely overlap with any other stage also found in the dataset, although partial overlap is allowed and expected. We will base our stageframe on the life history model provided in Ehrlén [-@ehrlen_dynamics_2000], but we will use the different size classification we just described to allow age-by-stage MPM construction.</p>
  
  <p style="text-indent: 20px">Before creating the stage frame, let's explore the possible size variables. We will particularly look at summaries of the distribution of original and log sizes.</p>

```r
summary(c(lathyrus$Volume88, lathyrus$Volume89, lathyrus$Volume90, lathyrus$Volume91))
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.    NA's 
#>     1.8    14.7   123.0   484.2   732.5  7032.0    1248
summary(c(lathyrus$lnVol88, lathyrus$lnVol89, lathyrus$lnVol90, lathyrus$lnVol91))
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.    NA's 
#>   0.600   2.700   4.800   4.777   6.600   8.900    1248
```
  
  <p style="text-indent: 20px">The lower line shows the original size (upper line) given in logarithmic terms. It is important to note the size minima and maxima, because we have been using 0 as the size of vegetatively dormant individuals. The lowest uncorrected size is , with a maximum of . The minimum corrected size is , and the maximum corrected size is . Since the minimum corrected size is above 0 (i.e. all log sizes should be positive), and since the number of NAs has not increased (increased NAs would suggest some unuseable log sizes occur in the dataset), we are still able to use the log size value 0 as an indicator of vegetative dormancy (hote, however, through exploration of the dataset that vegetative dormancy is currently included in the many NAs that occur in size variables in this dataset).</p>
  
  <p style="text-indent: 20px">It can also help to take a look at plots of these distributions. We will plot raw volume on the left and log volume on the right.</p>

```r
par(mfrow=c(1,2))
plot(density(c(lathyrus$Volume88, lathyrus$Volume89, lathyrus$Volume90,
    lathyrus$Volume91), na.rm = TRUE), main = "", xlab = "Volume", bty = "n")
plot(density(c(lathyrus$lnVol88, lathyrus$lnVol89, lathyrus$lnVol90,
    lathyrus$lnVol91), na.rm = TRUE), main = "", xlab = "Log volume", bty = "n")
```

![Figure 8.2. Density plot of aboveground plant volume](Ch8.2-1.png)

  <p style="text-indent: 20px">Note how highly skewed thraw volume distribution looks. This might cause some difficulty with linear modeling, if we use this variable untransformed and with a Gaussian distribution. The log volume distribution looks 'better' than the raw volume distribution, in the sense that it is closer to some semblance of a Gaussian distribution (primarily through symmetry). This is helpful since our size metrics are decimals, and so cannot be treated as integers. If they could be treated as integers, then we could try modeling size as either Poisson- or negative binomial-distributed. We will work with log volume in this example, and treat it as Gaussian-distributed.</p>
  
  <p style="text-indent: 20px">We will now develop a stageframe that incorporates the log volume of size. We will build this by creating vectors of the values describing each stage, always in the same order.</p>

```r
sizevector <- c(0, 4.6, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3, 4, 5, 6, 7, 8, 9)
stagevector <- c("Sd", "Sdl", "Dorm", "Sz1nr", "Sz2nr", "Sz3nr", "Sz4nr",
  "Sz5nr","Sz6nr", "Sz7nr", "Sz8nr", "Sz9nr", "Sz1r", "Sz2r", "Sz3r", "Sz4r",
  "Sz5r", "Sz6r", "Sz7r", "Sz8r", "Sz9r")
repvector <- c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1)
obsvector <- c(0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
immvector <- c(1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 4.6, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 
            0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5)
minima <- c(0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
maxima <- c(NA, 1, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,
  NA, NA, NA, NA, NA)
comments <- c("Dormant seed", "Seedling", "Dormant", "Size 1 Veg", "Size 2 Veg",
  "Size 3 Veg", "Size 4 Veg", "Size 5 Veg", "Size 6 Veg", "Size 7 Veg",
  "Size 8 Veg", "Size 9 Veg", "Size 1 Flo", "Size 2 Flo", "Size 3 Flo",
  "Size 4 Flo", "Size 5 Flo", "Size 6 Flo", "Size 7 Flo", "Size 8 Flo",
  "Size 9 Flo")
lathframeln <- sf_create(sizes = sizevector, stagenames = stagevector,
  repstatus = repvector, obsstatus = obsvector, propstatus = propvector, 
  immstatus = immvector, matstatus = matvector, indataset = indataset,
  binhalfwidth = binvec, minage = minima, maxage = maxima, comments = comments)
#lathframeln
```

  <p style="text-indent: 20px">So everything is set! Let's now move on to organizing the dataset.</p>
  
#### Step 2a. Data organization

  <p style="text-indent: 20px">Once the stageframe is created, we can reorganize the dataset into historically-formatted vertical (hfv) format. Here, 'vertical' format is a way of organizing demographic data in which each row corresponds to the state of a single individual in two (if ahistorical) or three (if historical) consecutive times. To handle this, we use the `verticalize3()` function, which creates historically-formatted vertical datasets, as below. We also need to get rid of NAs in size and fecundity variables for `modelsearch` to work properly when we build models of vital rates, so we will now use the `NAas0 = TRUE` option. Some care needs to be taken with this last step, since some authors give missing values extra meaning not present in a value of 0. In our case, a missing value indicates that a plant was dead (both size and fecundity are missing), was alive but not sprouting (size was missing), or did not produce seed (fecundity was missing). In all cases, these NA values may be replaced by 0, because other variables indicate those conditions.</p>
  
  <p style="text-indent: 20px">We also have two choices for fecundity variables. The first choice, `FCODE88` indicates whether a plant flowered. The second choice, `Intactseed88`, indicates the number of seed produced, and so will also be used as the fecundity variable. The choice of which to use depends strongly on the aims of the study. In our case, we would like to treat all plants that flowered as reproductive, but treat fecundity in terms of real seed produced. The reason for this is that we believe that flowering plants have a different demography than non-flowering plants, either reflecting reproductive costs, or, conversely, because flowering plants might have more resources and hence higher survival than non-flowering plants, and so we wish to separate transitions among these two groups. So, let's use `FCODE88` to indicate reproductive status, and `Intactseed88` to indicate fecundity. Once complete, we will look at a summary.</p>

```r
lathvertln <- verticalize3(lathyrus, noyears = 4, firstyear = 1988,
  patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9,
  juvcol = "Seedling1988", sizeacol = "lnVol88", repstracol = "FCODE88",
  fecacol = "Intactseed88", deadacol = "Dead1988",
  nonobsacol = "Dormant1988", stageassign = lathframeln,
  stagesize = "sizea", censorcol = "Missing1988", censorkeep = NA,
  NAas0 = TRUE, censor = TRUE)
#summary(lathvertln)
```
  
  <p style="text-indent: 20px">Before we move on to the next key steps in analysis, let's take a closer look at fecundity. In this dataset, fecundity is mostly a count of intact seeds, and only differs in six cases where the seed output was estimated based on other models. To see this, try the following code.</p>

```r
writeLines(paste0("Total length of variable corresponding to fecundity in time t+1: ", length(lathvertln$feca3)))
#> Total length of variable corresponding to fecundity in time t+1: 2527
writeLines(paste0("Total non-integer entries in fecundity in time t+1: ", length(which(lathvertln$feca3 != round(lathvertln$feca3)))))
#> Total non-integer entries in fecundity in time t+1: 0
writeLines(paste0("\nTotal length of variable corresponding to fecundity in time t: ", length(lathvertln$feca2)))
#> 
#> Total length of variable corresponding to fecundity in time t: 2527
writeLines(paste0("Total non-integer entries in fecundity in time t: ", length(which(lathvertln$feca2 != round(lathvertln$feca2)))))
#> Total non-integer entries in fecundity in time t: 6
writeLines(paste0("\nTotal length of variable corresponding to fecundity in time t-1: ", length(lathvertln$feca1)))
#> 
#> Total length of variable corresponding to fecundity in time t-1: 2527
writeLines(paste0("Total non-integer entries in fecundity in time t-1: ", length(which(lathvertln$feca1 != round(lathvertln$feca1)))))
#> Total non-integer entries in fecundity in time t-1: 6
```
  
  <p style="text-indent: 20px">We see that we have quite a bit of fecundity data, and that it is overwhelmingly but not exclusively composed of integer values. So, we can either treat fecundity as a continuous variable, or round the values and treat it as a count variable. We will round fecundity so that we can treat fecundity as a count variable in the analysis.</p>

```r
lathvertln$feca3 <- round(lathvertln$feca3)
lathvertln$feca2 <- round(lathvertln$feca2)
lathvertln$feca1 <- round(lathvertln$feca1)
```

  <p style="text-indent: 20px">The fact that fecundity is now integer-based suggests that it can be treated as a count variable. This package currently allows 7 choices of count distributions: Gaussian, Poisson, negative binomial, zero-inflated Poisson, zero-inflated negative binomial, zero-truncated Poisson, and zero-truncated negative binomial. To assess which to use, we should first assess whether the mean and variance of the count are equal using a dispersion test. This test allows us to test whether the variance is greater than that expected under our mean value for fecundity using a chi-squared test. If it is not significantly different, then we may use some variant of the Poisson distribution. If the data are overdispersed, then we should use the negative binomial distribution. We should also test whether the number of zeroes is more than expected under these distributions, and make the distribution zero-inflated if so. Note that, because we have not excluded 0s from fecundity using reproductive status, we should not use a zero-truncated distribution.</p>
  
  <p style="text-indent: 20px">Let's start off by looking at a bar plot of the distribution of fecundity.</p>

```r
hist(subset(lathvertln, repstatus2 == 1)$feca2, main = "Fecundity", xlab = "Intact seeds produced in time t")
```

![Figure 8.3. Histogram of fecundity in time t](Ch8.7-1.png)

  <p style="text-indent: 20px">We see that the distribution conforms to a classic count variable with a very low mean value. The first bar suggests that there may be too many zeroes, as well, although it is not clear. Let's look at a finer scale plot.</p>

```r
hist(subset(lathvertln, repstatus2 == 1)$feca2[which(subset(lathvertln, repstatus2 == 1)$feca2 < 11)], 
     xlim = c(0, 10), main = "Fecundity", xlab = "Intact seeds produced in time t")
```

![Figure 8.4. Histogram of fecundity in time t, only cases with <10 seeds produced](Ch8.8-1.png)

  <p style="text-indent: 20px">We see very many zeroes here, relative to the rest of the distribution. Let's now go to a formal test of these two assumptions. Both use chi-squared distribution-based approaches, with the zero-inflation test in particular based on van der Broek [-@van_den_broek_score_1995].</p>

```r
sf_distrib(lathvertln, size2 = "sizea2", fec = "feca2", repst = "repstatus2")
#> 
#> Mean fecundity is 4.791
#> The variance in fecundity is 70.14
#> The probability of this dispersion level by chance assuming the true mean fecundity = variance in fecundity, and an alternative hypothesis of overdispersion, is 0
#> 
#> Fecundity is significantly overdispersed.
#> 
#> 
#> Mean lambda is 0.008302
#> The actual number of 0s in fecundity is 334
#> The expected number of 0s in fecundity under the null hypothesis is 4.973
#> The probability of this deviation in 0s is 0
#> 
#> Fecundity is significantly zero-inflated.
#> NULL
```

  <p style="text-indent: 20px">Such significant results for both tests show us that we really need to use a zero-inflated negative binomial distribution here. Now let's move on to supplemental descriptive information.</p>
  
#### Step 2b. Provide supplemental information for matrix estimation

  <p style="text-indent: 20px">Matrix estimation functions in package `lefko3` are made to work with **supplemental tables**, which provide extra data for matrix estimation that is not included in the main demographic dataset. The `supplemental()` function provides a means of inputting three kinds of data into MPM construction:</p>
  
  1. fixed transition values derived from other studies and added as constants to matrices,
  2. proxy transition values when data for particular transitions does not exist and other, estimable transitions need to be used as proxies, and
  3. reproductive multipliers to indicate which stages leading to the production of which stages, and at what level relative to estimated fecundity.
  
  <p style="text-indent: 20px">Here, we will create an ahistorical supplement table taking all of these sorts of data. Each row refers to a specific transition. The first 2 of these transitions are set to specific probabilities, which are the probabilities of germination and seed dormancy, estimated from a separate study. The final 2 terms are fecundity multipliers, which mark which transitions correspond to fecundity and provide information on what multiple of fecundity estimated via linear modeling applies to each case. Note that we can also include proxy transitions, in which we define a specific transition as being equal to another in the matrix. The latter approach is useful when some transitions cannot be estimated given a particular dataset, and so need to be set to other, proxy values that are estimable.</p>

```r
lathsupp2 <- supplemental(stage3 = c("Sd", "Sdl", "Sd", "Sdl"), 
  stage2 = c("Sd", "Sd", "rep", "rep"),
  givenrate = c(0.345, 0.054, NA, NA),
  multiplier = c(NA, NA, 0.345, 0.054),
  type = c(1, 1, 3, 3), stageframe = lathframeln, historical = FALSE)
#lathsupp2
```

#### Step 3. Tests of history, and vital rate modeling

  <p style="text-indent: 20px">Next we will run the `modelsearch` function with the new vertical dataset. This function will develop our best-fit vital rate models for us. This function looks simple, but it automates several crucial and complex tasks in MPM analysis. Specifically, it automates 1) the building of global models for each vital rate requested, 2) the exhaustive construction of all reduced models, and 3) the selection of the best-fit models.</p>
  
  <p style="text-indent: 20px">Let's look at some of the options that we will utilize for this purpose (please note that this list includes only some of the options actually offered by the function - further options are shown in the documentation for `modelsearch()`, and further theoretical details are shown in the `Basic theory and concepts` vignette).</p>
  
  **historical**: Setting this to TRUE or FALSE indicates to include state in time *t*-1 in the global models.
  
  **approach**: Designates whether to use generalized linear models (`glm`), in which all factors are treated as fixed, or mixed effects models (`mixed`), in which factors are treated as either fixed or random (most notably, time, patch, and individual identity can be treated as random). We encourage users to use the latter option, as it accounts for pseudoreplication, but the former approach is more common.
  
  **suite**: Designates which factors to include in the global model. Possible values include `size`, which includes size only; `rep`, which includes reproductive status only; `main`, which includes both size and reproductive status as main effects only; `full`, which includes both size and reproductive status and all two-way interactions; and `const`, which includes only an intercept. These factors are in addition to individual identity, patch, and time.
  
  **vitalrates**: Designates which vital rates to model. The default is to model survival, size, and fecundity, but users can also model observation status and reproduction status.
  
  **juvestimate**: Designates the name of the juvenile stage transitioning to maturity, in cases where the dataset includes data on juveniles.
  
  **juvsize**: Denotes whether size should be used as an independent term in models involving transition from the juvenile stage.
  
  **bestfit**: Denotes whether the best-fit model should be chosen as the model with the lowest AICc (`AICc`) or as the most parsimonious model (`AICc&k`), where the latter is the model that has the fewest estimated parameters and is within 2 AICc units of the model with the lowest AICc. We encourage users to choose the latter. This is the default setting, and is more in-line with model selection protocols preferred by information theorists [@burnham_model_2002]..
  
  **sizedist**: Designates the distribution used for size. The options include `gaussian`, `poisson`, and `negbin`, the last of which refers to the negative binomial distribution.
  
  **fecdist**: Designates the distribution used for fecundity. The options include `gaussian`, `poisson`, and `negbin`, the last of which refers to the negative binomial distribution.
  
  **fectime**: Designates whether fecundity is estimated within time *t* (the default) or time *t*+1. Plant ecologists are likely to choose the former, since fecundity is typically estimated via a proxy such as flowers, fruit, or seed produced. Wildlife ecologists might choose the latter, since fecundity may be best estimated as a count of actual juveniles within nests, burrows, or other family structures.
  
  **size.zero**: Designates whether the size distribution should be zero-inflated. Only applies to the Poisson and negative binomial distributions.
  
  **size.trunc**: Designates whether to use a zero-truncated distribution for size. Only applies to the Poisson and negative binomial distributions, and cannot be applied is `size.zero = TRUE`.
  
  **fec.zero**: Designates whether the fecundity distribution should be zero-inflated. Only applies to the Poisson and negative binomial distributions.
  
  **fec.trunc**: Designates whether to use a zero-truncated distribution for fecundity. Only applies to the Poisson and negative binomial distributions, and cannot be applied is `fec.zero = TRUE`.
  
  **jsize.zero**: Designates whether the juvenile size distribution should be zero-inflated. Only applies to the Poisson and negative binomial distributions.
  
  **jsize.trunc**: Designates whether to use a zero-truncated distribution for juvenile size. Only applies to the Poisson and negative binomial distributions, and cannot be applied is `jsize.zero = TRUE`.
  
  **indiv**: Designates the variable corresponding to individual identity in the vertical dataset.
  
  **patch**: Designates the variable corresponding to patch identity in the vertical dataset.
  
  **year**: Designates the variable corresponding to time *t* in the vertical dataset.
  
  **age**: Designates the name of the variable corresponding to age in time *t*. Should be set **only if an age-by-stage model is desired**. Do not use this option to produce a model that does not incorporate age.
  
  **year.as.random**: Designates whether to treat year as a random factor, and is only used when `approach = "mixed"`.
  
  **patch.as.random**: Designates whether to treat patch identity as a random factor, and is only used when `approach = "mixed"`.
  
  **show.model.tables**: Designates whether to include the full dredge model tables showing all models developed and their associated AICc values.
  
  **quiet**: Denotes whether to silence guidepost statements and most warning messages. Only warnings incurred in model testing will be visible, including warnings from the testing of global models and those from the testing of reduced models produced during model dredging.
  
  <p style="text-indent: 20px">In addition, there are other options that provide flexibility in handling datasets with different designations for key variables, and allowing manual designation of stages.</p>
  
  <p style="text-indent: 20px">This function is useful not just because it develops the models that we can use to estimate function-based MPMs, but because it provides a test of whether individual history affects demography. Setting `historical = TRUE` fits size and/or reproductive status in time *t*-1 into global models, while setting `historical = FALSE` prevents testing of the impacts of state in time *t*-1. The model building and selection protocols can then be used to see if history has a significant impact on a vital rate, by assessing whether a historical term is retained in the best-fit model. Here, we will build only ahistorical models.</p>

  <p style="text-indent: 20px">Here, we will create two ahistorical model sets. The first will be a model set for the entire population, without separating patches. The second will include patch as a random factor, and will thus allow us to explore patch dynamics as well as population dynamics. We will not create a historical set this time because we are producing an age x stage MPM only.</p>

```r
lathmodelsln2 <- modelsearch(lathvertln, historical = FALSE,
  approach = "mixed", suite = "main",
  vitalrates = c("surv", "obs", "size", "repst", "fec"), juvestimate = "Sdl",
  bestfit = "AICc&k", sizedist = "gaussian", fecdist = "negbin",
  indiv = "individ", year = "year2", age = "obsage", year.as.random = TRUE,
  patch.as.random = TRUE, show.model.tables = TRUE, fec.zero = TRUE, quiet = TRUE)
#> boundary (singular) fit: see ?isSingular
#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you

#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you

#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you
#> boundary (singular) fit: see ?isSingular
lathmodelsln2p <- modelsearch(lathvertln, historical = FALSE,
  approach = "mixed", suite = "main",
  vitalrates = c("surv", "obs", "size", "repst", "fec"), juvestimate = "Sdl",
  bestfit = "AICc&k", sizedist = "gaussian", fecdist = "negbin",
  indiv = "individ", patch = "patchid", year = "year2", age = "obsage",
  year.as.random = TRUE, patch.as.random = TRUE, show.model.tables = TRUE,
  fec.zero = TRUE, quiet = TRUE)
#> boundary (singular) fit: see ?isSingular
#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you

#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you

#> Warning in Matrix::sparseMatrix(dims = c(0, 0), i = integer(0), j = integer(0), : 'giveCsparse' has been deprecated; setting 'repr = "T"' for
#> you
#> boundary (singular) fit: see ?isSingular
#> boundary (singular) fit: see ?isSingular
#> boundary (singular) fit: see ?isSingular
#summary(lathmodelsln2)
#summary(lathmodelsln2p)
```

  <p style="text-indent: 20px">The output can be rather verbose, and so we have limited it with the `quiet = TRUE` option. The function was developed to provide text marker posts of what the function is doing and what it has accomplished, as well as to show all warnings from all workhorse functions used. Because we used the `mixed` approach here, this includes warnings originating from estimating mixed linear models with package `lme4` [@bates_fitting_2015] and, in the case of fecundity, the package `glmmTMB` [@brooks_glmmtmb_2017]. It also shows warnings originating from the `dredge()` function of package `MuMIn` [@barton_mumin_2014], which is the core function used in model building and AICc estimation. We encourage users to get familiar with interpreting these warnings and assessing the degree to which they impact their own analyses.</p>

  <p style="text-indent: 20px">In developing these linear models, the `modelsearch()` function set up a series of nested datasets for use in estimating vital rates as conditional rates and probabilities. The exact subsets created depend on which parameters are called for. It is important to consider which are required, and particular attention needs to be paid if there are size classes with sizes of 0. In these situations, it is best to consider a size of 0 as unobservable, and so to introduce observation status as a vital rate. This sets up datasets for size estimation that do not include 0 in the response term, because all 0 responses are already absorbed by observation status.</p>
  
  <p style="text-indent: 20px">A look at the summaries shows that the best-fit models vary in complexity. Age is important in all of the adult vital rates, in both the population-only model set as well as the patch model set. For example, survival is influenced by reproductive status and age in the current year, as well as by patch, individual identity, and year, while observation status is influenced by age but not by reproductive status. We can see these models explicitly, as well as the model tables developed, by calling them directly from the lefkoMod object.</p>

#### Step 4. MPM estimation
  
  <p style="text-indent: 20px">Next, we will estimate the ahistorical set of matrices. We will match the ahistorical age-by-stage matrix estimation function, `aflefko2()`, with the appropriate ahistorical input, including the ahistorical lefkoMod objects `lathmodelsln2` and `lathmodelsln2p`. Model sets that include historical terms should not be used to create ahistorical matrices, since the coefficients in the best-fit models are estimated assuming a specific model structure. Historical vital rate models may yield biased results if used to construct ahistorical matrices. Also note that `lefko3` does not currently allow the construction of historical age-by-stage MPMs, which risk becoming too large and overparameterized.</p>

```r
lathmat2age <- aflefko2(year = "all", stageframe = lathframeln,
  modelsuite = lathmodelsln2, data = lathvertln, supplement = lathsupp2,
  patchcol = "patchid", yearcol = "year2", year.as.random = FALSE,
  patch.as.random = FALSE, final_age = 2, continue = TRUE, reduce = FALSE)
lathmat2agep <- aflefko2(year = "all", patch = "all", stageframe = lathframeln,
  modelsuite = lathmodelsln2p, data = lathvertln, supplement = lathsupp2,
  patchcol = "patchid", yearcol = "year2", year.as.random = FALSE,
  patch.as.random = FALSE, final_age = 2, continue = TRUE, reduce = FALSE)
summary(lathmat2age)
#> 
#> This ahistorical lefkoMat object contains 3 matrices.
#> 
#> Each matrix is a square matrix with 63 rows and columns, and a total of 3969 elements.
#> A total of 2178 survival transitions were estimated, with 726 per matrix.
#> A total of 108 fecundity transitions were estimated, with 36 per matrix.
#> 
#> Vital rate modeling quality control:
#> 
#> Survival estimated with 257 individuals and 2246 individual transitions.
#> Observation estimated with 254 individuals and 2121 individual transitions.
#> Size estimated with 254 individuals and 1916 individual transitions.
#> Reproductive status estimated with 254 individuals and 1916 individual transitions.
#> Fecundity estimated with 128 individuals and 599 individual transitions.
#> Juvenile survival estimated with 187 individuals and 281 individual transitions.
#> Juvenile observation estimated with 154 individuals and 210 individual transitions.
#> Juvenile size estimated with 144 individuals and 193 individual transitions.
#> Juvenile reproduction probability not estimated.
#> NULL
summary(lathmat2agep)
#> 
#> This ahistorical lefkoMat object contains 18 matrices.
#> 
#> Each matrix is a square matrix with 63 rows and columns, and a total of 3969 elements.
#> A total of 13068 survival transitions were estimated, with 726 per matrix.
#> A total of 648 fecundity transitions were estimated, with 36 per matrix.
#> 
#> Vital rate modeling quality control:
#> 
#> Survival estimated with 257 individuals and 2246 individual transitions.
#> Observation estimated with 254 individuals and 2121 individual transitions.
#> Size estimated with 254 individuals and 1916 individual transitions.
#> Reproductive status estimated with 254 individuals and 1916 individual transitions.
#> Fecundity estimated with 128 individuals and 599 individual transitions.
#> Juvenile survival estimated with 187 individuals and 281 individual transitions.
#> Juvenile observation estimated with 154 individuals and 210 individual transitions.
#> Juvenile size estimated with 144 individuals and 193 individual transitions.
#> Juvenile reproduction probability not estimated.
#> NULL
```

  <p style="text-indent: 20px">The first model set led to the development of 3 matrices, reflecting the 4 years of data. The second model set led to the development of 18 matrices, reflecting 4 years and 6 patches. We can get a sense of what these matrices look like by visualizing them. Let's use the `image3()` function to look at just one.</p>

```r
image3(lathmat2age, used = 1)
```

![Figure 8.5. Visualization of 1st A Matrix](Ch8.13-1.png)

```
#> NULL
```

  <p style="text-indent: 20px">The clear squares refer to zero elements, and the red elements refer to non-zero values of survival and fecundity. The vast number of 0s may be surprising, but this matrix is a supermatrix organized by age first, with stage organizing within-age blocks. The first age is age 0, which cannot be adult, and age 1 corresponds to seedlings, leading to most non-zero elements in the adult portion. The adult block occurs from age 2, and this block can perpetuate indefinitely. The number of elements estimated is greater now than in the typical ahistoprical MPM, because now we have added age as a major factor for analysis. This matrix is overwhelmingly composed of elements that must be 0, and so it is a rather sparse matrix ((726 + 36)  / 3969 = 19.2% of elements).</p>

  <p style="text-indent: 20px">Next let's take a look at the column sums from the `$U` matrices, which represent the survival probabilities of all age-stage combinations and so should equal numbers ranging from 0 to 1. </p>

```r
writeLines("Stage survival in matrix 1")
#> Stage survival in matrix 1
summary(colSums(lathmat2age$U[[1]]))
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>  0.0000  0.0000  0.9572  0.6040  0.9867  0.9982
writeLines("\nStage survival in matrix 2")
#> 
#> Stage survival in matrix 2
summary(colSums(lathmat2age$U[[2]]))
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>  0.0000  0.0000  0.9380  0.6016  0.9850  0.9955
writeLines("\nStage survival in matrix 3")
#> 
#> Stage survival in matrix 3
summary(colSums(lathmat2age$U[[3]]))
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>  0.0000  0.0000  0.8857  0.5870  0.9773  0.9912
```

  <p style="text-indent: 20px">Matrix estimation can sometimes create spurious values, such as stage survival greater than 1.0. These values can occur for a variety of reasons, but the most common is the inclusion through a supplement table or overwrite table of externally-determined survival probabilities that are too high. Make sure to check your matrix column sums each time you estimate MPMs to prevent this problem. Survival greater than 1.0 can lead to strange impacts on metrics of population dynamics.</p>
  
  <p style="text-indent: 20px">Now let's estimate the element-wise mean matrices. Note that the first lefkoMat object created will include a single mean matrix, while the second  will include 6 mean matrices for the patches, followed by a grand mean matrix, yielding a total of 7 matrices.</p>

```r
lathmat2mean <- lmean(lathmat2age)
lathmat2pmean <- lmean(lathmat2agep)
summary(lathmat2mean)
#> 
#> This ahistorical lefkoMat object contains 1 matrix.
#> 
#> Each matrix is a square matrix with 63 rows and columns, and a total of 3969 elements.
#> A total of 726 survival transitions were estimated, with 726 per matrix.
#> A total of 36 fecundity transitions were estimated, with 36 per matrix.
#> NULL
summary(lathmat2pmean)
#> 
#> This ahistorical lefkoMat object contains 7 matrices.
#> 
#> Each matrix is a square matrix with 63 rows and columns, and a total of 3969 elements.
#> A total of 5082 survival transitions were estimated, with 726 per matrix.
#> A total of 252 fecundity transitions were estimated, with 36 per matrix.
#> NULL
```

#### Step 5. MPM analysis

  <p style="text-indent: 20px">Now let's estimate the deterministic population growth rate $\lambda$, and the stochastic population growth rate, $a = \text{log} \lambda _{S}$, in our age x stage MPM. Let's plot these for comparison, making sure to take the natural exponent of the stochastic growth rate to make it comparable to $\lambda$. We will show the patch means and the grand population mean.</p>

```r
lambda2 <- lambda3(lathmat2age)
lambda2m <- lambda3(lathmat2mean)
lambda2mp <- lambda3(lathmat2pmean)
set.seed(42)
sl2 <- slambda3(lathmat2age) #Stochastic growth rate
sl2$expa <- exp(sl2$a)

par(mfrow = c(1,2))
plot(lambda ~ year2, data = lambda2, ylim = c(0.92, 0.98),xlab = "Year",
  ylab = expression(lambda), type = "l", lty= 1, lwd = 2, bty = "n")
abline(a = lambda2m$lambda[1], b = 0, lty = 2, lwd= 2, col = "orangered")
abline(a = sl2$expa[1], b = 0, lty = 2, lwd= 3, col = "darkred")
legend("bottomright", c("det annual", "det mean", "stochastic"), lty = c(1, 2, 2),
  col = c("black", "orangered", "darkred"), lwd = c(2, 2, 3), bty = "n")

plot(lambda ~ patch, data = lambda2mp[1:6,], ylim = c(0.96, 0.975), xlab = "Patch",
  ylab = expression(lambda), type = "l", lty= 1, lwd = 2, bty = "n")
abline(a = lambda2m$lambda[1], b = 0, lty = 2, lwd= 2, col = "orangered")
abline(a = sl2$expa[1], b = 0, lty = 2, lwd= 2, col = "darkred")
legend("bottomleft", c("patch det mean", "pop det mean", "pop sto"), lty = c(1, 2, 2),
  col = c("black", "orangered", "darkred"), lwd = 2, bty = "n")
```

![Figure 8.6. Deterministic vs. stochastic lambda](Ch8.16-1.png)

  <p style="text-indent: 20px">Deterministic and stochastic analyses show that the population and all patches are declining on average. Qualitatively, they agree with the $\lambda$ estimates from our other *Lathyrus* vignettes.</p>
  
  <p style="text-indent: 20px">Now let's look at the stable stage distribution, using the population matrices. The output for the ahistorical MPM is a dataframe with matrix of origin, stage name, and stable stage proportion in each row. Note that the `ss_prop` column, which gives us the stable stage proportion of each stage, sums to 1.0 within each matrix.</p>

```r
ehrlen2ss <- stablestage3(lathmat2mean)
ehrlen2ss_s <- stablestage3(lathmat2age, stochastic = TRUE, seed = 42)

ss_props <- cbind.data.frame(ehrlen2ss$ss_prop, ehrlen2ss_s$ss_prop)
names(ss_props) <- c("det", "sto")
rownames(ss_props) <- paste(ehrlen2ss$age, ehrlen2ss$stage)

barplot(t(ss_props), beside = T, ylab = "Proportion", xlab = "Age-Stage",
  ylim = c(0, 0.25), xaxt = "n", col = c("black", "red"), bty = "n")
text(cex=0.5, y = -0.015, x = seq(from = 0, to = 2.98*length(rownames(ss_props)), by = 3),
  rownames(ss_props), xpd=TRUE, srt=45)
legend("topright", c("det", "sto"), col = c("black", "red"), pch = 15, bty = "n")
```

![Figure 8.7. Stable and long-run age-stage distribution](Ch8.17-1.png)

  <p style="text-indent: 20px">The distribution is actually a stable age-stage distribution, and deterministic and stochastic approaches generally agree. The population is dominated by seedlings and mid-sized adults. To explore further, it may be useful to collapse age and only look at stage. So, let's replot accordingly.</p>

```r
det_dist <- apply(as.matrix(c(1:21)), 1, function(X) {
  ss_sum <- ss_props$det[X] + ss_props$det[21 + X] + ss_props$det[42 + X]
  return(ss_sum)
})
sto_dist <- apply(as.matrix(c(1:21)), 1, function(X) {
  ss_sum <- ss_props$sto[X] + ss_props$sto[21 + X] + ss_props$sto[42 + X]
  return(ss_sum)
})

barplot(t(cbind.data.frame(det_dist, sto_dist)), beside = T,  ylab = "Proportion",
  xaxt = "n", ylim = c(0, 0.25), col = c("black", "red"), bty = "n")
text(cex=1, x=seq(from = 0.5, to = 3 * length(lathframeln$stage), by = 3),
  y=-0.025, lathframeln$stage, xpd=TRUE, srt=45)
legend("topright", c("det", "sto"), col = c("black", "red"), pch = 15, bty = "n")
```

![Figure 8.8. Stable and long-run stage distribution](Ch8.18-1.png)

  <p style="text-indent: 20px">The stable stage distribution shows very high levels of seedlings and dormant seeds, and also of mid-size adults of both non-flowering and flowering varieties. So, the same patterns as before, but without age making us sense squint at the x-axis labels.</p>

  <p style="text-indent: 20px">Now let's take a look at the reproductive values. We'll go straight to the plots, as with the stable stage distribution.</p>

```r
ehrlen2rv <- repvalue3(lathmat2mean)
ehrlen2rv_s <- repvalue3(lathmat2age, stochastic = TRUE, seed = 42)

barplot(t(cbind.data.frame(ehrlen2rv$rep_value, ehrlen2rv_s$rep_value)),
  beside = T, ylab = "Relative rep value", xlab = "Age-Stage", ylim = c(0, 1.3),
  col = c("black", "red"), bty = "n")
text(cex=0.5, y = -0.06, x = seq(from = 0, to = 2.98*length(rownames(ss_props)), by = 3),
  rownames(ss_props), xpd=TRUE, srt=45)
legend("topright", c("det", "sto"), col = c("black", "red"), pch = 15, bty = "n")
```

![Figure 8.10. Age-stage reproductive values](Ch8.19-1.png)

  <p style="text-indent: 20px">We see reproductive values above 0 starting with non-reproductive adults in age 1, and the highest reproductive values associated with flowering, medium to large adults in ages 1 and 2. These patterns hold in both deterministic and stochastic analyses.</p>

  <p style="text-indent: 20px">We will next assess which matrix elements $\lambda$ is most sensitive and elastic to changes in. As before, we will look at both deterministic and stochastic sensitivities.</p>

```r
lathmat2msens <- sensitivity3(lathmat2mean)
lathmat2msens_s <- sensitivity3(lathmat2age, stochastic = TRUE, seed = 42)

writeLines("\nThe highest deterministic sensitivity value: ")
#> 
#> The highest deterministic sensitivity value:
max(lathmat2msens$ah_sensmats[[1]][which(lathmat2mean$A[[1]] > 0)])
#> [1] 0.1477963
writeLines("\nThis value is associated with element: ")
#> 
#> This value is associated with element:
which(lathmat2msens$ah_sensmats[[1]] == max(lathmat2msens$ah_sensmats[[1]][which(lathmat2mean$A[[1]] > 0)]))
#> [1] 3838
writeLines("\nThe highest deterministic sensitivity value: ")
#> 
#> The highest deterministic sensitivity value:
max(lathmat2msens_s$ah_sensmats[[1]][which(lathmat2mean$A[[1]] > 0)])
#> [1] 0.1532107
writeLines("\nThis value is associated with element: ")
#> 
#> This value is associated with element:
which(lathmat2msens_s$ah_sensmats[[1]] == max(lathmat2msens_s$ah_sensmats[[1]][which(lathmat2mean$A[[1]] > 0)]))
#> [1] 3838
```

  <p style="text-indent: 20px">The highest sensitivity value in both analyses appears to be associated with the transition from flowering adult age 2 and up in size class 7, to flowering adult age 2 and up in size class 4 (element 3838 is in column 61, row 58). Inspecting the sensitivity matrix (type `lathmat2msens$ah_sensmats[[1]]` to inspect the full deterministic sensitivity matrix, or `lathmat2msens_s$ah_sensmats[[1]]` to inspect the full stochastic sensitivity matrix) also shows that transitions near that element in the matrix are also associated with rather high sensitivities.</p>

  <p style="text-indent: 20px">Let's now assess the elasticity of $\lambda$ or $\text{log} \lambda$ to matrix elements.</p>

```r
lathmat2melas <- elasticity3(lathmat2mean)
lathmat2melas_s <- elasticity3(lathmat2age, stochastic = TRUE, seed = 42)

writeLines("\nThe highest deterministic elasticity value: ")
#> 
#> The highest deterministic elasticity value:
max(lathmat2melas$ah_elasmats[[1]][which(lathmat2mean$A[[1]] > 0)])
#> [1] 0.03506728
writeLines("\nThe largest determnistic elasticity is associated with element: ")
#> 
#> The largest determnistic elasticity is associated with element:
which(lathmat2melas$ah_elasmats[[1]] == max(lathmat2melas$ah_elasmats[[1]]))
#> [1] 3841
writeLines("\nThe highest stochastic elasticity value: ")
#> 
#> The highest stochastic elasticity value:
max(lathmat2melas_s$ah_elasmats[[1]][which(lathmat2mean$A[[1]] > 0)])
#> [1] 0.03529783
writeLines("\nThe largest stochastic elasticity is associated with element: ")
#> 
#> The largest stochastic elasticity is associated with element:
which(lathmat2melas_s$ah_elasmats[[1]] == max(lathmat2melas_s$ah_elasmats[[1]]))
#> [1] 3841
```

  <p style="text-indent: 20px">Both deterministic and stochastic analyses show that population growth rate is most elastic to element 3841, which is in column 61 and row 61. Checking our stageframe shows that this element is associated with stasis in flowering adult age 2 and up in size class.</p>

  <p style="text-indent: 20px">Further analytical tools are being planned for `lefko3`, but packages that handle projection matrices can typically handle the individual matrices produced and saved in `lefkoMat` objects in this package. Differences, obscure results, and errors sometimes arise when packages are not made to handle large and/or sparse matrices - historical matrices are both, and so care must be taken with their analysis.</p>


## Acknowledgements

  <p style="text-indent: 20px">We are grateful to two anonymous reviewers whose scrutiny improved the quality of this vignette. The project resulting in this package and this tutorial was funded by Grant-In-Aid 19H03298 from the Japan Society for the Promotion of Science.</p>
  
  
## Literature cited

<div id="refs"></div>
