R/perturb_trans.R
perturb_trans.RdCalculates 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.
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",
...
)The survival component submatrix of a MPM (i.e., a square projection matrix reflecting survival-related transitions; e.g., progression, stasis, and retrogression).
The sexual component submatrix of a MPM (i.e., a square projection matrix reflecting transitions due to sexual reproduction).
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.
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).
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).
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).
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.
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.
The magnitude of the perturbation (defaults to 1e-6).
An argument defining whether to return `sensitivity` or `elasticity` values. Defaults to `sensitivity`.
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.
A list with 5 elements:
The sensitivity or elasticity
of demog_stat to stasis.
The sensitivity or
elasticity of demog_stat to retrogression.
The
sensitivity or elasticity of demog_stat to progression.
The sensitivity or elasticity of demog_stat to
sexual fecundity.
The sensitivity or elasticity of
demog_stat to clonality.
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.
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.
Other perturbation analysis:
perturb_matrix(),
perturb_stochastic(),
perturb_vr(),
pop_vectors()
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)
#> $stasis
#> [1] 1.000001
#>
#> $retro
#> [1] 0.4171896
#>
#> $progr
#> [1] 1.428538
#>
#> $fecundity
#> [1] 0.3016217
#>
#> $clonality
#> [1] NA
#>
# Use a larger perturbation than the default of 1e-6.
perturb_trans(matU, matF, pert = 0.01)
#> $stasis
#> [1] 1.005989
#>
#> $retro
#> [1] 0.4167755
#>
#> $progr
#> [1] 1.418785
#>
#> $fecundity
#> [1] 0.3014444
#>
#> $clonality
#> [1] NA
#>
# 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")
#> $stasis
#> [1] 0.2627447
#>
#> $retro
#> [1] 3.807707
#>
#> $progr
#> [1] -4.831068
#>
#> $fecundity
#> [1] 1.276311
#>
#> $clonality
#> [1] NA
#>