tfam_lambda: Transfer function analysis
In popdemo: Demographic Modelling Using Projection Matrices

Description Usage Arguments Details Value References See Also Examples

Transfer function analysis of the dominant eigenvalue of a population matrix projection model for all matrix elements.

tfam_lambda(
  A,
  elementtype = NULL,
  Flim = c(-1, 10),
  Plim = c(-1, 10),
  plength = 100,
  digits = 1e-10
)

`A`	a square, irreducible, nonnegative numeric matrix of any dimension
`elementtype`	(optional) a character matrix of the same dimension as `A` describing the structure of `A`: `"P"` denotes elements bounded between 0 and 1, i.e. survival, growth, regression; `"F"` denotes elements not bounded at 1, i.e. fecundity, fission; `NA` denotes absent elements (see details).
`Flim, Plim`	the perturbation ranges for `"F"` and `"P"` elements, expressed as a proportion of their magnitude (see details).
`plength`	the desired length of the perturbation ranges.
`digits`	specifies which values of lambda should be excluded from analysis to avoid a computationally singular system (see details).

tfam_lambda calculates an array of transfer functions of the dominant eigenvalue of A. A separate transfer function for each nonzero element of A is calculated (each element perturbed independently of the others). The function is most useful for use with the S3 method plot.tfam to visualise how perturbations affect the life cycle transitions, and easily compare the (nonlinear) effect of perturbation to different transitions on the dominant eigenvalue.

The sizes of the perturbations are determined by elementtype, Flim, Plim and plength. elementtype gives the type of each element, specifying whether perturbations should be bounded at 1 (elementtype = "P") or not (elementtype = "F"). If elementtype is not directly specified, the function assigns its own types, with those in the first row attributed "F", and elsewhere in the matrix attributed "F" if the value of the element >1 and "P" if the value of the element is <=1. Flim and Plim determine the desired perturbation magnitude, expressed as a proportion of the magnitude of the elements of A, whilst plength determines the length of the perturbation vector. For example, if an "F" element is equal to 0.5, Flim=c(-1,10) and plength=100 then the perturbation to that element is seq(-1*0.5,10*0.5,100-1). The process is the same for "P" elements, except that these are truncated to a maximum value of 1 (growth/survival elements cannot be greater than 1). Both "F" and "P" elements are truncated to a minimum value of 0.

tfam_lambda uses tfa_lambda to calculate transfer functions. digits is passed to tfa_lambda to prevent the problem of singular matrices (see details in tfa_lambda).

tfam_lambda will not work for reducible matrices.

A list containing numerical arrays:

p: perturbation magnitudes
lambda: dominant eigenvalues of perturbed matrices

The first and second dimensions of the arrays are equivalent to the first and second dimensions of A. The third dimension of the arrays are the vectors returned by tfa_lambda. e.g. $lambda[3,2,] selects the lambda values for the transfer function of element [3,2] of the matrix.

Townley & Hodgson (2004) J. Appl. Ecol., 41, 1155-1161.
Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

S3 plotting method: plot.tfa

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

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

  # Calculate the matrix of transfer functions using default arguments
  ( tfmat<-tfam_lambda(A) )

  # Plot the result using the S3 method
  plot(tfmat)

  # Plot the transfer function of element [3,2] without using the S3 method
  par(mfrow=c(1,1))
  par(mar=c(5,4,4,2)+0.1)
  plot(tfmat$lambda[3,2,]~tfmat$p[3,2,],xlab="p",ylab="lambda",type="l")

  # Create a new matrix with fission of adults
  B <- A; B[2,3] <- 0.9; B

  # Calculate the matrix of transfer functions using chosen arguments
  # that give the exact structure of the new matrix
  # and perturb a minimum of half the value of an element and
  # a maximum of double the value of an element
  ( etype <- matrix(c(NA, "F", "F", "P", "P", "F", NA, "P", "P"), 
                  ncol=3, byrow=TRUE) )
  ( tfmat2 <- tfam_lambda(B, elementtype=etype, Flim=c(-0.5,2),
                      Plim=c(-0.5,2)) )

  # Plot the new matrix of transfer functions using the S3 method
  plot(tfmat2)