vr: Derive mean vital rates from a matrix population model
In Rage: Life History Metrics from Matrix Population Models

vr	R Documentation

Derive mean vital rates from a matrix population model

Description

Derive mean vital rates of survival, growth (or development), shrinkage (or de-development), stasis, dormancy, or reproduction from a matrix population model, by averaging across stage classes. These functions include optional arguments for custom weighting of different stage classes (see Weighting stages), excluding certain stage classes from the calculation (see Excluding stages), and defining the set of biologically-possible transitions (see Possible transitions).

These decompositions assume that all transition rates are products of a stage-specific survival term (column sums of matU) and a lower level vital rate that is conditional on survival (growth/development, shrinkage/de-development, stasis, dormancy, or a/sexual reproduction). Reproductive vital rates that are not conditional on survival (i.e., within a stage class from which there is no survival) are also allowed.

Usage

vr_survival(matU, posU = matU > 0, exclude_col = NULL, weights_col = NULL)

vr_growth(
  matU,
  posU = matU > 0,
  exclude = NULL,
  exclude_row = NULL,
  exclude_col = NULL,
  weights_col = NULL,
  surv_only_na = TRUE
)

vr_shrinkage(
  matU,
  posU = matU > 0,
  exclude = NULL,
  exclude_row = NULL,
  exclude_col = NULL,
  weights_col = NULL,
  surv_only_na = TRUE
)

vr_stasis(
  matU,
  posU = matU > 0,
  exclude = NULL,
  weights_col = NULL,
  surv_only_na = TRUE
)

vr_dorm_enter(matU, posU = matU > 0, dorm_stages, weights_col = NULL)

vr_dorm_exit(matU, posU = matU > 0, dorm_stages, weights_col = NULL)

vr_fecundity(
  matU,
  matR,
  posR = matR > 0,
  exclude_col = NULL,
  weights_row = NULL,
  weights_col = NULL
)

Arguments

`matU`	The survival component of a matrix population model (i.e., a square projection matrix reflecting survival-related transitions; e.g., progression, stasis, and retrogression)
`posU`	A logical matrix of the same dimension as `matU`, with elements indicating whether a given `matU` transition is possible (`TRUE`) or not (`FALSE`). Defaults to `matU > 0` (see Possible transitions).
`exclude_col`	Integer, character or logical vector indicating stages for which transitions both to and from the stage should be excluded from the calculation of vital rates. See section Excluding stages.
`weights_col`	Vector of stage-specific weights to apply while averaging vital rates across columns. See section Weighting stages.
`exclude`	Integer, character or logical vector indicating stages for which transitions both to and from the stage should be excluded from the calculation of vital rates. See section Excluding stages.
`exclude_row`	Integer, character or logical vector indicating stages for which transitions both to and from the stage should be excluded from the calculation of vital rates. See section Excluding stages.
`surv_only_na`	If there is only one possible `matU` transition in a given column, should that transition be attributed exclusively to survival? If `TRUE`, the vital rate of growth/stasis/shrinkage in that column will be coerced to `NA`. If `FALSE`, dividing the single transition by the stage-specific survival probability will always yield a value of `1`. Defaults to `TRUE`.
`dorm_stages`	Integer or character vector indicating dormant stage classes.
`matR`	The reproductive component of a matrix population model (i.e., a square projection matrix reflecting transitions due to reproduction; either sexual, clonal, or both)
`posR`	A logical matrix of the same dimension as `matR`, with elements indicating whether a given `matR` transition is possible (`TRUE`) or not (`FALSE`). Defaults to `matR > 0` (see Possible transitions).
`weights_row`	Vector of stage-specific weights to apply while summing vital rates across rows within columns. See section Weighting stages.

Value

Vector of vital rates. Vital rates corresponding to impossible transitions are coerced to NA (see Possible transitions).

Possible transitions

A transition rate of 0 within a matrix population model may indicate that the transition is not possible in the given life cycle (e.g., tadpoles never revert to eggs), or that the transition rate is possible but was estimated to be 0 in the relevant population and time period. If vital rates are to be averaged across multiple stage classes, or compared across populations, it may be important to distinguish between these two types of zeros.

By default, the vr_ functions assume that a transition rate of 0 indicates an impossible transition, in which case a value of NA will be used in relevant calculations. Specifically, the arguments posU and posR are specified by the logical expressions (matU > 0) and (matR > 0), respectively. If the matrix population model includes transitions that are estimated to be 0 but still in fact possible, one should specify the posU and/or posR arguments manually.

Weighting stages

In averaging vital rates across stages, it may be desirable to weight stage classes differently (e.g., based on reproductive values or stable distributions). Weights are generally applied when averaging across columns, i.e., across transitions from a set of stage classes (e.g., averaging stage-specific survival probabilities across multiple stages). All vr_ functions therefore include an optional argument weights_from.

In principle, particularly for vital rates of reproduction, the user can also apply weights when summing across rows within columns, i.e., across reproductive transitions to a set of stage classes (e.g., summing the production of different types of offspring, such as seeds vs. seedlings). The function vr_fecundity therefore also includes an optional argument weights_to.

If supplied, weights_from will automatically be scaled to sum to 1 over the set of possible transitions, whereas weights_to will not be rescaled because we wish to enable the use of reproductive values here, which do not naturally sum to 1.

Excluding stages

It may be desirable to exclude one or more stages from the calculation of certain vital rates. For instance, we might not believe that 'growth' to a dormant stage class really reflects biological growth, in which case we could exclude transitions to the dormant stage class using the argument exclude_row. We may or may not want to ignore 'growth' transitions from the dormant stage class, which can be done using exclude_col. To exclude transitions both to and from a given set of stages, use argument exclude.

Author(s)

Patrick Barks <patrick.barks@gmail.com>

Examples

# create example MPM (stage 4 is dormant)
matU <- rbind(
  c(0.1, 0, 0, 0),
  c(0.5, 0.2, 0.1, 0.1),
  c(0, 0.3, 0.3, 0.1),
  c(0, 0, 0.5, 0.4)
)

matF <- rbind(
  c(0, 0.7, 1.1, 0),
  c(0, 0.3, 0.8, 0),
  c(0, 0, 0, 0),
  c(0, 0, 0, 0)
)

vr_survival(matU, exclude_col = 4)
vr_growth(matU, exclude = 4)
vr_shrinkage(matU, exclude = 4)
vr_stasis(matU, exclude = 4)

# `exclude*` and `*_stages` arguments can accept stage names
matU <- name_stages(matU)
matF <- name_stages(matF)
vr_dorm_enter(matU, dorm_stages = "stage_4")
vr_dorm_exit(matU, dorm_stages = 4)

vr_fecundity(matU, matF, exclude_col = 4)

Rage documentation built on Sept. 30, 2023, 1:06 a.m.