maxatt: Calculate maximal attenuation
In popdemo: Demographic Modelling Using Projection Matrices

Description Usage Arguments Details Value References See Also Examples

Calculate maximal attenuation for a population matrix projection model.

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

`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 attenuation
`return.N`	(optional) if `TRUE`, returns population size at the point of maximal attenuation (including effects of asymptotic growth and initial population size), alongside standardised maximal attenuation.
`return.t`	(optional) if `TRUE`, returns the time at which maximal attenuation occurs in the population projection.
`return.stage`	(optional) if `TRUE` and `vector="n"`, returns the stage that achieves the bound on maximal attenuation.
`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`.

maxatt returns a standardised measure of maximal attenuation, 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 attenuation (the greatest maximal attenuation that may be achieved) is returned, otherwise a 'case-specific' maximal attenuation for the specified matrix and demographic structure is calculated. Note that not all demographic structures will yield a maximal attenuation: 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 attenuation (including the effects of asymptotic growth and initial population size), the time at which maximal attenuation occurs and (if vector="n"), the stage-bias that results in the bound on maximal attenuation, respectively. NOTE that N is not indicative of minuium possible population size for a non-standardised model: merely the population size at the point of maximal attenuation (i.e. largest negative deviation from lambda-max).

max.att uses a simulation technique, using project to project the dynamics of the model before evaluating minimum 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 attenuation is correctly captured in model projection.

maxatt will not work for imprimitive or reducible matrices.

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

maxatt: the bound on or case-specific maximal attenuation
N: the population size at the point of maximal attenuation, including the effects of initial population size and asymptotic growth. NOTE that N is not indicative of minimum possible population size for a non-standardised model: merely the population size at the point of maximal attenuation (i.e. largest negative deviation from lambda-max).
t: the projection interval at which maximal attenuation is achieved.
stage: (only if vector="n"), the stage that achieves the bound on maximal attenuation.

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.

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

  # 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(3,1,1) )

  # Calculate the bound on maximal attenuation of A
  maxatt(A)

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

  # Calculate case-specific maximal attenuation of A
  # and initial
  maxatt(A, vector=initial)

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