Derive a vector of stage-specific vital rates of survival, growth, shrinkage, stasis, dormancy, or reproduction from a matrix population model. These functions include optional arguments for excluding certain stage classes from the calculation (see Excluding stages), and defining the set of biologically-possible transitions (see Possible transitions).

This decomposition 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, shrinkage, stasis, dormancy, or 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.

vr_vec_survival(matU, posU = matU > 0, exclude_col = NULL)

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

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

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

vr_vec_dorm_enter(matU, posU = matU > 0, dorm_stages)

vr_vec_dorm_exit(matU, posU = matU > 0, dorm_stages)

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

Arguments

matU

The survival component of a matrix population model (i.e., a square projection matrix only containing survival-related transitions; 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 Details).

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.

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 only 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 Details).

weights_row

Vector of stage-specific weights to apply while summing vital rates across rows within columns (e.g., reproductive value vector).

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 vitals_ 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.

Excluding stages

It may be desirable to exclude one or more stages from the calculation of certain vital rates. For instance, a user might not believe that 'growth' to a dormant stage class really reflects biological growth, in which case the user could exclude transitions to the dormant stage class using the argument exclude_row. The user may or may not want to ignore 'growth' transitions from the dormant stage class, which can be done using exclude_col. The argument exclude_col effectively just coerces the respective vital rate to NA, to prevent it from getting used in subsequent calculations. To exclude transitions both to and from a given set of stages, use argument exclude.

See also

Other vital rates: vital_rates(), vr_mat, vr

Author

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)
)

matR <- 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_vec_survival(matU, exclude_col = 4)
#> [1] 0.6 0.5 0.9  NA
vr_vec_growth(matU, exclude = 4)
#> [1] 0.8333333 0.6000000        NA        NA

# `exclude*` and `*_stages` arguments can accept stage names
matU <- name_stages(matU)
matR <- name_stages(matR)
vr_vec_shrinkage(matU, exclude = 4)
#>   stage_1   stage_2   stage_3   stage_4 
#>        NA        NA 0.1111111        NA 
vr_vec_stasis(matU, exclude = "stage_4")
#>   stage_1   stage_2   stage_3   stage_4 
#> 0.1666667 0.4000000 0.3333333        NA 

vr_vec_dorm_enter(matU, dorm_stages = 4)
#>   stage_1   stage_2   stage_3   stage_4 
#>        NA        NA 0.5555556        NA 
vr_vec_dorm_exit(name_stages(matU), dorm_stages = "stage_4")
#> Warning: Existing stage names have been overwritten!
#>   stage_1   stage_2   stage_3   stage_4 
#>        NA        NA        NA 0.3333333 

vr_vec_reproduction(matU, matR, exclude_col = "stage_4")
#>  stage_1  stage_2  stage_3  stage_4 
#>       NA 2.000000 2.111111       NA