tfamatrix: Analyse transfer function

Description

Analyse the transfer function of a given population projection matrix (PPM) and perturbation structure.

Usage

tfamatrix(A, elementtype=NULL, Flim=c(-1,10), Plim=c(-1,10),
              plength=100, digits=1e-10)

Arguments

a square, irreducible, nonnegative matrix of any dimension

elementtype

(optional) a matrix describing the structure of A: "P" denotes elements bounded at 1, i.e. survival, growth, regression, "F" denotes elements not bounded at 1, i.e. fecundity, fission, and NA d

Flim,Plim

The perturbation ranges for "F" and "P" elements, expressed as a proportion of their magnitude (see details).

plength

The desired length of the perturbation ranges.

digits

specifies which values of lambda should be excluded to avoid a computationally singular system (see details).

Value

A list containing numerical arrays:
pthe perturbation magnitude.
lambdathe dominant eigenvalue of the perturbed matrix.
The first and second dimensions of the arrays are equivalent to the first and second dimensions of the matrix. The third dimension of the arrays are therefore the vectors returned by tfa. Therefore selecting e.g. $lambda[3,2,] will select the lambda values for element [3,2] of the matrix (for more information see examples).

Details

tfamatrix calculates an array of transfer functions for each nonzero element in A. Each element is perturbed individually. The function is most useful for use with the S3 method plot.tfamatrix to visualise how perturbations affect the life cycle and easily compare the effect on different transitions. The structure of the perturbations are determined by elementtype, Flim, Plim and plength. elementtype gives the nature of each transition, specifying whether perturbations should be bounded at 1 or not. If elementtype is not directly specified, then the function assigns its own types, with those in the first row attributed "F", and elsewhere in the matrix being attributed "F" if the element >1 and "P" if the element is <=1. Flim and Plim then determine the desired perturbation magnitude, expressed as a proportion of the magnitude of the elements, whilst plength determines the length of the perturbation vector. So, if an "F" element is equal to 0.5 and Flim=c(-1,10) and plength=100 then the perturbation to that element is seq(-1*0.5,10*0.5,100-1) = seq(-0.5,5,100). The process is the same for "P" elements, except that these are bounded to give a maximum perturbed value of 1 (as growth/survival elements cannot be greater than unity). Both "F" and "P" elements are bounded to give a minimum perturbed value of 0. tfamatrix uses tfa to calculate transfer functions. digits is passed to tfa to prevent the problem of singular matrices (see details in tfa). tfamatrix will not work for reducible matrices.

References

Townley & Hodgson (2004) J. Appl. Ecol., 41, 1155-1161. Hodgson et al. (2006) J. Theor. Biol., 70, 214-224.

Examples

Run this code

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

    # Calculate the matrix of transfer functions using default arguments
    tfmat<-tfamatrix(A)
    tfmat

    # Plot the result
    plot(tfmat)
    
    # Plot the transfer function of element [3,2]
    par(mfrow=c(1,1))
    par(mar=c(5,4,4,2)+0.1)
    plot(tfmat$lambda[3,2,]~tfmat$p[3,2,],xlab="p",ylab="lambda",type="l")

    # Create a new matrix with fission of adults
    B <- A
    B[2,3] <- 0.9
    B

    # Calculate the matrix of transfer functions using chosen arguments
    # that give the exact structure of the new matrix
    # and perturb a minimum of half the value of an element and
    # a maximum of double the value of an element
    etype <- matrix(c(NA, "F", "F", "P", "P", "F", NA, "P", "P"), 
                    ncol=3, byrow=TRUE)
    etype
    tfmat2 <- tfamatrix(B, elementtype=etype, Flim=c(-0.5,2),
                        Plim=c(-0.5,2))
    tfmat2

    # Plot the new matrix of transfer functions
    plot(tfmat2)

Run the code above in your browser using DataLab