popdemo (version 1.3-1)

tfs_inertia: Calculate sensitivity of inertia using transfer functions

Description

Calculate the sensitivity of population inertia of a population matrix projection model using differentiation of the transfer function.

Usage

tfs_inertia(A, d=NULL, e=NULL, vector="n", bound=NULL, startval=0.001, 
            tolerance=1e-10,return.fit=FALSE,plot.fit=FALSE)
tfsm_inertia(A,vector="n",bound=NULL,startval=0.001,tolerance=1e-10)

Arguments

A

a square, primitive, nonnegative numeric matrix of any dimension

d, e

numeric vectors that determine the perturbation structure (see details).

vector

(optional) a numeric vector or one-column matrix describing the age/stage distribution ('demographic structure') used to calculate the transfer function of a 'case-specific' inertia

bound

(optional) specifies whether the transfer funciton of an upper or lower bound on inertia should be calculated (see details).

startval

tfs_inertia calculates the limit of the derivative of the transfer function as lambda of the perturbed matrix approaches the dominant eigenvalue of A (see details). startval provides a starting value for the algorithm: the smaller startval is, the quicker the algorithm should converge.

tolerance

the tolerance level for determining convergence (see details).

return.fit

if TRUE (and only if d and e are specified), the lambda and sensitivity values obtained from the convergence algorithm are returned alongside the sensitivity at the limit.

plot.fit

if TRUE then convergence of the algorithm is plotted as sensitivity~lambda.

Value

For tfs_inertia, the sensitivity of inertia (or its bound) to the specified perturbation structure. If return.fit=TRUE a list containing components:

sens

the sensitivity of inertia (or its bound) to the specified perturbation structure

lambda.fit

the lambda values obtained in the fitting process

sens.fit

the sensitivity values obtained in the fitting process.

For tfsm_inertia, a matrix containing sensitivity of inertia (or its bound) to each separate element of A.

Details

tfs_inertia and tfsm_inertia differentiate a transfer function to find sensitivity of population inertia to perturbations.

tfs_inertia evaluates the transfer function of a specific perturbation structure. The perturbation structure is determined by d%*%t(e). Therefore, the rows to be perturbed are determined by d and the columns to be perturbed are determined by e. The values in d and e determine the relative perturbation magnitude. For example, if only entry [3,2] of a 3 by 3 matrix is to be perturbed, then d = c(0,0,1) and e = c(0,1,0). If entries [3,2] and [3,3] are to be perturbed with the magnitude of perturbation to [3,2] half that of [3,3] then d = c(0,0,1) and e = c(0,0.5,1). d and e may also be expressed as numeric one-column matrices, e.g. d = matrix(c(0,0,1), ncol=1), e = matrix(c(0,0.5,1), ncol=1). See Hodgson et al. (2006) for more information on perturbation structures.

tfsm_inertia returns a matrix of sensitivity values for observed transitions (similar to that obtained when using sens to evaluate sensitivity of asymptotic growth), where a separate transfer function for each nonzero element of A is calculated (each element perturbed independently of the others).

The formula used by tfs_inertia and tfsm_inertia cannot be evaluated at lambda-max, therefore it is necessary to find the limit of the formula as lambda approaches lambda-max. This is done using a bisection method, starting at a value of lambda-max + startval. startval should be small, to avoid the potential of false convergence. The algorithm continues until successive sensitivity calculations are within an accuracy of one another, determined by tolerance: a tolerance of 1e-10 means that the sensitivity calculation should be accurate to 10 decimal places. However, as the limit approaches lambda-max, matrices are no longer invertible (singular): if matrices are found to be singular then tolerance should be relaxed and made larger.

For tfs_inertia, there is an extra option to return and/or plot the above fitting process using return.fit=TRUE and plot.fit=TRUE respectively.

References

• Stott et al. (2012) Methods Ecol. Evol., 3, 673-684.

See Also

Other TransferFunctionAnalyses: tfa_inertia(), tfa_lambda(), tfam_inertia(), tfam_lambda(), tfs_lambda()

Other PerturbationAnalyses: elas(), sens(), tfa_inertia(), tfa_lambda(), tfam_inertia(), tfam_lambda(), tfs_lambda()

Examples

# NOT RUN {
  # Create a 3x3 matrix
  ( A <- matrix(c(0,1,2,0.5,0.1,0,0,0.6,0.6), byrow=TRUE, ncol=3) )

  # Create an initial stage structure    
  ( initial <- c(1,3,2) )

  # Calculate the sensitivity matrix for the upper bound on inertia
  tfsm_inertia(A, bound="upper",tolerance=1e-7)

  # Calculate the sensitivity of simultaneous perturbation to 
  # A[1,3] and A[2,3] for the lower bound on inertia
  tfs_inertia(A, d=c(1,0,0), e=c(0,1,1), bound="lower")

  # Calculate the sensitivity of simultaneous perturbation to 
  # A[1,3] and A[2,3] for specified initial stage structure
  # and return and plot the fitting process
  tfs_inertia(A, d=c(1,0,0), e=c(0,1,1), vector=initial,tolerance=1e-7,
              return.fit=TRUE,plot.fit=TRUE)

# }