popdemo (version 1.3-1)

tfa_inertia: Transfer function Analysis

Description

Transfer function analysis of inertia of a population matrix projection model using a specified perturbation structure.

Usage

tfa_inertia(A, d, e, vector = "n", bound = NULL, prange, digits = 1e-10)

Arguments

A

a square, primitive, nonnegative numeric matrix of any dimension

d, e

numeric vectors that determine the perturbation structure (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

bound

(optional) specifies whether the transfer funciton of an upper or lower bound on inertia should be calculated (see details).

prange

a numeric vector giving the range of perturbation magnitude (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

perturbation magnitudes

lambda

dominant eigenvalues of perturbed matrices

iteminertiainertias of perturbed 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_inertia calculates the transfer function of inertia of a population matrix projection model given a perturbation structure (specified using d and e), and a range of desired perturbation magnitude (prange). Currently tfa_inertia can only work with rank-one, single-parameter perturbations (see Hodgson & Townley 2006).

If vector="n" then either bound="upper" or bound="lower" must be specified, which calculate the transfer function of the upper or lower bound on population inertia (i.e. the largest and smallest values that inertia may take) respectively. Specifying vector overrides calculation of a bound, and will yield a transfer function of a 'case-specific' inertia.

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 used to calculate the transfer function, prange is used to find a range of lambda from which the perturbation magnitudes are back-calculated, and matched to their orresponding inertia, so the output perturbation magnitude p will match prange in length and range but not in numerical value (see Stott et al. 2012 for more information).

tfa_inertia uses the resolvent matrix in its calculation, which cannot be computed if any lambda in the equation 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_inertia will not work for reducible matrices.

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

References

• Stott et al. (2012) Methods Ecol. Evol., 3, 673-684.

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

See Also

S3 plotting method: plot.tfa

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

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

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

  # Calculate the transfer function of upper bound on inertia 
  # given a perturbation to A[3,2]
  ( transfer<-tfa_inertia(A, d=c(0,0,1), e=c(0,1,0), bound="upper",
                          prange=seq(-0.6,0.4,0.01)) )

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

  # Plot inertia against lambda using the S3 method
  plot(transfer, xvar="lambda", yvar="inertia")

  # Calculate the transfer function of case-specific inertia 
  # given perturbation to A[3,2] and A[3,3] with perturbation 
  # to A[3,2] half that of A[3,3]
  ( transfer2<-tfa_inertia(A, d=c(0,0,1), e=c(0,0.5,1), vector=initial,
                           prange=seq(-0.6,0.4,0.01)) )

  # Plot inertia against p using the S3 method
  plot(transfer2)

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

# }