popdemo (version 1.3-1)

maxamp: Calculate maximal amplification

Description

Calculate maximal amplification for a population matrix projection model.

Usage

maxamp(
  A,
  vector = "n",
  return.N = FALSE,
  return.t = FALSE,
  return.stage = FALSE,
  conv.iterations = 1e+05,
  conv.accuracy = 1e-05
)

Arguments

A

a square, primitive, non-negative numeric matrix of any dimension

vector

(optional) a numeric vector or one-column matrix describing the age/stage distribution ('demographic structure') used to calculate a 'case-specific' maximal amplification.

return.N

(optional) if TRUE, returns population size at the point of maximal amplification (including effects of asymptotic growth and initial population size), alongside standardised maximal amplification.

return.t

(optional) if TRUE, returns the time at which maximal amplification occurs in the population projection.

return.stage

(optional) if TRUE and vector="n", returns the stage that achieves the bound on maximal amplification.

conv.iterations

the maximum number of iterations allowed when calulating convergence time (see details). Please see iterations in convt.

conv.accuracy

the accuracy of convergence (see details). Please see accuracy in convt.

Value

If vector="n", the bound on maximal amplification of A. If vector is specified, the case-specific maximal amplification of the model. If return.N=TRUE, return.t=TRUE and/or return.stage=TRUE, a list with possible components:

maxamp

the bound on or case-specific maximal amplification

N

the population size at the point of maximal amplification, including the effects of initial population size and asymptotic growth. NOTE that N is not indicative of maximum possible population size for a non-standardised model: merely the population size at the point of maximal amplification (i.e. largest positive deviation from lambda-max).

t

the projection interval at which maximal amplification is achieved.

stage

(only if vector="n"), the stage that achieves the bound on maximal amplification.

Details

maxamp returns a standardised measure of maximal amplification, discounting the effects of both initial population size and asymoptotic growth (Stott et al. 2011).

If vector is not specified then the bound on maximal amplification (the largest maximal amplification that may be achieved) is returned, otherwise a 'case-specific' maximal amplification for the specified matrix and demographic structure is calculated. Note that not all demographic structures will yield a maximal amplification: if the model does not amplify then an error is returned.

Setting return.N=T, return.t=T and return.stage=T results in the function returning realised population size at maximal amplification (including the effects of asymptotic growth and initial population size), the time at which maximal amplification occurs and (if vector="n"), the stage-bias that results in the bound on maximal amplification, respectively. NOTE that N is not indicative of maximum possible population size for a non-standardised model: merely the population size at the point of maximal amplification (i.e. largest positive deviation from lambda-max).

max.amp uses a simulation technique, using project to project the dynamics of the model before evaluating maximum projected density over all t. conv.accuracy and conv.iterations are passed to convt, which is used to find the point of model convergence in order to ensure maximal amplification is correctly captured in model projection.

maxamp will not work for imprimitive or reducible matrices.

References

• Neubert & Caswell (1997) Ecology, 78, 653-665.

• Stott et al. (2011) Ecol. Lett., 14, 959-970.

• Townley & Hodgson (2008) J. Appl. Ecol., 45, 1836-1839.

See Also

Other TransientIndices: Kreiss(), inertia(), maxatt(), reac()

Examples

# NOT RUN {
  # Create a 3x3 PPM
  ( 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 bound on maximal amplification of A
  maxamp(A)

  # Calculate the bound on maximal amplification of A and 
  # return the stage that achieves it
  maxamp(A, return.stage=TRUE)

  # Calculate case-specific maximal amplification of A
  # and initial
  maxamp(A, vector=initial)

  # Calculate case-specific maximal amplification of A
  # and initial and return realised population size and the 
  # time at which it is achieved
  maxamp(A, vector=initial, return.N=TRUE, return.t=TRUE)

# }