make_stage4age_matrix: Construct a stage-structured matrix with given mean stage...
In BruceKendall/mpmtools: Tools for Building and Analyzing Matrix Population Models

Description Usage Arguments Details Value References Examples

View source: R/mpm_creation.R

Construct a stage-structured matrix with given mean stage durations

make_stage4age_matrix(stage_table, survival = stage_table$survival,
  maternity = stage_table$maternity, duration = stage_table$duration,
  approx_method = c("unrolled", "AAS", "SAS", "FAS"), model = c("post",
  "pre"), tol = 10^(-6))

`stage_table`	Either a vector of stage names or a data frame with columns "stage_name", "survival", "maternity", and "duration". In the latter case the next three arguments do not need to be provided
`survival`	A vector of stage-specific survival, on a per-timestep basis
`maternity`	A vector of stage-specific maternities (number of offspring produced by an individual in a given stage)
`duration`	A vector of average number of timesteps spent in each stage. If the final stage continues indefinitely (there is no maximum age) then the last element should be "Inf"
`approx_method`	The rule for generating the matrix (see details). Defaults to "unrolled"
`model`	Whether the matrix should represent a prebreeding ("pre") or postbreeding ("post") census model. Defaults to "post"
`tol`	The convergence tolerance for lambda in estimating the AAS model. Defaults to 1e-6.

There is no universally "best" way to construct a stage structured model based on mean stage durations. This function implements four approaches, with names based on the scheme in Kendall et al. (in review).

approx_method = "unrolled": this creates an age-structured Leslie matrix where stage i is replicated duration[i] times. This is a good solution if the variance in stage duration is small, and is the best solution if there is no variance in stage duration: it correctly generates both the transient and asymptotic dynamics. The cost is a potentially large matrix, which doesn't cause R any difficulty but may be challenging to visualize (future developments will provide tools to aggregate results by stage). This method requires that all elements of duration be integers.

approx_method = "AAS" ("asymptotic age structure"): this creates a stage-structured Lefkovitch model where the fraction of individual maturing out of stage i is given by the formula in Crowder et al. (1994). This reproduces the mean stage durations that would be observed if the population were at the asymptotic stage structure, and (with suitable care in the sensitivity calculations) can reproduce the asymptotic calculations of the unrolled matrix. However, the model will likely not give useful estimates of transient dynamics, and will not give reliable statistics that are based on folloing cohorts (such as R0), for which SAS is preferred. As with SAS and FAS, the variance of the stage durations cannot be set, being equal to the means. This method requires an iterative approach, as the maturation fraction depends on the asymptotic growth rate, lambda1; the argument tol is used to determine when convergence has occurred. Smaller values will produce more precise estimates of the transition rates, but will require longer to calculate.

approx_method = "SAS" ("stable age structure"): this creates a stage-structured Lefkovitch model where the fraction of individual maturing out of stage i is given by the formula in Crouse et al. (1987). This reproduces the mean stage durations that would be observed if one is following a cohort through time, and hence is probably the best stage-based solution for calculating quantities such as R0, mean age at maturity, or some definitions of generation time. However, unless lambda = 1, this model will not give the correct mean stage duration under asymptotic conditions. As with AAS and FAS, the variance of the stage durations cannot be set, being equal to the means.

approx_method = "FAS" ("flat age structure"): this creates a stage-structured Lefkovitch model where the fraction of individual maturing out of stage i is 1/duration[i]. This is not likely to ever be a good solution, as the mean stage duration will only be matched under very special conditions and the stage duration variance is uncontrolled (it is equal to the mean). However, it is the first solution proposed by Caswell (2001) and, being easy to calculate by hand, is popular in the literature.

A projection matrix. For the "unrolled" case the row and column names are a concatenation of the stage name and the age; for the others they are the stage names.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation, 2nd edition. Sinauer Associates, Sunderland, MA.

Crouse, D. T., L. B. Crowder, and H. Caswell. 1987. A stage-based population model for loggerhead sea turtles and implications for conservation. Ecology 68:1412-1423.

Crowder, L. B., D. T. Crouse, S. S. Heppell, and T. H. Martin. 1994. Predicting the impact of turtle excluder devices on loggerhead sea turtle populations. Ecological Applications 4:437-445.

Kendall, B.E., M. Fujiwara, J. Diaz-Lopez, S. Schneider, J. Voigt, and S. Wiesner. In review. Persistent problems in the construction of matrix population models. Ecological Modelling.

# Recreate the model published as Table 2 of Crowder et al. (1994)
# (which differs slightly in A[1, 4], presumbably from a rounding error)
make_stage4age_matrix(loggerhead[[2]], approx_method = "AAS")

# Reducing the tolerance only changes the matrix slightly
make_stage4age_matrix(loggerhead[[2]], approx_method = "AAS", tol = 1e-8)

# Attempt to recreate the model published as Table 4 of Crouse et al. (1987).
# However, the published model has a typo in A[7, 7] and incorrect reproduction terms.
make_stage4age_matrix(loggerhead[[1]], approx_method = "SAS")

# Compare asymptotic growth rate from AAS and unrolled approximations
A_AAS <- make_stage4age_matrix(loggerhead[[2]], approx_method = "AAS")
A_unrolled <- make_stage4age_matrix(loggerhead[[2]])
lambda1(A_AAS)
lambda1(A_unrolled)