rleslie {lefko3}

Create Raw Leslie (Age-based) Matrix Projection Model

Description

Function rleslie() returns raw Leslie MPMs, including the associated component transition and fecundity matrices, a data frame describing the ages used, and a data frame describing the population, patch, and occasion time associated with each matrix.

Usage

rleslie(
  data,
  start_age = NA,
  last_age = NA,
  continue = TRUE,
  fecage_min = NA,
  fecage_max = NA,
  alive = c("alive3", "alive2", "alive1"),
  repst = c("repstatus3", "repstatus2", "repstatus1"),
  fec = c("feca3", "feca2", "feca1"),
  agecol = "obsage",
  year = "all",
  supplement = NULL,
  pop = NULL,
  patch = NULL,
  yearcol = NULL,
  popcol = NULL,
  patchcol = NULL,
  indivcol = NULL,
  censor = FALSE,
  censorcol = NULL,
  censorkeep = 0,
  fectime = 2,
  fecmod = 1,
  prebreeding = TRUE,
  reduce = FALSE,
  simple = FALSE,
  err_check = FALSE,
  sparse_output = FALSE
)

Arguments

data

A vertical demographic data frame, with variables corresponding to the naming conventions in verticalize3().

start_age

The age from which to start the matrix. Defaults to NA, age 1 is used if prebreeding = TRUE, and age 0 is used if prebreeding = FALSE.

last_age

The final age to use in the matrix. Defaults to NA, in which case the highest age in the dataset is used.

continue

A logical value designating whether to allow continued survival of individuals past the final age noted in the stageframe, using the demographic characteristics of the final age. Defaults to TRUE.

fecage_min

The minimum age at which reproduction is possible. Defaults to NA, which is interpreted to mean that fecundity should be assessed starting in the minimum age observed in the dataset.

fecage_max

The maximum age at which reproduction is possible. Defaults to NA, which is interpreted to mean that fecundity should be assessed until the final observed age.

alive

A vector of names of binomial variables corresponding to status as alive (1) or dead (0) in occasions t+1 ans t, respectively.

repst

A vector of names of variables coding reproductive status in occasions t+1 and t, respectively. Defaults to c("repstatus3", "repstatus2").

fec

A vector of names of variables coding fecundity in occasions t+1 and t, respectively. Defaults to c("feca3", "feca2").

agecol

The name or column number of the variable coding for age in data. Defaults to "obsage".

year

A variable corresponding to observation occasion, or a set of such values, given in values associated with the year term used in vital rate model development. Can also equal "all", in which case matrices will be estimated for all occasion times. Defaults to "all".

supplement

An optional data frame of class lefkoSD that provides supplemental data that should be incorporated into the MPM. Three kinds of data may be integrated this way: transitions to be estimated via the use of proxy transitions, transition overwrites from the literature or supplemental studies, and transition multipliers for survival and fecundity. This data frame should be produced using the supplemental() function.

pop

A variable designating which populations will have matrices estimated. Should be set to specific population names, or to "all" if all populations should have matrices estimated.

patch

A variable designating which patches or subpopulations will have matrices estimated. Should be set to specific patch names, or to "all" if matrices should be estimated for all patches. Defaults to "all".

yearcol

The variable name or column number corresponding to occasion t in the dataset.

popcol

The variable name or column number corresponding to the identity of the population.

patchcol

The variable name or column number corresponding to patch in the dataset.

indivcol

The variable name or column number coding individual identity.

censor

If TRUE, then data will be removed according to the variable set in censorcol, such that only data with censor values equal to censorkeep will remain. Defaults to FALSE.

censorcol

The variable name or column number denoting the censor status. Only needed if censor = TRUE.

censorkeep

The value of the censor variable denoting data elements to keep. Defaults to 0.

fectime

An integer indicating whether to estimate fecundity using the variable given for fec in time t (2) or time t+1 (3).

fecmod

A scalar multiplier for fecundity. Defaults to 1.0.

prebreeding

A logical value indicating whether the life history model is a pre-breeding model. Defaults to TRUE.

reduce

A logical value denoting whether to remove ages associated with only zero transitions. These are removed only if the respective row and column sums in ALL matrices estimated equal 0. Defaults to FALSE, and should generally not be used in age-based MPMs.

simple

A logical value indicating whether to produce A, U, and F matrices, or only the latter two. Defaults to FALSE, in which case all three are output.

err_check

A logical value indicating whether to append extra information used in matrix calculation within the output list. Defaults to FALSE.

sparse_output

A logical value indicating whether to output matrices in sparse format. Defaults to FALSE, in which case all matrices are output in standard matrix format.

Value

If all inputs are properly formatted, then this function will return an object of class lefkoMat, which is a list that holds the matrix projection model and all of its metadata. Its structure is a list with the following elements:

A

A list of full projection matrices in order of sorted populations, patches, and occasions. All matrices output in the matrix class, or in the dgCMatrix class from the Matrix package if sparse.

U

A list of survival transition matrices sorted as in A. All matrices output in the matrix class, or in the dgCMatrix class from the Matrix package if sparse.

F

A list of fecundity matrices sorted as in A. All matrices output in the matrix class, or in the dgCMatrix class from the Matrix package if sparse.

hstages

A data frame matrix showing the pairing of ahistorical stages used to create historical stage pairs. Set to NA for ahistorical matrices.

agestages

A data frame showing age-stage pairs. In this function, it is set to NA. Only used in output to function aflefko2().

ahstages

A data frame detailing the characteristics of associated ahistorical stages, in the form of a modified stageframe that includes status as an entry stage through reproduction.

labels

A data frame giving the population, patch, and year of each matrix in order.

dataqc

A vector showing the numbers of individuals and rows in the vertical dataset used as input.

matrixqc

A short vector describing the number of non-zero elements in U and F matrices, and the number of annual matrices.

modelqc

This is the qc portion of the modelsuite input in function-based MPMs. Empty in this function.

Notes

In order to accomodate survival to time t+1 in the final year of a study, the maximum age assessed if no input last_age is provided is one time step past the final described age.

Users may at times wish to estimate MPMs using a dataset incorporating multiple patches or subpopulations. Should the aim of analysis be a general MPM that does not distinguish these patches or subpopulations, the patchcol variable should be left to NA, which is the default. Otherwise the variable identifying patch needs to be named.

Input options including multiple variable names must be entered in the order of variables in occasion t+1 and t. Rearranging the order WILL lead to erroneous calculations, and may lead to fatal errors.

See Also

mpm_create()

flefko3()

flefko2()

aflefko2()

arlefko2()

fleslie()

rlefko3()

rlefko2()

Examples

data(cypdata)

cypraw_v1 <- verticalize3(data = cypdata, noyears = 6, firstyear = 2004,
  patchidcol = "patch", individcol = "plantid", blocksize = 4,
  sizeacol = "Inf2.04", sizebcol = "Inf.04", sizeccol = "Veg.04",
  repstracol = "Inf.04", repstrbcol = "Inf2.04", fecacol = "Pod.04",
  age_offset = 3, NAas0 = TRUE, NRasRep = TRUE)

cyp_rl <- rleslie(data = cypraw_v1, start_age = 0, last_age = 4,
  continue = TRUE, fecage_min = 3, year = "all", pop = NA, patch = "all",
  yearcol = "year2", patchcol = "patchid", indivcol = "individ")