popdemo (version 0.1-2)

Kreiss: Calculate Kreiss bounds

Description

Calculate the upper or lower Kreiss bound for a specified population projection matrix (PPM).

Usage

Kreiss(A, bound=NULL, return.r=FALSE, theta=1,
           rlimit=100, step1=1e-3, step2=1e-6)

Arguments

A

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

bound

(optional) specifies whether an upper or lower bound should be calculated.

return.r

(optional) specifies whether the value of r at which the Kreiss bound is achieved should be returned (see details).

theta

the value to which the Kriess bound is to be assessed relative to (see details).

rlimit

the maximum value of r that may be reached before the code breaks (see details).

step1,step2

determine the iterative process in calculating the Kreiss bound (see details).

Value

• The upper or lower Kreiss bound of A. If return.r=TRUE, a list with components:
• bound
  the upper or lower Kriess bound
• r
  the value of r at which the function is minimised/maximised.

Details

Kreiss by default returns a standardised Kreiss bound relative to both asymptotic growth/decline and initial population density (Townley & Hodgson 2008; Stott et al. 2011). It uses an iterative process that evaluates a function of the resolvent of A over a range of values r where r>theta. This iterative process finds the maximum/minimum of the function for the upper/lower bounds respectively. The process is determined using step1 and step2: in order to increase accuracy but keep computation time low, the function is evaluated forward in steps equal to step1 until the maximum/minimum is passed and then backward in steps of step2 to more accurately find the maximum/minimum itself. Therefore, step1 should be larger than step2. The balance between both will determine computation time, whilst accuracy is determined almost solely by step2. The defaults should be sufficient for most matrices. theta defaults to 1, which means the Kriess bound is assessed relative to both asymptotic growth and initial population size. Sometimes, the maximum/minimum of the function occurs at r-->theta, in which case r is equal to theta+step2. Setting return.r=TRUE tells the function to return the value of r where the maximum/minimum occurs alongside the value of the Kreiss bound. r may not exceed rlimit. Kreiss will not work with reducible matrices, and returns a warning for imprimitive matrices.

References

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

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

    # Calculate the upper Kreiss bound of A
    Kreiss(A, bound="upper")

    # Calculate the lower Kreiss bound of A
    Kreiss(A, bound="lower")

    # Calculate the upper Kreiss bound of A and return 
    # the value of r at which the function is maximised
    Kreiss(A, bound="upper", return.r=TRUE)