tfam_lambda: Transfer function analysis

Description

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

Usage

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

Arguments

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

Value

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.

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.

References

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

Examples

Run this code

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

Run the code above in your browser using DataCamp Workspace