popdemo (version 0.1-2)

tfsens: Calculate sensitivity using transfer functions

Description

Calculate the sensitivity of perturbations to a population projection matrix using a transfer function method.

Usage

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

Arguments

A

a square, nonnegative matrix of any dimension.

d,e

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

startval

tfsens calculates the limit of the derivative of the transfer function as lambda approaches the dominant eigenvalue of A (see details). startval provides a starting value for the algorithm: the smaller

tolerance

the tolerance level for determining convergence (see details).

return.fit

if TRUE the lambda and sensitivity values obtained in the convergence algorithm are returned alongside the calculated sensitivity of inertia.

plot.fit

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

Value

• For tfsens, 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 tfsensmatrix, a matrix containing sensitivity of lambda-max to each seperate element of A.

Details

tfsens and tfsensmatrix differentiate a transfer function to find sensitivity to perturbation. This provides an alternative method to using matrix eigenvectors to calculate the sensitivity matrix and is useful as it may utilise more complex perturbation structures. tfsens may be used to find sensitivity of a particular perturbation structure. A desired 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 specific values in d and e will determine the relative perturbation magnitude. So 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 column vectors of class matrix, 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. tfsensmatrix returns a matrix of sensitivity values for observed transitions (similar to that obtained when using sens to evaluate sensitivity using eigenvectors), where the sensitivity of each matrix element is evaluated seperately. The formula used by tfsens and tfsensmatrix 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 become uninvertible (singular): if matrices are found to be singular then tolerance should be relaxed and made larger. For tfsens, there is an extra option to return and/or plot the above fitting process using return.fit=TRUE and plot.fit=TRUE respectively.

References

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

See Also

Transfer function methods: tfa, tfamatrix

Examples

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

    # Calculate the sensitivity matrix
    tfsensmatrix(A)

    # Calculate the sensitivity of simultaneous perturbation to 
    # A[1,2] and A[1,3]
    tfsens(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
    tfsens(A, d=c(1,0,0), e=c(0,1,1),
           return.fit=TRUE, plot.fit=TRUE)