f_projection3: Project Function-based Matrix Projection Model

In lefko3: Historical and Ahistorical Population Projection Matrix Analysis

Project Function-based Matrix Projection Model

Description

Function f_projection3() develops and projects function-based matrix models. Unlike projection3(), which uses matrices provided as input via already created lefkoMat objects, function f_projection3() creates matrices at each time step from vital rate models and parameter inputs provided. Projections may be stochastic or not, and may be density dependent in either case. Also handles replication.

Usage

f_projection3(
  format,
  prebreeding = TRUE,
  start_age = NA_integer_,
  last_age = NA_integer_,
  fecage_min = NA_integer_,
  fecage_max = NA_integer_,
  cont = TRUE,
  stochastic = FALSE,
  standardize = FALSE,
  growthonly = TRUE,
  repvalue = FALSE,
  integeronly = FALSE,
  substoch = 0L,
  ipm_cdf = TRUE,
  nreps = 1L,
  times = 10000L,
  repmod = 1,
  exp_tol = 700,
  theta_tol = 1e+08,
  random_inda = FALSE,
  random_indb = FALSE,
  random_indc = FALSE,
  err_check = FALSE,
  quiet = FALSE,
  data = NULL,
  stageframe = NULL,
  supplement = NULL,
  repmatrix = NULL,
  overwrite = NULL,
  modelsuite = NULL,
  paramnames = NULL,
  year = NULL,
  patch = NULL,
  sp_density = NULL,
  ind_terms = NULL,
  dev_terms = NULL,
  surv_model = NULL,
  obs_model = NULL,
  size_model = NULL,
  sizeb_model = NULL,
  sizec_model = NULL,
  repst_model = NULL,
  fec_model = NULL,
  jsurv_model = NULL,
  jobs_model = NULL,
  jsize_model = NULL,
  jsizeb_model = NULL,
  jsizec_model = NULL,
  jrepst_model = NULL,
  jmatst_model = NULL,
  start_vec = NULL,
  start_frame = NULL,
  tweights = NULL,
  density = NULL,
  density_vr = NULL,
  sparse = NULL
)

Arguments

format	An integer indicating the kind of function-based MPM to create. Possible choices include: 1, Ehrlen-format historical MPM; 2, deVries-format historical MPM; 3, ahistorical MPM; 4, age-by-stage MPM; and 5, Leslie (age-based) MPM.
prebreeding	A logical value indicating whether the life history model is a pre-breeding model. Only used in Leslie and age-by-stage MPMs. Defaults to TRUE.
start_age	The age from which to start the matrix. Defaults to NA, in which case 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.
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.
cont	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.
stochastic	A logical value denoting whether to conduct a stochastic projection or a deterministic / cyclical projection.
standardize	A logical value denoting whether to re-standardize the population size to 1.0 at each occasion. Used in density-independent simulations in which it is more important to know the general trend in population growth than the explicit growth rate. Defaults to FALSE.
growthonly	A logical value indicating whether to produce only the projected population size at each occasion (TRUE), or also to produce vectors showing the stage distribution at each occasion (FALSE). Defaults to TRUE.
repvalue	A logical value indicating whether to calculate reproductive value vectors at each time step. Can only be set to TRUE if growthonly = FALSE. Setting to TRUE may dramatically increase the duration of calculations. Defaults to FALSE.
integeronly	A logical value indicating whether to round the number of individuals projected in each stage at each occasion to the nearest integer. Defaults to FALSE.
substoch	An integer value indicating whether to force survival- transition matrices to be substochastic in density dependent and density independent simulations. Defaults to 0, which does not enforce substochasticity. Alternatively, 1 forces all survival-transition elements to range from 0.0 to 1.0, and forces fecundity to be non-negative; and 2 forces all column rows in the survival-transition matrices to total no more than 1.0, in addition to the actions outlined for option 1. Both settings 1 and 2 change negative fecundity elements to 0.0.
ipm_cdf	A logical value indicating whether to estimate size transitions using the cumulative density function in cases with continuous distributions. Defaults to TRUE, with the midpoint method used if FALSE.
nreps	The number of replicate projections. Defaults to 1.
times	Number of occasions to iterate per replicate. Defaults to 10000.
repmod	A scalar multiplier of fecundity. Defaults to 1.
exp_tol	A numeric value used to indicate a maximum value to set exponents to in the core kernel to prevent numerical overflow. Defaults to 700.
theta_tol	A numeric value used to indicate a maximum value to theta as used in the negative binomial probability density kernel. Defaults to 100000000, but can be reset to other values during error checking.
random_inda	A logical value denoting whether to treat individual covariate a as a random, categorical variable. Otherwise is treated as a fixed, numeric variable. Defaults to FALSE.
random_indb	A logical value denoting whether to treat individual covariate b as a random, categorical variable. Otherwise is treated as a fixed, numeric variable. Defaults to FALSE.
random_indc	A logical value denoting whether to treat individual covariate c as a random, categorical variable. Otherwise is treated as a fixed, numeric variable. Defaults to FALSE.
err_check	A logical value indicating whether to append extra output for debugging purposes. Defaults to FALSE.
quiet	A logical value indicating whether warning messages should be suppressed. Defaults to FALSE.
data	The historical vertical demographic data frame used to estimate vital rates (class hfvdata), which is required to initialize times and patches properly. Variable names should correspond to the naming conventions in verticalize3() and historicalize3().
stageframe	An object of class stageframe. These objects are generated by function sf_create(), and include information on the size, observation status, propagule status, reproduction status, immaturity status, maturity status, stage group, size bin widths, and other key characteristics of each ahistorical stage. Required for all MPM formats except Leslie MPMs.
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 flefko3() 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. May be the dimensions of either a historical or an ahistorical matrix. If the latter, then all stages will be used in occasion t-1 for each suggested ahistorical transition.
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.
modelsuite	A lefkoMod object, at minimum with all required best-fit vital rate models and a paramnames data frame, and following the naming conventions used in this package. If given, then surv_model, obs_model, size_model, sizeb_model, sizec_model, repst_model, fec_model, jsurv_model, jobs_model, jsize_model, jsizeb_model, jsizec_model, jrepst_model, jmatst_model, paramnames, yearcol, and patchcol are not required. Although this is optional input, it is recommended, and without it separate vital rate model inputs (named XX_model) are required.
paramnames	A data frame with three columns, the first describing all terms used in linear modeling, the second (must be called mainparams) giving the general model terms that will be used in matrix creation, and the third showing the equivalent terms used in modeling (must be named modelparams). Function create_pm() can be used to create a skeleton paramnames object, which can then be edited. Only required if modelsuite is not supplied.
year	Either a single integer value corresponding to the year to project, or a vector of times elements with the year to use at each time step. Defaults to NA, in which the first year in the set of years in the dataset is projected. If a vector shorter than times is supplied, then this vector will be cycled.
patch	A value of NA, a single string value corresponding to the patch to project, or a vector of times elements with the patch to use at each time step. If a vector shorter than times is supplied, then this vector will be cycled. Note that this function currently does not handle multiple projections for different patches in the same run.
sp_density	Either a single numeric value of spatial density to use in vital rate models in all time steps, or a vector of times elements of such numeric values. Defaults to NA.
ind_terms	An optional data frame with 3 columns and times rows giving the values of individual covariates a, b, and c, respectively, for each projected time. Unused terms must be set to 0 (use of NA will produce errors.)
dev_terms	An optional data frame with 14 columns and times rows showing the values of the deviation terms to be added to each linear vital rate. The column order should be: 1: survival, 2: observation, 3: primary size, 4: secondary size, 5: tertiary size, 6: reproduction, 7: fecundity, 8: juvenile survival, 9: juvenile observation, 10: juvenile primary size, 11: juvenile secondary size, 12: juvenile tertiary size, 13: juvenile reproduction, and 14: juvenile maturity transition. Unused terms must be set to 0 (use of NA will produce errors.)
surv_model	A linear model predicting survival probability. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
obs_model	A linear model predicting sprouting or observation probability. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
size_model	A linear model predicting primary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
sizeb_model	A linear model predicting secondary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
sizec_model	A linear model predicting tertiary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
repst_model	A linear model predicting reproduction probability. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
fec_model	A linear model predicting fecundity. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jsurv_model	A linear model predicting juvenile survival probability. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jobs_model	A linear model predicting juvenile sprouting or observation probability. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jsize_model	A linear model predicting juvenile primary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jsizeb_model	A linear model predicting juvenile secondary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jsizec_model	A linear model predicting juvenile tertiary size. This can be a model of class glm, glmer, glmmTMB, zeroinfl, vglm, lm, or lmer. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jrepst_model	A linear model predicting reproduction probability of a mature individual that was immature in time t. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
jmatst_model	A linear model predicting maturity probability of an individual that was immature in time t. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. Ignored if modelsuite is provided. This model must have been developed in a modeling exercise testing the impacts of occasions t and t-1.
start_vec	An optional numeric vector denoting the starting stage distribution for the projection. Defaults to a single individual of each stage.
start_frame	An optional data frame characterizing stages, age-stages, or stage-pairs that should be set to non-zero values in the starting vector, and what those values should be. Can only be used with lefkoMat objects.
tweights	An optional numeric vector denoting the probabilistic weightings of year terms. Defaults to equal weighting among occasions.
density	An optional data frame describing the matrix elements that will be subject to density dependence, and the exact kind of density dependence that they will be subject to. The data frame used should be an object of class lefkoDens, which is the output from function density_input().
density_vr	An optional data frame describing density dependence relationships in vital rates, if such relationships are to be assumed. The data frame must be of class lefkoDensVR, which is the output from the function density_vr().
sparse	A text string indicating whether to use sparse matrix encoding ("yes") or dense matrix encoding ("no"). Defaults to "auto", in which case sparse matrix encoding is used with square matrices with at least 50 rows and no more than 50% of elements with values greater than zero. Can also be entered as a logical value if forced sparse (TRUE) or forced dense (FALSE) projection is desired.

Value

A list of class lefkoProj, which always includes the first three elements of the following, and also includes the remaining elements below when a lefkoMat object is used as input:

projection	A list of lists of matrices showing the total number of individuals per stage per occasion. The first list corresponds to each pop-patch followed by each population (this top-level list is a single element in f_projection3()). The inner list corresponds to replicates within each pop-patch or population.
stage_dist	A list of lists of the actual stage distribution in each occasion in each replicate in each pop-patch or population. The list structure is the same as in projection3().
rep_value	A list of lists of the actual reproductive value in each occasion in each replicate in each pop-patch or population. The list structure is the same as in projection3().
pop_size	A list of matrices showing the total population size in each occasion per replicate (row within data frame) per pop-patch or population (list element). Only a single pop-patch or population is allowed in f_projection3().
labels	A data frame showing the order of populations and patches in item projection.
ahstages	The original stageframe used in the study.
hstages	A data frame showing the order of historical stage pairs.
agestages	A data frame showing the order of age-stage pairs.
labels	A short data frame indicating the population (always 1), and patch (either the numeric index of the single chosen patch, or 1 in all other cases).
control	A short vector indicating the number of replicates and the number of occasions projected per replicate.
density	The data frame input under the density option. Only provided if input by the user.
density_vr	The data frame input under the density_vr option. Only provided if input by the user.

Notes

Population projection can be a very time-consuming activity, and it is most time-consuming when matrices need to be created at each time step. We have created this function to work as quickly as possible, but some options will slow analysis. First, the err_check option should always be set to FALSE, as the added created output will not only slow the analysis down but also potentially crash the memory if matrices are large enough. Second, the repvalue option should be set to FALSE unless reproductive values are genuinely needed, since this step requires concurrent backward projection and so in some cases may double total run time. Finally, if the only needed data is the total population size and age/stage structure at each time step, then setting growthonly = TRUE will yield the quickest possible run time.

Projections with large matrices may take a long time to run. To assess the likely running time, try using a low number of iterations on a single replicate first. For example, set nreps = 1 and times = 10 for a trial run. If a full run is set and takes too long, press the STOP button in RStudio to cancel the projection run, or click esc.

This function currently allows three forms of density dependence. The first modifies matrix elements on the basis of the input provided in option density, and so alters matrix elements once the matrix has already been created. The second form alters the vital rates estimated, and so estimates matrix elements using vital rate values already modified by density. This second form uses the input provided in option density_vr. These two forms of density dependence utilize the projected population size at some time to make these alterations. The third form of density dependence also alters the vital rates, but using spatial density supplied via option sp_density and only in vital rates in which spatial density is included as a fixed factor in the associated vital rate model.

When running density dependent simulations involving user-set exponents, such as the beta term in the Ricker function and both the alpha and beta terms in the Usher function, values above or below the computer limits may cause unpredictable behavior. Noted odd behavior includes sudden shifts in population size to negative values. This function produces warnings when such values are used, and the values used for warnings may be reset with the exp_tol term. In addition, this function resets beta values for the Ricker function automatically to positive or negative exp_tol, giving a warning when doing so.

Consistently positive population growth can quickly lead to population size numbers larger than can be handled computationally. In that circumstance, a continuously rising population size will suddenly become NaN for the remainder of the projection.

This function does not reduce the dimensionality of matrices developed for projection.

Speed can sometimes be increased by shifting from automatic sparse matrix determination to forced dense or sparse matrix projection. This will most likely occur when matrices have between 30 and 300 rows and columns. Defaults work best when matrices are very small and dense, or very large and sparse.

See Also

projection3()

flefko3()

flefko2()

aflefko2()

fleslie()

Examples

data(lathyrus)

sizevector <- c(0, 4.6, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3, 4, 5, 6, 7, 8,
  9)
stagevector <- c("Sd", "Sdl", "Dorm", "Sz1nr", "Sz2nr", "Sz3nr", "Sz4nr",
  "Sz5nr", "Sz6nr", "Sz7nr", "Sz8nr", "Sz9nr", "Sz1r", "Sz2r", "Sz3r", 
  "Sz4r", "Sz5r", "Sz6r", "Sz7r", "Sz8r", "Sz9r")
repvector <- c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1)
obsvector <- c(0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
matvector <- c(0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
immvector <- c(1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
propvector <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 
  0)
indataset <- c(0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)
binvec <- c(0, 4.6, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 
  0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5)

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

lathvertln <- verticalize3(lathyrus, noyears = 4, firstyear = 1988,
  patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9, 
  juvcol = "Seedling1988", sizeacol = "lnVol88", repstracol = "Intactseed88",
  fecacol = "Intactseed88", deadacol = "Dead1988", 
  nonobsacol = "Dormant1988", stageassign = lathframeln, stagesize = "sizea",
  censorcol = "Missing1988", censorkeep = NA, NAas0 = TRUE, censor = TRUE)

lathvertln$feca2 <- round(lathvertln$feca2)
lathvertln$feca1 <- round(lathvertln$feca1)
lathvertln$feca3 <- round(lathvertln$feca3)

lathmodelsln3 <- modelsearch(lathvertln, historical = TRUE, 
  approach = "mixed", suite = "main", 
  vitalrates = c("surv", "obs", "size", "repst", "fec"), juvestimate = "Sdl",
  bestfit = "AICc&k", sizedist = "gaussian", fecdist = "poisson", 
  indiv = "individ", patch = "patchid", year = "year2", year.as.random = TRUE,
  patch.as.random = TRUE, show.model.tables = TRUE, quiet = "partial")

lathsupp3 <- supplemental(stage3 = c("Sd", "Sd", "Sdl", "Sdl", "mat", "Sd", "Sdl"), 
  stage2 = c("Sd", "Sd", "Sd", "Sd", "Sdl", "rep", "rep"),
  stage1 = c("Sd", "rep", "Sd", "rep", "Sd", "mat", "mat"),
  eststage3 = c(NA, NA, NA, NA, "mat", NA, NA),
  eststage2 = c(NA, NA, NA, NA, "Sdl", NA, NA),
  eststage1 = c(NA, NA, NA, NA, "Sdl", NA, NA),
  givenrate = c(0.345, 0.345, 0.054, 0.054, NA, NA, NA),
  multiplier = c(NA, NA, NA, NA, NA, 0.345, 0.054),
  type = c(1, 1, 1, 1, 1, 3, 3), type_t12 = c(1, 2, 1, 2, 1, 1, 1),
  stageframe = lathframeln, historical = TRUE)

# While we do not use MPMs to initialize f_projections3(), we do use MPMs to
# initialize functions start_input() and density_input().
lathmat3ln <- flefko3(year = "all", patch = "all", stageframe = lathframeln, 
  modelsuite = lathmodelsln3, data = lathvertln, supplement = lathsupp3, 
  reduce = FALSE)

e3m_sv <- start_input(lathmat3ln, stage2 = "Sd", stage1 = "Sd", value = 1000)

e3d <- density_input(lathmat3ln, stage3 = c("Sd", "Sdl"),
  stage2 = c("rep", "rep"), stage1 = c("all", "all"), style = 1,
  time_delay = 1, alpha = 1, beta = 0, type = c(2, 2), type_t12 = c(1, 1))

trial7a <- f_projection3(format = 1, data = lathvertln,
  modelsuite = lathmodelsln3, stageframe = lathframeln, nreps = 2,
  times = 100, stochastic = TRUE, standardize = FALSE, growthonly = TRUE,
  integeronly = FALSE, substoch = 0, sp_density = 0, start_frame = e3m_sv,
  density = e3d)
summary(trial7a)

lefko3 documentation built on Oct. 14, 2023, 1:07 a.m.