Projection-class: 'Projection' object S4 class

Description

Projection objects are created using the project function. Primarily, they contain overall population size over time: they can be treated as a vector (single population projection) or matrix (multiple population projections; see information on slot ".Data" below). They also contain further information on the population projection. These extra pieces of information are described below in the "Slots" section, and the methods for accessing them appear below. These are:

vec: access population vectors
bounds: access bounds on population dynamics
mat: access projection matrix/matrices used to create projection(s)
Aseq: access projection matrix sequence used to create projection(s)
projtype: find out projection type
vectype: access type of vector used to initiate population projection(s)

Other methods for accessing basic information from the projection are:

nproj: access projection matrix/matrices used to create projection
nmat: number of projection matrices used to create projection(s)
ntime: number of time intervals

Plotting and display methods for 'Projection' objects can be found on the Projection-plots page.

Usage

vec(object)
# S4 method for Projection
vec(object)
bounds(object)
# S4 method for Projection
bounds(object)
mat(object, ...)
# S4 method for Projection
mat(object, return = "simple")
Aseq(object)
# S4 method for Projection
Aseq(object)
projtype(object)
# S4 method for Projection
projtype(object)
vectype(object)
# S4 method for Projection
vectype(object)
nproj(object)
# S4 method for Projection
nproj(object)
nmat(object)
# S4 method for Projection
nmat(object)
ntime(object)
# S4 method for Projection
ntime(object)
show(object)
# S4 method for Projection
show(object)

Arguments

object

an object of class "Projection" generated using project

...

further arguments (see method, below)

return

either "simple", "list", or "array": used for accessing the 'mat' slot from a Projection object. Note that only list or array can be used for stochastic projections, which have more than one matrix.

Slots

.Data

One or more time series of population sizes. 'Projection' objects inherit from a standard array, and can be treated as such. Therefore, if vector is specified, the 'Projection' object will behave as:

if a single vector is given, a numeric vector of population sizes of length time+1
if multiple vectors are given, a numeric matrix of population projections where each column represents a single population projection and is of length time+1
if vector="n", a numeric matrix of population projections where each column represents a single stage-biased projection and is of length time+1.
if vector="diri", a numeric matrix of population projections where each column represents projection of a single vector draw and each column is of length time+1.

vec

Age- or stage-based population vectors. vec will be:

If a single vector is specified, a numeric matrix of demographic vectors from projection of vector through A. Each column represents the densities of one life (st)age in the projection.
If multiple vectors are specified, a three-dimensional array of demographic vectors from projection of the set of initial vectors through A. The first dimension represents time (and is therefore equal to time+1). The second dimension represents the densities of each stage (and is therefore equal to the dimension of A). The third dimension represents each individual projection (and is therefore equal to the number of initial vectors given).
If vector="n", a three-dimensional 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). The second dimension represents the densities of each stage (and is therefore equal to the dimension of A). The third dimension represents each individual stage-biased projection (and is therefore also equal to the dimension of A).
Ifvector="diri", a three-dimensional array of demographic vectors from projection of the dirichlet vector draws projected through A. The first dimension represents time (and is therefore equal to time+1). The second dimension represents the densities of each stage (and is therefore equal to the dimension of A). The third dimension represents projection of each population draw (and is therefore equal to draws).

Some examples for understanding the structure of 3D arrays returned when return.vec=TRUE: when projecting a 3 by 3 matrix for >10 time intervals, element [11,3,2] represents the density of stage 3 at time 10 for either vector 2 (multiple vectors), stage-bias 2 (vector="n") or draw 2 (vector="diri"); note that because element 1 represents t=0, then t=10 is found at element 11. The vector [,3,2] represents the time series of densities of stage 3 in the projection of vector 2 / stage-bias 2 / draw 2. The matrix [,,2] represents the time series of all stages in the projection of vector 2 / stage-bias 2 / draw 2.

Note that the projections inherit the labelling from A and vector, if it exists. Both stage and vector names are taken from the COLUMN names of A and vector respectively. These may be useful for selecting from the projection object, and are used when labelling plots of Projection objects containing multiple population projections.

Set return.vec = FALSE when calling project to prevent population vectors from being saved: in this case, vec is equal to numeric(0). This may be necessary when projecting large numbers of vectors, as is the case when vector = "diri".

bounds

The bounds on population dynamics (only for deterministic projections). These represent the maximum and minimum population sizes achieveable at each time interval of the projection. bounds is a matrix with 2 columns (lower and upper bounds, in that order), and the number of rows is equal to time + 1.

mat

The matrix/matrices used in the population projection. In their raw form mat is always a three-dimensional array, where the third dimension is used to index the different matrices. However, by using the mat() accessor function below, it is possible to choose different ways of representing the matrices (matrix, list, array).

Aseq

The sequence of matrices used in the projection. For deterministic projections (where there is only 1 matrix) this will always be rep(1, time). For stochastic projections (with more than 1 matrix), if Aseq is given to project as a numeric or character vector then this slot will take that value. If a matrix describing a random markov process is passed, the Aseq slot will be a single random chain.

projtype

The type of projection. Either "deterministic" (single matrix; time-invariant), or "stochastic" (multiple matrices; time-varying).

vectype

The type of vector passed to project. May be "single" (one vector; one population projection), "multiple" (more than one vector; several population projections), "bias" (stage-biased vectors; vector = "n"), or "diri" (vectors drawn from the dirichlet distribution; vector = "diri").

Details

In addition to the examples below, see the "Deterministic population dynamics" and "Stochastic population dynamics" vignettes for worked examples that use the 'Projection' objects.

Examples

Run this code

# NOT RUN {
  ### USING PROJECTION OBJECTS

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

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

  # Access other slots
  vec(pr)  #time sequence of population vectors
  bounds(pr)  #bounds on population dynamics
  mat(pr)  #matrix used to create projection
  Aseq(pr)  #sequence of matrices (more useful for stochastic projections)
  projtype(pr)  #type of projection
  vectype(pr)  #type of vector(s) initiating projection

  # Extra information on the projection
  nproj(pr)  #number of projections
  nmat(pr)  #number of matrices (more usefulk for stochastic projections)
  ntime(pr)  #number of time intervals
  
  # Select the projection of stage 2 bias
  pr[,2]

  # Project stage-biased dynamics of standardised A over 30 intervals
  ( pr2 <- project(A, vector="n", time=30, standard.A=TRUE) )
  plot(pr2)

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

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

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

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

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

  # Project A over 50 intervals using a specified population structure
  ( pr3 <- project(A, vector=initial, time=50) )
  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) )
  plot(pr4)

  # Select the time series for stage 1
  vec(pr4)[,1]

# }