arlefko2: Create Raw Ahistorical Age x Stage Matrix Projection Model

Description

Function arlefko2() returns raw ahistorical age x stage MPMs corresponding to the patches and occasion times given, including the associated component transition and fecundity matrices, data frames detailing the characteristics of ahistorical stages and the exact age-stage combinations corresponding to rows and columns in estimated matrices, and a data frame characterizing the patch and occasion time combinations corresponding to these matrices.

Usage

arlefko2(
  data,
  stageframe,
  year = "all",
  pop = NULL,
  patch = NULL,
  censor = FALSE,
  stages = NULL,
  alive = c("alive3", "alive2"),
  obsst = NULL,
  size = c("sizea3", "sizea2"),
  sizeb = NULL,
  sizec = NULL,
  repst = c("repstatus3", "repstatus2"),
  matst = c("matstatus3", "matstatus2"),
  fec = c("feca3", "feca2"),
  supplement = NULL,
  repmatrix = NULL,
  overwrite = NULL,
  agecol = "obsage",
  yearcol = NULL,
  popcol = NULL,
  patchcol = NULL,
  indivcol = NULL,
  censorcol = NULL,
  censorkeep = 0,
  final_age = NA,
  continue = TRUE,
  prebreeding = TRUE,
  NRasRep = FALSE,
  reduce = FALSE,
  simple = FALSE,
  err_check = FALSE,
  sparse_output = FALSE
)

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 patches and occasions. All matrices output in R's 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 R's 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 R's 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 age-by-stage MPMs.
agestages: A data frame showing the stage number and stage name corresponding to ahstages, as well as the associated age, of each row in each age-by-stage matrix.
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 patch and year of each matrix in order. In aflefko2(), only one population may be analyzed at once, and so pop = NA
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.

Arguments

data: A vertical demographic data frame, with variables corresponding to the naming conventions in verticalize3() and historicalize3().
stageframe: A stageframe object that includes information on the size, observation status, propagule status, reproduction status, immaturity status, and maturity status of each ahistorical stage. Should also incorporate bin widths if size is continuous.
year: A variable corresponding to observation occasion, or a set of such values, given in values associated with the year term used in linear model development. Defaults to "all", in which case matrices will be estimated for all occasions.
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 NA, in which case patch designations are ignored.
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.
stages: An optional vector denoting the names of the variables within the main vertical dataset coding for the stages of each individual in occasions t+1 and t. The names of stages in these variables should match those used in the stageframe exactly. If left blank, then arlefko2() will attempt to infer stages by matching values of alive, size, repst, and matst to characteristics noted in the associated stageframe.
alive: A vector of names of binomial variables corresponding to status as alive (1) or dead (0) in occasions t+1 ans t, respectively.
obsst: A vector of names of binomial variables corresponding to observation status in occasions t+1, t, and t-1, respectively. Defaults to NULL, in which case observation status is not used.
size: A vector of names of variables coding the primary size variable in occasions t+1 and t, respectively. Defaults to c("sizea3", "sizea2").
sizeb: A vector of names of variables coding the secondary size variable in occasions t+1 and t, respectively. Defaults to NULL, in which case this variable is not used.
sizec: A vector of names of variables coding the tertiary size variable in occasions t+1 and t, respectively. Defaults to NULL, in which case this variable is not used.
repst: A vector of names of variables coding reproductive status in occasions t+1 and t, respectively. Defaults to c("repstatus3", "repstatus2"). Must be supplied if stages is not provided.
matst: A vector of names of variables coding maturity status in occasions t+1 and t, respectively. Defaults to c("matstatus3", "matstatus2"). Must be supplied if stages is not provided.
fec: A vector of names of variables coding fecundity in occasions t+1 and t, respectively. Defaults to c("feca3", "feca2").
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. Can be used in place of or in addition to an overwrite table (see overwrite below) and a reproduction matrix (see repmatrix below).
repmatrix: An optional reproduction matrix. This matrix is composed mostly of 0s, with non-zero entries acting as element identifiers and multipliers for fecundity (with 1 equaling full fecundity). If left blank, and no supplement is provided, then aflefko2() will assume that all stages marked as reproductive produce offspring at 1x that of estimated fecundity, and that offspring production will yield the first stage noted as propagule or immature. To prevent this behavior, input just 0, which will result in fecundity being estimated only for transitions noted in supplement above. Must be the dimensions of an ahistorical stage-based matrix.
overwrite: An optional data frame developed with the overwrite() function describing transitions to be overwritten either with given values or with other estimated transitions. Note that this function supplements overwrite data provided in supplement.
agecol: The variable name or column number coding for age in time t.
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.
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.
final_age: The final age to model in the matrix. Defaults to the maximum age in the dataset.
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.
prebreeding: A logical value indicating whether the life history model is a pre-breeding model. Defaults to TRUE.
NRasRep: If data does not include stage assignments, then this option determines whether non-reproductive and reproductive individuals should be lumped into the same stages. Defaults to FALSE.
reduce: A logical value denoting whether to remove age-stages 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.
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.

Notes

The default behavior of this function is to estimate fecundity with regards to transitions specified via associated fecundity multipliers in either supplement or repmatrix. If both of these fields are left empty, then fecundity will be estimated at full for all transitions leading from reproductive stages to immature and propagule stages. However, if a supplement is provided and a repmatrix is not, or if repmatrix is set to 0, then only fecundity transitions noted in the supplement will be set to non-zero values. To use the default behavior of setting all reproductive stages to reproduce at full fecundity into immature and propagule stages but also incorporate given or proxy survival transitions, input those given and proxy transitions through the overwrite options.

The reproduction matrix (field repmatrix) may only be supplied as ahistorical. If provided as historical, then rlefko2() will fail and produce an error.

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.

Although this function is capable of assigning stages given an input stageframe, it lacks the power of verticalize3() and historicalize3() in this regard. Users are strongly encouraged to use the latter two functions for stage assignment.

Examples

Run this code

# \donttest{
# Cypripedium example
data(cypdata)

sizevector <- c(0, 0, 0, 0, 0, 0, 1, 2.5, 4.5, 8, 17.5)
stagevector <- c("SD", "P1", "P2", "P3", "SL", "D", "XSm", "Sm", "Md", "Lg",
  "XLg")
repvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
obsvector <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
immvector <- c(0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
indataset <- c(0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 0, 0, 0, 0, 0.5, 0.5, 1, 1, 2.5, 7)
minagevec <- c(1, 1, 2, 3, 4, 5, 5, 5, 5, 5, 5)
maxagevec <- c(rep(NA, 11))

cypframe_raw <- sf_create(sizes = sizevector, stagenames = stagevector,
  repstatus = repvector, obsstatus = obsvector, matstatus = matvector,
  propstatus = propvector, immstatus = immvector, indataset = indataset,
  binhalfwidth = binvec, minage = minagevec, maxage = maxagevec)

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",
  stageassign = cypframe_raw, stagesize = "sizeadded", NAas0 = TRUE,
  NRasRep = TRUE, age_offset = 4)

# Here we use supplemental() to provide overwrite and reproductive info
cypsupp2r <- supplemental(stage3 = c("SD", "P1", "P2", "P3", "SL", "D", 
    "XSm", "Sm", "SD", "P1"),
  stage2 = c("SD", "SD", "P1", "P2", "P3", "SL", "SL", "SL", "rep",
    "rep"),
  eststage3 = c(NA, NA, NA, NA, NA, "D", "XSm", "Sm", NA, NA),
  eststage2 = c(NA, NA, NA, NA, NA, "XSm", "XSm", "XSm", NA, NA),
  givenrate = c(0.10, 0.20, 0.20, 0.20, 0.25, NA, NA, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, NA, NA, NA, NA, 0.5, 0.5),
  type =c(1, 1, 1, 1, 1, 1, 1, 1, 3, 3),
  stageframe = cypframe_raw, historical = FALSE, agebased = TRUE)

cyp_mats <- arlefko2(data = cypraw_v1, stageframe = cypframe_raw, year = "all", 
  patch = NA, censor = FALSE, stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added"), fec = c("feca3", "feca2"),
  supplement = cypsupp2r, agecol = "obsage", yearcol = "year2", 
  patchcol = "patchid", indivcol = "individ", prebreeding = TRUE, final_age = NA,
  continue = TRUE, reduce = FALSE)
# }