perturb_trans {Rage}

Perturbation analysis of transition types within a matrix population model

Description

Calculates the summed sensitivities or elasticities for various transition types within a matrix population model (MPM), including stasis, retrogression, progression, fecundity, and clonality.

Sensitivities or elasticities are calculated by perturbing elements of the MPM and measuring the response of the per-capita population growth rate at equilibrium (\lambda), or, with a user-supplied function, any other demographic statistic.

Usage

perturb_trans(
  matU,
  matF,
  matC = NULL,
  posU = matU > 0,
  posF = matF > 0,
  posC = matC > 0,
  exclude_row = NULL,
  exclude_col = NULL,
  pert = 1e-06,
  type = "sensitivity",
  demog_stat = "lambda",
  ...
)

Arguments

matU

The survival component submatrix of a MPM (i.e., a square projection matrix reflecting survival-related transitions; e.g., progression, stasis, and retrogression).

matF

The sexual component submatrix of a MPM (i.e., a square projection matrix reflecting transitions due to sexual reproduction).

matC

The clonal component submatrix of a MPM (i.e., a square projection matrix reflecting transitions due to clonal reproduction). Defaults to NULL, indicating no clonal reproduction possible.

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

posF

A logical matrix of the same dimension as matF, with elements indicating whether a given matF transition is possible (TRUE) or not (FALSE). Defaults to matF > 0 (see Details).

posC

A logical matrix of the same dimension as matC, with elements indicating whether a given matC transition is possible (TRUE) or not (FALSE). Defaults to matC > 0 (see Details).

exclude_row

A vector of row indices or stages names indicating stages for which transitions to the stage should be excluded from perturbation analysis. Alternatively, a logical vector of length nrow(matU) indicating which stages to include TRUE or exclude FALSE from the calculation. See section Excluding stages.

exclude_col

A vector of column indices or stages names indicating stages for which transitions to the stage should be excluded from perturbation analysis. Alternatively, a logical vector of length ncol(matU) indicating which stages to include TRUE or exclude FALSE from the calculation. See section Excluding stages.

pert

The magnitude of the perturbation (defaults to 1e-6).

type

An argument defining whether to return 'sensitivity' or 'elasticity' values. Defaults to 'sensitivity'.

demog_stat

An argument defining which demographic statistic should be used, as in "the sensitivity/elasticity of demog_stat to matrix element perturbations." Defaults to the per-capita population growth rate at equilibrium (lambda). Also accepts a user-supplied function that performs a calculation on a MPM and returns a single numeric value.

...

Additional arguments passed to the function demog_stat.

Details

A transition rate of 0 within a matrix population model can either 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. Because transition rates of zero do generally yield non-zero sensitivities, it is important to distinguish between structural (i.e. impossible) zeros and sampled zeros when summing multiple sensitivities for a given process (e.g., progression/growth).

By default, the perturb_ functions assume that a transition rate of 0 indicates an impossible transition, in which case the sensitivity for that transition will not be included in any calculation. Specifically, the arguments posX are specified by the logical expression (matX > 0). If the matrix population model includes transitions that are possible but estimated to be 0, users should specify the posX argument(s) manually.

If there are no possible transitions for a given process (e.g., clonality, in many species), the value of sensitivity or elasticity returned for that process will be NA.

Value

A list with 5 elements:

stasis

The sensitivity or elasticity of demog_stat to stasis.

retrogression

The sensitivity or elasticity of demog_stat to retrogression.

progression

The sensitivity or elasticity of demog_stat to progression.

fecundity

The sensitivity or elasticity of demog_stat to sexual fecundity.

clonality

The sensitivity or elasticity of demog_stat to clonality.

Excluding stages

It may be desirable to exclude one or more stages from the calculation. For instance, we might not believe that 'progression' to a dormant stage class truly reflects progression. In this case we could exclude transitions to the dormant stage class using the argument exclude_row. We may or may not want to ignore progression transitions from the dormant stage class, which can be done in a similar way using the argument exclude_col. The exclude_ arguments simply set the relevant row or column of the posX arguments to FALSE, to prevent those transitions from being used in subsequent calculations.

Author(s)

Rob Salguero-Gómez <[e-mail]>

Patrick Barks <[e-mail]>

See Also

Other perturbation analysis: perturb_matrix(), perturb_stochastic(), perturb_vr(), pop_vectors()

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_trans(matU, matF)

# Use a larger perturbation than the default of 1e-6.
perturb_trans(matU, matF, pert = 0.01)

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

# Second, run the perturbation analysis using demog_stat = "damping".
perturb_trans(matU, matF, demog_stat = "damping")