popdemo (version 0.1-2)

maxatt: Calculate maximal attenuation

Description

Calculate maximal attenuation for a specified population projection matrix (PPM) model.

Usage

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

Arguments

A

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

vector

(optional) a specified initial age/stage distribution of class vector or class matrix with which 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 convergence.time.

conv.accuracy

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

Value

• If vector="n", the bound on maximal attenuation of A. If vector is specified, the case-specific maximal attenuation of the model. In addition, 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 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.

Details

maxatt returns a standardised measure of maximal attenuation, so 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 largest maximal attenuation that may be achieved) is returned, otherwise a case-specific maximal attenuation for the specified PPM and demographic structure is calculated. Note that not all specified demographic structures will yield a maximal attenuation: if the model does not attenuate 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 interval 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 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). 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 convergence.time, 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.

References

Stott et al. (2011) Ecol. Lett., 14, 959-970. Townley & Hodgson (2008) J. Appl. Ecol., 45, 1836-1839.

See Also

Other indices of transient density: reactivity, firststepatt, maxamp, inertia

Examples

# Create a 3x3 PPM
    A <- matrix(c(0,1,2,0.5,0.1,0,0,0.6,0.6), byrow=TRUE, ncol=3)
    A

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

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