popdemo (version 0.2-3)

tfa : Analyse transfer function

Description

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

Usage

tfa(A, d, e, prange=NULL, lambdarange=NULL, digits=1e-10)

Arguments

A

a square, irreducible, nonnegative matrix of any dimension

d,e

numeric vectors that determine the perturbation structure (see details).

lambdarange

a numeric vector giving the range of lambda values (asymptotic growth rates) to be achieved.

prange

a numeric vector giving the range of perturbation magnitude.

digits

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

Value

A list containing numerical vectors:

p

the perturbation magnitude.

lambda

the dominant eigenvalue of the perturbed matrix.

(Note that p will not be exactly the same as prange when specified, as the code calculates p for a given lambda rather than the other way around, with prange only used to determine max, min and number of lambda values to evaluate.)

Details

tfa calculates the transfer function of a matrix given a perturbation structure and a range of desired lambda values or a range of desired perturbation magnitude. Currently tfa can only work with rank-one, single-parameter perturbations (see Hodgson & Townley 2004).

The perturbation structure is determined by d%*%t(e). Therefore, the rows to be perturbed are determined by d and the columns to be perturbed are determined by e. The specific values in d and e will determine the relative perturbation magnitude. So for example, if only entry [3,2] of a 3 by 3 matrix is to be perturbed, then d = c(0,0,1) and e = c(0,1,0). If entries [3,2] and [3,3] are to be perturbed with the magnitude of perturbation to [3,2] half that of [3,3] then d = c(0,0,1) and e = c(0,0.5,1). d and e may also be expressed as column vectors of class matrix, e.g. d = matrix(c(0,0,1), ncol=1), e = matrix(c(0,0.5,1), ncol=1). See Hodgson et al. (2006) for more information on perturbation structures.

The perturbation magnitude is determined by prange, a numeric vector that gives the continuous range of perterbation magnitude to evaluate over. This is usually a sequence (e.g. prange=seq(-0.1,0.1,0.001)), but single transfer functions can be calculated using a single perturbation magnitude (e.g. prange=-0.1). Because of the nature of the equation, prange is used to find a range of lambda from which the perturbation magnitudes are back-calculated and matched to their corresponding inertia, so that the output perturbation magnitude p will match prange in length and range but not in numerical value (see value). Alternatively, a vector lambdarange can be specified, representing a range of desired lambda values from which the corresponding perturbation values will be calculated. Only one of either prange or lambdarange may be specified.

tfa uses the resolvent matrix in its calculation, which cannot be computed if any lambdarange are equal to the dominant eigenvalue of A. digits specifies the values of lambda that should be excluded in order to avoid a computationally singular system. Any values equal to the dominant eigenvalue of A rounded to an accuracy of digits are excluded. digits should only need to be changed when the system is found to be computationally singular, in which case increasing digits should help to solve the problem.

tfa will not work for reducible matrices.

There is an S3 plotting method available (see plot.tfa and examples below)

References

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

See Also

S3 plotting method: plot.tfa

Related: tfamatrix

Sensitivity methods: tfsens

Examples

    # 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 transfer function of A[3,2] given a range of lambda
    evals<-eigen(A)$values
    lmax<-which.max(Re(evals))
    lambda<-Re(evals[lmax])
    lambdarange <- seq(lambda-0.1, lambda+0.1, 0.01)
    transfer<-tfa(A, d=c(0,0,1), e=c(0,1,0), lambdarange=lambdarange)
    transfer

    # Plot the transfer function (defaults to lambda~p)
    plot(transfer)

    # Calculate the transfer function of perturbation to A[3,2] and A[3,3]
    # with perturbation to A[3,2] half that of A[3,3], given a range of 
    # perturbation values
    p<-seq(-0.6,0.4,0.01)
    transfer2<-tfa(A, d=c(0,0,1), e=c(0,0.5,1), prange=p)
    transfer2

    # Plot p and lambda by hand
    plot(transfer$lambda~transfer$p,type="l", xlab="p",ylab=expression(lambda))