Rage: perturb_vr – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

perturb_vr

Perturbation analysis of vital rates in a matrix population model

Description

Perturbs lower-level vital rates within a matrix population model and measures the response (sensitivity or elasticity) of the per-capita population growth rate at equilibrium (λ), or, with a user-supplied function, any other demographic statistic.

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

Usage

perturb_vr(
  matU,
  matF,
  matC = NULL,
  pert = 1e-06,
  type = "sensitivity",
  demog_stat = "lambda",
  ...
)

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).
`matF`	The sexual component of a matrix population model (i.e. a square projection matrix reflecting transitions due to sexual reproduction).
`matC`	The clonal component of a matrix population model (i.e. a square projection matrix reflecting transitions due to clonal reproduction). Defaults to `NULL`, indicating no clonal reproduction (i.e. `matC` is a matrix of zeros).
`pert`	Magnitude of the perturbation. Defaults to `1e-6`.
`type`	Whether to return "sensitivity" or "elasticity" values. Defaults to "sensitivity".
`demog_stat`	The demographic statistic to be used, as in "the sensitivity/elasticity of `demog_stat` to vital rate perturbations." Defaults to the per-capita population growth rate at equilibrium (λ). Also accepts a user-supplied function that performs a calculation on a projection matrix and returns a single numeric value.
`...`	Additional arguments passed to the function `demog_stat`.

Value

A list with 5 elements:

`survival`	sensitivity or elasticity of `demog_stat` to survival
`growth`	sensitivity or elasticity of `demog_stat` to growth
`shrinkage`	sensitivity or elasticity of `demog_stat` to shrinkage
`fecundity`	sensitivity or elasticity of `demog_stat` to sexual fecundity
`clonality`	sensitivity or elasticity of `demog_stat` to clonality

Author(s)

Rob Salguero-Gomez <rob.salguero@zoo.ox.ac.uk>

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

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

perturb_vr(matU, matF)

# use elasticities rather than sensitivities
perturb_vr(matU, matF, type = "elasticity")

# use a larger perturbation than the default
perturb_vr(matU, matF, pert = 0.01)

# calculate the sensitivity/elasticity of the damping ratio to vital rate
#  perturbations
damping <- function(matA) {  # define function for damping ratio
  eig <- eigen(matA)$values
  dm <- rle(Mod(eig))$values
  return(dm[1] / dm[2])
}

perturb_vr(matU, matF, demog_stat = "damping")

Rage

Life History Metrics from Matrix Population Models

v1.0.0

GPL-3

Authors

Patrick Barks [aut] (<https://orcid.org/0000-0002-5947-8151>), Danny Buss [ctb], Pol Capdevila [aut] (<https://orcid.org/0000-0002-2842-4302>), Hal Caswell [aut] (<https://orcid.org/0000-0003-4394-6894>), Judy P. Che-Castaldo [aut] (<https://orcid.org/0000-0002-9118-9202>), John Jackson [aut] (<https://orcid.org/0000-0002-4563-2840>), Tamora James [aut] (<https://orcid.org/0000-0003-1363-4742>), Owen Jones [aut, cre] (<https://orcid.org/0000-0001-5720-4686>), Sam Levin [aut] (<https://orcid.org/0000-0002-3289-9925>), William K. Petry [aut] (<https://orcid.org/0000-0002-5230-5987>), Roberto Salguero-Gomez [aut] (<https://orcid.org/0000-0002-6085-4433>), Caroline Schuette [ctb] (<https://orcid.org/0000-0002-2063-8736>), Iain Stott [aut] (<https://orcid.org/0000-0003-2724-7436>), Chelsea C. Thomas [aut] (<https://orcid.org/0000-0002-8155-9353>)

Initial release