mpmsim (version 3.2.0)

rand_lefko_set: Generate lists of Lefkovitch matrix population models (MPMs) based on life history archetypes

Description

This function generates a list of n MPMs according to the specified criteria. Criteria include the archetype, and the acceptable constraining criteria, which could include lambda, generation time or any other metric derived from an A matrix. The function attempts to find matrices that fulfil the criteria, discarding unacceptable matrices. By default, if it takes more than 1000 attempts to find a suitable matrix model, then an error is produced. However, the number of attempts can be altered with the attempts parameter.

Usage

rand_lefko_set(
  n_models = 5,
  n_stages = 3,
  archetype = 1,
  fecundity = 1.5,
  output = "Type1",
  max_surv = 0.99,
  constraint = NULL,
  attempts = 1000
)

Value

A compadreDB object or list of MPMs that meet the specified criteria.

Arguments

n_models

An integer indicating the number of MPMs to generate.

n_stages

The number of stages for the MPMs. Default is 3.

archetype

The archetype of the MPMs. Default is 1.

fecundity

The average number of offspring produced (fecundity). Values can be provided in 4 ways:

• An numeric vector of length 1 providing a single measure of fecundity to the top right corner of the matrix model only.

• A numeric vector of integers of length equal to n_stages to provide fecundity estimates for the whole top row of the matrix model. Use 0 for cases with no fecundity.

• A matrix of numeric values of the same dimension as n_stages to provide fecundity estimates for the entire matrix model. Use 0 for cases with no fecundity.

• A list of two matrices of numeric values, both with the same dimension as n_stages, to provide lower and upper limits of mean fecundity for the entire matrix model.

In the latter case, a fecundity value will be drawn from a uniform distribution for the defined range. If there is no fecundity in a particular age class, use a value of 0 for both the lower and upper limit.

output

Character string indicating the type of output.

• Type1 or cdb_split: A compadreDB Object containing MPMs split into the submatrices (i.e. A, U, F and C).

• Type2 or cdb_A: A compadreDB Object containing MPMs that are not split into submatrices (i.e. only the A matrix is included).

• Type3: A list_split1 of MPMs arranged so that each element of the list contains a model and associated submatrices (i.e. the nth element contains the nth A matrix alongside the nth U and F matrices).

• Type4: A list_split2 of MPMs arranged so that the list contains 3 lists for the A matrix and the U and F submatrices respectively.

• Type5 or list_A: A list of MPMs, including only the A matrix.

max_surv

The maximum acceptable survival value, calculated across all transitions from a stage. Defaults to 0.99. This is only used the output splits a matrix into the submatrices.

constraint

An optional data frame with 4 columns named fun, arg, lower and upper. These columns specify (1) a function that outputs a metric derived from an A matrix and (2) an argument for the function (NA, if no argument supplied) (3) the lower acceptable bound for the metric and (4) upper acceptable bound for the metric.

attempts

An integer indicating the number of attempts To be made when simulating matrix model. The default is 1000. If it takes more than 1000 attempts to make a matrix that satisfies the conditions set by the other arguments, then a warning is produced.

Author

Owen Jones

References

Caswell, H. (2001). Matrix Population Models: Construction, Analysis, and Interpretation. Sinauer.

Lefkovitch, L. P. (1965). The study of population growth in organisms grouped by stages. Biometrics, 21(1), 1.

Takada, T., Kawai, Y., & Salguero-Gómez, R. (2018). A cautionary note on elasticity analyses in a ternary plot using randomly generated population matrices. Population Ecology, 60(1), 37–47.

See Also

rand_lefko_mpm() which this function is essentially a wrapper for.

Other Lefkovitch matrices: rand_lefko_mpm()

Examples

set.seed(42) # set seed for repeatability

# Basic operation, without splitting matrices and with no constraints
rand_lefko_set(
  n_models = 3, n_stages = 5, fecundity = c(0, 0, 4, 8, 10),
  archetype = 4, output = "Type5"
)

# Constrain outputs to A matrices with lambda between 0.9 and 1.1
library(popbio)
constrain_df <- data.frame(
  fun = "lambda", arg = NA, lower = 0.9, upper =
    1.1
)
rand_lefko_set(
  n_models = 10, n_stages = 5, fecundity = c(0, 0, 4, 8, 10),
  archetype = 4, constraint = constrain_df, output = "Type5"
)

# As above, but using popdemo::eigs function instead of popbio::lambda
# to illustrate use of argument
library(popdemo)
constrain_df <- data.frame(
  fun = "eigs", arg = "lambda", lower = 0.9, upper = 1.1
)

rand_lefko_set(
  n_models = 10, n_stages = 5, fecundity = c(0, 0, 4, 8, 10),
  archetype = 4, constraint = constrain_df, output = "Type5"
)

# Multiple constraints
# Constrain outputs to A matrices with lambda between 0.9 and 1.1, generation
# time between 3 and 5 and damping ratio between 1 and 7.
library(popbio)
constrain_df <- data.frame(
  fun = c("lambda", "generation.time", "damping.ratio"),
  arg = c(NA, NA, NA),
  lower = c(0.9, 3.0, 1.0),
  upper = c(1.1, 5.0, 7.0)
)
rand_lefko_set(
  n_models = 10, n_stages = 5, fecundity = c(0, 0, 4, 8, 10),
  archetype = 4, constraint = constrain_df, output = "Type5"
)

# Constraints based on user-defined functions are also possible...
# User-defined function to calculate survival from the first stage
simpleFun <- function(x) {
  sum(x[, 1])
}

# Define the constraint, based on the user-defined function
constrain_df <- data.frame(
  fun = "simpleFun", arg = NA, lower = 0.75, upper = 1
)

rand_lefko_set(
  n_models = 10, n_stages = 5, fecundity = c(0, 0, 4, 8, 10),
  archetype = 4, output = "Type5", constraint = constrain_df
)