tfam_inertia: Transfer function Analysis
In popdemo: Demographic Modelling Using Projection Matrices

Description Usage Arguments Details Value References See Also Examples

Transfer function analysis of inertia of a population matrix projection model for all matrix elements.

tfam_inertia(
  A,
  bound = NULL,
  vector = "n",
  elementtype = NULL,
  Flim = c(-1, 10),
  Plim = c(-1, 10),
  plength = 100,
  digits = 1e-10
)

`A`	a square, primitive, nonnegative numeric matrix of any dimension
`bound`	(optional) specifies whether the transfer funciton of an upper or lower bound on inertia should be calculated (see details).
`vector`	(optional) a numeric vector or one-column matrix describing the age/stage distribution ('demographic structure') used to calculate the transfer function of a 'case-specific' inertia
`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_inertia calculates an array of transfer functions of population inertia. 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_inertia uses tfa_inertia to calculate transfer functions. digits is passed to tfa_inertia to prevent the problem of singular matrices (see details in tfa_inertia).

tfam_inertia will not work for reducible matrices.

A list containing numerical arrays:

p: perturbation magnitudes
lambda: dominant eigenvalues of perturbed matrices
inertia: inertias 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_inertia. e.g. $inertia[3,2,] selects the inertia values for the transfer function of element [3,2] of the matrix.

Stott et al. (2012) Methods Ecol. Evol., 3, 673-684.
Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

S3 plotting method: plot.tfam

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

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

  # Create an initial stage structure
  ( initial <- c(1,3,2))

  # Calculate the matrix of transfer functions for the upper bound on
  # inertia, using default arguments
  ( tfmat<-tfam_inertia(A,bound="upper") )

  # Plot the transfer function using the S3 method (defaults to p 
  # and inertia in this case)
  plot(tfmat)

  # Plot inertia against lambda using the S3 method
  plot(tfmat, xvar="lambda", yvar="inertia")
    
  # Plot the transfer function of element [3,2] without the S3 method
  par(mfrow=c(1,1))
  par(mar=c(5,4,4,2)+0.1)
  plot(tfmat$inertia[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 for specified
  # initial stage structure, 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_inertia(B, vector=initial, 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)