tfs_lambda: Calculate sensitivity using transfer functions
In popdemo: Demographic Modelling Using Projection Matrices

Description Usage Arguments Details Value References See Also Examples

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

1
2
3

tfs_lambda(A, d=NULL, e=NULL, startval=0.001, tolerance=1e-10, 
           return.fit=FALSE, plot.fit=FALSE)
tfsm_lambda(A, startval=0.001, tolerance=1e-10)

`A`	a square, nonnegative numeric matrix of any dimension.
`d, e`	numeric vectors that determine the perturbation structure (see details).
`startval`	`tfs_lambda` 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` 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_lambda and tfsm_lambda differentiate a transfer function to find sensitivity of the dominant eigenvalue of A to perturbations. This provides an alternative method to using matrix eigenvectors to calculate the sensitivity matrix and is useful as it may incorporate a greater diversity of perturbation structures.

tfs_lambda 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_lambda returns a matrix of sensitivity values for observed transitions (similar to that obtained when using sens to evaluate sensitivity using eigenvectors), 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_lambda and tfsm_lambda 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_lambda, 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_lambda, the sensitivity of lambda-max to the specified perturbation structure. If return.fit=TRUE a list containing components:

sens: the sensitivity of lambda-max 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_lambda, a matrix containing sensitivity of lambda-max to each element of A.

Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

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

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

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

  # Calculate the sensitivity matrix
  tfsm_lambda(A)

  # Calculate the sensitivity of simultaneous perturbation to 
  # A[1,2] and A[1,3]
  tfs_lambda(A, d=c(1,0,0), e=c(0,1,1))

  # Calculate the sensitivity of simultaneous perturbation to 
  # A[1,2] and A[1,3] and return and plot the fitting process
  tfs_lambda(A, d=c(1,0,0), e=c(0,1,1),
             return.fit=TRUE, plot.fit=TRUE)