popdemo (version 1.3-1)

tfa_lambda: Transfer function analysis

Description

Transfer function analysis of the dominant eigenvalue of a population matrix projection model using a specified perturbation structure.

Usage

tfa_lambda(A, d, e, prange = NULL, lambdarange = NULL, digits = 1e-10)

Arguments

A

a square, irreducible, nonnegative numeric matrix of any dimension

d, e

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

prange

a numeric vector giving the range of perturbation magnitude (see details)

lambdarange

a numeric vector giving the range of lambda values (asymptotic growth rates) to be achieved (see details).

digits

specifies which values of lambda should be excluded from analysis to avoid a computationally singular system (see details).

Value

A list containing numerical vectors:

p

the perturbation magnitude(s).

lambda

the dominant eigenvalue(s) of the perturbed matrix(matrices)

.

(Note that p will not be exactly the same as prange when prange is specified, as the code calculates p for a given lambda rather than the other way around, with prange only used to determine max, min and number of lambda values to evaluate.)

Details

tfa_lambda calculates the transfer function of the dominant eigenvalue of a matrix (A), given a perturbation structure (specified using d and e), and either a range of target values for asymptotic population growth (lambdavalues) or a range of desired perturbation magnitude (prange). Currently tfa_lambda can only work with rank- one, single-parameter perturbations (see Hodgson & Townley 2004).

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

The perturbation magnitude is determined by prange, a numeric vector that gives the continuous range of perterbation magnitude to evaluate over. This is usually a sequence (e.g. prange=seq(-0.1,0.1,0.001)), but single transfer functions can be calculated using a single perturbation magnitude (e.g. prange=-0.1). Because of the nature of the equation, prange is used to find a range of lambda from which the perturbation magnitudes are back-calculated, so the output perturbation magnitude p will match prange in length and range but not in numerical value (see value). Alternatively, a vector lambdarange can be specified, representing a range of target lambda values from which the corresponding perturbation values will be calculated. Only one of either prange or lambdarange may be specified.

tfa_lambda uses the resolvent matrix in its calculation, which cannot be computed if any lambda are equal to the dominant eigenvalue of A. digits specifies the values of lambda that should be excluded in order to avoid a computationally singular system. Any values equal to the dominant eigenvalue of A rounded to an accuracy of digits are excluded. digits should only need to be changed when the system is found to be computationally singular, in which case increasing digits should help to solve the problem.

tfa_lambda will not work for reducible matrices.

There is an S3 plotting method available (see plot.tfa and examples below)

References

• Townley & Hodgson (2004) J. Appl. Ecol., 41, 1155-1161.

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

See Also

S3 plotting method: plot.tfa

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

Other PerturbationAnalyses: elas(), sens(), tfa_inertia(), tfam_inertia(), tfam_lambda(), tfs_inertia(), 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) )

  # Calculate the transfer function of A[3,2] given a range of lambda
  evals <- eigen(A)$values
  lmax <- which.max(Re(evals))
  lambda <- Re(evals[lmax])
  lambdarange <- seq(lambda-0.1, lambda+0.1, 0.01)
  ( transfer <- tfa_lambda(A, d=c(0,0,1), e=c(0,1,0), lambdarange=lambdarange) )

  # Plot the transfer function using the S3 method
  plot(transfer)

  # Calculate the transfer function of perturbation to A[3,2] and A[3,3]
  # with perturbation to A[3,2] half that of A[3,3], given a range of 
  # perturbation values
  p<-seq(-0.6,0.4,0.01)
  ( transfer2 <- tfa_lambda(A, d=c(0,0,1), e=c(0,0.5,1), prange=p) )

  # Plot p and lambda without using the S3 method
  plot(transfer$lambda~transfer$p, type="l", xlab="p", ylab=expression(lambda))

# }