lefko3 (version 3.7.0)

flefko2: Create Function-based Ahistorical Matrix Projection Model

Description

Function flefko2() returns ahistorical MPMs corresponding to the patches and years given, including the associated component transition and fecundity matrices, a data frame detailing the characteristics of the ahistorical stages used, and a data frame characterizing the patch and year combinations corresponding to these matrices. Unlike rlefko2() and rlefko3(), this function does not currently distinguish populations.

Usage

flefko2(
  year = "all",
  patch = "all",
  stageframe,
  supplement = NA,
  repmatrix = NA,
  overwrite = NA,
  data = NA,
  modelsuite = NA,
  surv_model = NA,
  obs_model = NA,
  size_model = NA,
  repst_model = NA,
  fec_model = NA,
  jsurv_model = NA,
  jobs_model = NA,
  jsize_model = NA,
  jrepst_model = NA,
  paramnames = NA,
  inda = 0,
  indb = 0,
  indc = 0,
  surv_dev = 0,
  obs_dev = 0,
  size_dev = 0,
  repst_dev = 0,
  fec_dev = 0,
  jsurv_dev = 0,
  jobs_dev = 0,
  jsize_dev = 0,
  jrepst_dev = 0,
  repmod = 1,
  yearcol = NA,
  patchcol = NA,
  year.as.random = FALSE,
  patch.as.random = FALSE,
  randomseed = NA,
  negfec = FALSE,
  reduce = FALSE,
  err_check = 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. Can also equal all, in which case matrices will be estimated for all years. Defaults to all.

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.

stageframe

A stageframe object that includes information on the size, observation status, propagule status, immaturity status, and maturity status of each ahistorical stage. Should also incorporate bin widths if size is continuous.

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

A reproduction matrix, which is an optional matrix composed mostly of 0s, with non-zero values for each potentially new individual (row) born to each reproductive stage (column). Entries act as multipliers on fecundity, with 1 equaling full fecundity. Fecundity multipliers provided this way supplement rather than replace those provided in supplement. If left blank, then flefko2() will assume that all stages marked as reproductive produce offspring at 1x that of fecundity estimated in provided linear models, and that fecundity will be into 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 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.

data

The original historical demographic data frame used to estimate vital rates (class hfvdata). The original data frame is required in order to initialize years and patches properly.

modelsuite

An optional lefkoMod object holding the vital rate models. If given, then surv_model, obs_model, size_model, repst_model, fec_model, jsurv_model, jobs_model, jsize_model, jrepst_model, paramnames, yearcol, and patchcol are not required. No models should include size or reproductive status in occasion t-1.

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. If given, then will overwrite any survival probability model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

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. If given, then will overwrite any observation probability model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

size_model

A linear model predicting size. This can be a model of class glm or glmer, both of which require a predicted poisson variable under a log link, or a model of class lm or lmer, in which a Gaussian response is assumed. If given, then will overwrite any size model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

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. If given, then will overwrite any reproduction probability model given in modelsuite. 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 or glmer, and requires a predicted poisson variable under a log link. If given, then will overwrite any fecundity model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

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. If given, then will overwrite any juvenile survival probability model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

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. If given, then will overwrite any juvenile observation probability model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

jsize_model

A linear model predicting juvenile size. This can be a model of class glm or glmer, both of which require a predicted poisson variable under a log link, or a model of class lm or lmer, in which a Gaussian response is assumed. If given, then will overwrite any juvenile size model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

jrepst_model

A linear model predicting reproduction probability of a mature individual that was immature in the previous year. This can be a model of class glm or glmer, and requires a predicted binomial variable under a logit link. If given, then will overwrite any reproduction probability model given in modelsuite. This model must have been developed in a modeling exercise testing only the impacts of occasion t.

paramnames

A dataframe with two columns, the first showing the general model terms that will be used in matrix creation, and the second showing the equivalent terms used in modeling. Only required if modelsuite is not supplied.

inda

A numeric value to use for individual covariate a. Defaults to 0.

indb

A numeric value to use for individual covariate b. Defaults to 0.

indc

A numeric value to use for individual covariate c. Defaults to 0.

surv_dev

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

obs_dev

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

size_dev

A numeric value to be added to the y-intercept in the linear model for size.

repst_dev

A numeric value to be added to the y-intercept in the linear model for probability of reproduction.

fec_dev

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

jsurv_dev

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

jobs_dev

A numeric value to be added to the y-intercept in the linear model for juvenile observation probability.

jsize_dev

A numeric value to be added to the y-intercept in the linear model for juvenile size.

jrepst_dev

A numeric value to be added to the y-intercept in the linear model for juvenile reproduction probability.

repmod

A scalar multiplier of fecundity. Defaults to 1.

yearcol

The variable name or column number corresponding to year in occasion t in the dataset. Not needed if a modelsuite is supplied.

patchcol

The variable name or column number corresponding to patch in the dataset. Not needed if a modelsuite is supplied.

year.as.random

A logical term indicating whether coefficients for missing patches within vital rate models should be estimated as random intercepts. Defaults to FALSE, in which case missing monitoring occasion coefficients are set to 0.

patch.as.random

A logical term indicating whether coefficients for missing patches within vital rate models should be estimated as random intercepts. Defaults to FALSE, in which case missing patch coefficients are set to 0.

randomseed

A numeric value used as a seed to generate random estimates for missing occasion and patch coefficients, if either year.as.random or patch.as.random is set to TRUE. Defaults to set.seed() default.

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 ahistorical stages 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.

err_check

A logical value indicating whether to add matrices of vital rate probabilities associated with each matrix. Defaults to 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 years. All matrices output in the matrix class.

U

A list of survival transition matrices sorted as in A. All matrices output in the matrix class.

F

A list of fecundity matrices sorted as in A. All matrices output in the matrix class.

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 patch and year of each matrix in order. In flefko2(), only one population may be analyzed at once, and so pop = NA

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 4 columns in the order of survival, observation probability, reproduction probability, and size transition probability.

Notes

This function will yield incorrect estimates if the models utilized incorporate state in occasion t-1. Only use models developed testing for ahistorical effects.

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 option.

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

Users may at occasions 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.

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 will probably also lead to fatal errors.

Using the err_check option will produce a matrix of 4 columns, each characterizing a different vital rate. The product of each row yields an element in the associated $U matrix. The number and order of elements in each column of this matrix matches the associated matrix in column vector format. Use of this option is generally for the purposes of debugging code.

Examples

# NOT RUN {
# Lathyrus example
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)

lathmodelsln2 <- modelsearch(lathvertln, historical = FALSE, 
  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 = TRUE)

# Here we use supplemental to provide overwrite and reproductive info
lathsupp2 <- supplemental(stage3 = c("Sd", "Sdl", "Sd", "Sdl"), 
  stage2 = c("Sd", "Sd", "rep", "rep"),
  givenrate = c(0.345, 0.054, NA, NA),
  multiplier = c(NA, NA, 0.345, 0.054),
  type = c(1, 1, 3, 3), stageframe = lathframeln, historical = FALSE)

lathmat2ln <- flefko2(year = "all", patch = "all", stageframe = lathframeln, 
  modelsuite = lathmodelsln2, data = lathvertln, supplement = lathsupp2,
  patchcol = "patchid", yearcol = "year2", year.as.random = FALSE,
  patch.as.random = FALSE, reduce = FALSE)

summary(lathmat2ln)
# }
# NOT RUN {
# }