project: Project population dynamics

Description

Project dynamics of a specified population projection matrix (PPM) model.

Usage

project(A, vector="n", time=100, standard.A=FALSE, 
            standard.vec=FALSE, return.vec=FALSE)

Arguments

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

vector

(optional) a specified initial age/stage distribution of class vector or class matrix with which to project dynamics.

time

the number of projection intervals.

standard.A

(optional) if TRUE, standardises the PPM by scaling it by its dominant eigenvalue so that asymptotic dynamics of the projection are removed.

standard.vec

(optional) if TRUE, standardises vector to sum to 1 by scaling it by sum(vector).

return.vec

(optional) if TRUE, returns the time series of vectors of demographic distribution as well as overall population size.

Value

If vector is specified, a vector of population sizes of length time+1. If vector="n", a matrix of population projections: each column represents a single stage-biased projection and each column is of length time+1. If return.vec=TRUE, a list with components:
Nthe vector or matrix of population sizes
vecIf vector is specified, a matrix of demographic vectors from projection of vector through A. Each column represents the densities of one life stage in the projection. If vector="n", an array of demographic vectors from projection of the set of stage-biased vectors through A. The first dimension represents time (and is therefore equal to time+1 in length). The second dimension represents the densities of each stage (and is therefore equal to the dimension of A in length). The third dimension represents each individual stage-biased projection (and is therefore also equal to the dimension of A in length). So for example, if we projected a 3 by 3 matrix for >10 time intervals (see examples) then the density of stage 3 in bias 2 at time 10 is found at element [11,3,2] (remembering that because element 1 represents t=0, then t=10 is found at element 11); the time series of densities of stage 2 in bias 1 is found using [,2,1]; the matrix of population vectors for bias 2 would be found using [,,2].

Details

If vector is specified, then project will project the dynamics of the specified model using that vector. However, if vector="n", then project will automatically project the set of stage-biased vectors of A. In practise, these projections are achieved using a set of standard basis vectors, each with every element equal to 0, except for a single element that is equal to 1 (i.e. for a 3 by 3 matrix, the set of stage-biased vectors are: c(1,0,0), c(0,1,0) and c(0,0,1).) Projections returned are of length time+1, as the first element represents the population at t=0. Projections have their own S3 plotting method to enable easy graphing.

Examples

Run this code

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

    # Project stage-biased dynamics of A over 70 intervals
    pr <- project(A,time=70)
    pr
    plot(pr)

    # Select the projection of stage 2 bias
    pr[,2]

    # Project stage-biased dynamics of standardised A over 30 
    # intervals and return demographic vectors
    pr2 <- project(A, time=30, standard.A=TRUE, return.vec=TRUE)
    pr2
    plot(pr2)

    #Select the projection of stage 2 bias
    pr2$N[,2]

    # Select the density of stage 3 in bias 2 at time 10
    pr2$vec[11,3,2]

    # Select the time series of densities of stage 2 in bias 1
    pr2$vec[,2,1]

    #Select the matrix of population vectors for bias 2
    pr2$vec[,,2]

    # Project A over 50 intervals using a specified population structure
    pr3 <- project(A, vector=initial, time=50)
    pr3
    plot(pr3)

    # Project standardised dynamics of A over 10 intervals using 
    # standardised initial structure and return demographic vectors
    pr4 <- project(A, vector=initial, time=10, standard.vec=TRUE, 
                   standard.A=TRUE, return.vec=TRUE)
    pr4
    plot(pr4)
    
    # Select the time series for stage 1
    pr4$vec[,1]