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.

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

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

Vector of vital rates. Vital rates corresponding to impossible
transitions are coerced to `NA`

(see *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.

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.

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`

.

Other vital rates:
`vital_rates()`

,
`vr_mat`

,
`vr_vec`

```
# 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)
#> [1] 0.6666667
vr_growth(matU, exclude = 4)
#> [1] 0.7166667
vr_shrinkage(matU, exclude = 4)
#> [1] 0.1111111
vr_stasis(matU, exclude = 4)
#> [1] 0.3
# `exclude*` and `*_stages` arguments can accept stage names
matU <- name_stages(matU)
matF <- name_stages(matF)
vr_dorm_enter(matU, dorm_stages = "stage_4")
#> [1] 0.5555556
vr_dorm_exit(matU, dorm_stages = 4)
#> [1] 0.3333333
vr_fecundity(matU, matF, exclude_col = 4)
#> [1] 2.055556
```