Divides columns of a matrix population model by the corresponding stage-specific survival probability, to obtain lower-level vital rates for growth, stasis, shrinkage, and reproduction. Vital rates corresponding to biologically impossible transitions are coerced to NA.

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, shrinkage, stasis, 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_mat_U(matU, posU = matU > 0, surv_only_na = TRUE)

vr_mat_R(matU, matR, posR = matR > 0)

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

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.

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

## Value

A matrix of vital rates. Vital rates corresponding to impossible transitions will be coerced to NA (see Details).

## Details

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 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, vr_mat assumes that a transition rate of 0 indicates an impossible transition, in which case a value of NA will be returned in the relevant matrix cell. 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 possible but estimated to be 0, one should specify the posU and/or posR arguments manually.

## References

Caswell, H. 2001. Matrix Population Models: Construction, Analysis, and Interpretation. Sinauer Associates; 2nd edition. ISBN: 978-0878930968

## See also

Other vital rates: vital_rates(), vr_vec, vr

## Author

Patrick Barks <patrick.barks@gmail.com>

## Examples

matU <- rbind(
c(0.1, 0, 0, 0),
c(0.5, 0.2, 0.1, 0),
c(0, 0.3, 0.3, 0.1),
c(0, 0, 0.5, 0.6)
)

matR <- rbind(
c(0, 0, 1.1, 1.6),
c(0, 0, 0.8, 0.4),
c(0, 0, 0, 0),
c(0, 0, 0, 0)
)

# extract vital rates of survival from matU
vr_mat_U(matU)
#>           [,1] [,2]      [,3]      [,4]
#> [1,] 0.1666667   NA        NA        NA
#> [2,] 0.8333333  0.4 0.1111111        NA
#> [3,]        NA  0.6 0.3333333 0.1428571
#> [4,]        NA   NA 0.5555556 0.8571429

# extract vital rates of reproduction from matR
vr_mat_R(matU, matR)
#>      [,1] [,2]      [,3]      [,4]
#> [1,]   NA   NA 1.2222222 2.2857143
#> [2,]   NA   NA 0.8888889 0.5714286
#> [3,]   NA   NA        NA        NA
#> [4,]   NA   NA        NA        NA