tfs_inertia: Calculate sensitivity of inertia using transfer functions
In popdemo: Demographic Modelling Using Projection Matrices

Description Usage Arguments Details Value References See Also Examples

View source: R/tfs_inertia&tfsm_inertia.R

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

1
2
3

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)

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

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.

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.

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

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

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