fleslie {lefko3}

Create Function-based Age-based (Leslie) Matrix Projection Model

Description

Function fleslie() returns age-based (Leslie) MPMs corresponding to the patches and occasions given, including the associated component transition and fecundity matrices, data frames detailing the characteristics of the exact ages corresponding to rows and columns in estimated matrices, and a data frame characterizing the patch and occasion combinations corresponding to these matrices.

Usage

fleslie(
  year = "all",
  patch = NULL,
  prebreeding = TRUE,
  data = NULL,
  modelsuite = NULL,
  surv_model = NULL,
  fec_model = NULL,
  paramnames = NULL,
  supplement = NULL,
  start_age = NA,
  last_age = NA,
  fecage_min = NA,
  fecage_max = NA,
  continue = TRUE,
  inda = NULL,
  indb = NULL,
  indc = NULL,
  surv_dev = 0,
  fec_dev = 0,
  density = NA,
  fecmod = 1,
  random.inda = FALSE,
  random.indb = FALSE,
  random.indc = FALSE,
  negfec = FALSE,
  reduce = FALSE,
  simple = FALSE,
  err_check = FALSE,
  exp_tol = 700,
  theta_tol = 1e+08,
  sparse_output = FALSE
)

Arguments

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.

patch

A variable designating which patches or subpopulations will have matrices estimated. Defaults to "all", but can also be set to specific patch names or a vector thereof.

prebreeding

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

data

The historical vertical demographic data frame used to estimate vital rates (class hfvdata). The original data frame is generally required in order to initialize occasions and patches properly, and to assess the range of ages observed in the population. Not required if option modelsuite is set to a vrm_input object.

modelsuite

One of two optional lists. THe first is an optional lefkoMod object holding the vital rate models. Alternatively, an object of class vrm_input may be provided. If given, then surv_model, fec_model, and paramnames are not required. No models should include size or reproductive status in any occasion, nor should they include any variable for occasion t-1. Note that the modelsuite must have been created from a modelsearch() run in which vitalrates = c("surv", "fec") and the suite option was set to either age or cons.

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 only the impacts of occasion t.

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 only the impacts of occasion t.

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.

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.

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.

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.

inda

Can be a single value to use for individual covariate a in all matrices, or a vector of such values corresponding to each occasion in the dataset. Defaults to NULL.

indb

Can be a single value to use for individual covariate b in all matrices, or a vector of such values corresponding to each occasion in the dataset. Defaults to NULL.

indc

Can be a single value to use for individual covariate c in all matrices, or a vector of such values corresponding to each occasion in the dataset. Defaults to NULL.

surv_dev

A numeric value to be added to the y-intercept in the linear model for survival probability. Defaults to 0.

fec_dev

A numeric value to be added to the y-intercept in the linear model for fecundity. Defaults to 0.

density

A numeric value indicating density value to use to propagate matrices. Only needed if density is an explanatory term used in linear models. Defaults to NA.

fecmod

A scalar multiplier of fecundity. Defaults to 1.0.

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.

negfec

A logical value denoting whether fecundity values estimated to be negative should be reset to 0. Defaults to FALSE.

reduce

A logical value denoting whether to remove ages associated solely with 0 transitions. These are only removed in cases where the associated 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.

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.

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 has 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

Set to NA for Leslie MPMs.

agestages

Set to NA for Leslie MPMs.

ahstages

A data frame detailing the characteristics of associated ages, in the form of a modified stageframe including reproduction status.

labels

A data frame giving the patch and year of each matrix in order. In fleslie(), only one population may be analyzed at once.

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.

prob_out

An optional element only added if err_check = TRUE. This is a list of vital rate probability matrices, with 7 columns in the order of survival, observation probability, reproduction probability, primary size transition probability, secondary size transition probability, tertiary size transition probability, and probability of juvenile transition to maturity.

Notes

Unlike rlefko2(), rlefko3(), arlefko2(), and rleslie(), this function does not currently distinguish populations.

This function will yield incorrect estimates if the models utilized incorporate state in occasion t-1, or any size or reproductive status terms.

Users may at times wish to estimate MPMs using a dataset incorporating multiple patches or subpopulations, but without discriminating between those patches or subpopulations. Should the aim of analysis be a general MPM that does not distinguish these patches or subpopulations, the modelsearch() run should not include patch terms.

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.

Care should be taken to match the random status of year and patch to the states of those variables within the modelsuite. If they do not match, then they will be treated as zeroes in vital rate estimation.

Individual covariates are treated as categorical only if they are set as random terms. Fixed categorical individual covariates are currently not allowed. However, such terms may be supplied if the modelsuite option is set to a vrm_input object. In that case, the user should also set the logical random switch for the individual covariate to be used to TRUE (e.g., random.inda = TRUE).

See Also

mpm_create()

flefko3()

flefko2()

aflefko2()

arlefko2()

rlefko3()

rlefko2()

rleslie()

Examples

data(lathyrus)

lathvert_base <- verticalize3(lathyrus, noyears = 4, firstyear = 1988,
  patchidcol = "SUBPLOT", individcol = "GENET", blocksize = 9,
  sizeacol = "Volume88", repstracol = "FCODE88", fecacol = "Intactseed88",
  deadacol = "Dead1988", censorcol = "Missing1988", censorkeep = NA,
  censor = TRUE, NAas0 = TRUE, NRasRep = TRUE, NOasObs = TRUE)

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

lathvert_age <- subset(lathvert_base, firstseen > 1988)

lath_survival <- glm(alive3 ~ obsage + as.factor(year2), data = lathvert_age,
  family = "binomial")
lath_fecundity <- glm(feca2 ~ obsage + as.factor(year2), data = lathvert_age,
  family = "poisson")

mod_params <- create_pm(name_terms = TRUE)
mod_params$modelparams[22] <- "obsage"

lathmat2fleslie <- fleslie(year = "all", data = lathvert_age,
  surv_model = lath_survival, fec_model = lath_fecundity,
  paramnames = mod_params, fecage_min = 1)