project3 {adapt3}R Documentation

Project Multiple MPMs With or Without Density Dependence

Description

Function project3 uses pre-existing or function-based MPMs to run community projection simulations, in which different populations are run as separate MPMs. Density dependence can be used with individual equivalence vectors specifying Lotka-Volterra coefficients to adjust overall population sizes to make them comparable.

Usage

project3(
  mpms = NULL,
  vrms = NULL,
  stageframes = NULL,
  supplements = NULL,
  equivalence = NULL,
  starts = NULL,
  years = NULL,
  patches = NULL,
  tweights = NULL,
  format = NULL,
  entry_time = NULL,
  sp_density = NULL,
  ind_terms = NULL,
  dev_terms = NULL,
  fb_sparse = NULL,
  firstage = NULL,
  finalage = NULL,
  fecage_min = NULL,
  fecage_max = NULL,
  cont = NULL,
  fecmod = NULL,
  density = NULL,
  density_vr = NULL,
  err_check = NULL,
  stochastic = FALSE,
  integeronly = FALSE,
  substoch = 0L,
  nreps = 1L,
  times = 10000L,
  prep_mats = 20L,
  force_fb = FALSE,
  exp_tol = 700,
  theta_tol = 1e+08
)

Arguments

mpms

An optional list of MPMs. Each MPM must be of class lefkoMat.

vrms

An optional list of vrm_input objects, each corresponding to a distinct MPM that will be created during projection. Each vrm_input object requires its own stageframe, entered in the same order via argument stageframes.

stageframes

An optional list of stageframes, corresponding in number and order to the MPMs in argument vrms. Each stageframe must be of class stageframe.

supplements

An optional list of data frames of class lefkoSD that provide supplemental data that should be incorporated into function-based MPMs. If used, then should be the same number of data frames as the number of MPMs provided in the list for argument vrms. MPMs that do not need supplemental data should be entered as NULL in this list. See supplemental() for details.

equivalence

An optional numeric vector, list of numeric vectors, data frame of class adaptEq, or list of data frames of class adaptEq. If a numeric vector, then must have the same number of elements as the number of MPMs, with each element giving the effect of an individual of each MPM relative to a reference individual. If a list of vectors, then the list should be composed of as many numeric vectors as MPMs, with each vector giving the effect of each individual in each stage relative to a reference individual. Data frames of class adaptEq, and lists of such data frames, can be made with function equiv_input(). Numeric entries used in these vectors can be thought of as Lotka-Volterra interaction terms, such as are used in multiple species competition models.

starts

An optional list of lefkoSV objects, which are data frames providing the starting numbers of individuals of each stage. If provided, then one is needed per MPM. If not provided, then all projections start with a single individual of each stage per MPM.

years

An optional term corresponding either to a single integer vector of time t values, if all MPMs will use the same time t or set of time t's, or a list of such vectors with each vector corresponding to each MPM in order. In the latter case, a vector composed of a single NA value is interpreted to mean that all time t values in the MPM should be utilized. If a vector shorter than times is supplied, then this vector will be cycled.

patches

An optional string vector with length equal to the number of MPMs, detailing the name of each patch to project for each MPM, in order. Only a single pop-patch may be projected for each MPM given. A value of NA can be supplied to indicate that the population-level matrices should be projected (if argument mpms is used and a population-level set of matrices exist), or that the first patch noted should be used. Defaults to the population-level set or the first patch, depending on whether the former exists.

tweights

An optional list composed of numeric vectors or matrices denoting the probabilities of choosing each matrix in each MPM in a stochastic projection. If an element of the list is a matrix, then a first-order Markovian environment is assumed, in which the probability of choosing a specific annual matrix depends on which annual matrix is currently chosen. If an element of the list is a vector, then the choice of annual matrix is assumed to be independent of the current matrix. Defaults to equal weighting among matrices. If used, then one element per MPM is required, with equal weighting assumed for any element set to NULL.

format

An optional integer vector indicating the kind of function-based MPM to create for each vrm_input object entered in argument vrms. Possible choices include: 1, Ehrlen-format historical MPM; 2, deVries-format historical MPM; 3, ahistorical MPM (default); 4, age-by-stage MPM; and 5, Leslie (age-based) MPM.

entry_time

An optional integer vector giving the entry time for each MPM into the projection. Defaults to a zero vector with the length of the number of MPMs, as given either by argument mpms or vrms.

sp_density

An optional argument for use with vrm_input objects that specifies the spatial density to be used in each time step. If used, may either be a numeric vector giving a single spatial density for each vrm_input object entered in argument vrms (in this case, the value of spatial density given for each vrm_input object will be held constant through the projection), or a list of as many numeric vectors as vrm_input objects, with the length of each vector giving the spatial density at each time step. If vectors are shorter than specified in times, then these values will be cycled.

ind_terms

An optional argument providing values of individual or environmental covariate values for vrm_input objects used in function-based projection. Can be set either to a single data frame with 3 columns giving values for up to 3 covariates across time (rows give the time order of these values), or a list of as many such data frames as vrm_input objects. In the latter case, vrm_input objects that do not use such covariates should have the associated element set to NULL. Unused terms within each data frame must be set to 0 (use of NA will produce errors.) If the number of rows is less than times, then these values will be cycled.

dev_terms

An optional list of data frames, one for each vrm_input object. Each should include 14 columns and up to 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). Single or small numbers of values per vital rate model are also allowed, and if the number of rows is less than times, then the terms will be cycled.

fb_sparse

A logical vector indicating whether function-based MPMs should be produced in sparse matrix format. Defaults to FALSE for each MPM.

firstage

An optional integer vector used for function-based Leslie and age-by-stage MPMs giving the starting ages in such MPMs. Use only if at least one MPM is both function-based and has age structure. Typically, the starting age in such MPMs should be set to 0 if post-breeding and 1 if pre-breeding. All other MPMs should be set to 0. Do not use if no MPM has age structure.

finalage

An optional integer vector used for function-based Leslie and age-by-stage MPMs giving the final ages in such MPMs. Use only if at least one MPM is both function-based and has age structure. Do not use if no MPM has age structure.

fecage_min

An optional integer vector used for function-based Leslie MPMs giving the first age at which organisms can be reproductive in such MPMs. Use only if at least one MPM is a function-based Leslie MPM. Defaults to the values given in firstage.

fecage_max

An optional integer vector used for function-based Leslie MPMs giving the final age at which organisms can be reproductive in such MPMs. Use only if at least one MPM is a function-based Leslie MPM. Defaults to the values given in finalage.

cont

An optional vector used for function-based Leslie and age-by-stage MPMs stating whether the MPM should should include a stasis transition within the final age. This should be used only when an organism can maintain the demographic characteristics of the final described age after reaching that age. Can be entered as a logical vector or an integer vector. MPMs without age structure should be entered as 0 or FALSE. Do not use if no MPM has age structure.

fecmod

An optional vector used for function-based MPMs giving scalar multipliers for fecundity terms, when two fecundity variables are used for a collective fecundity per individual. Each entry refers to each vrm_input object in argument vrms, in the same order.

density

An optional list of data frames of class lefkoDens, which provide details for density dependence in MPM elements and have been created with function density_input(). If used, then one such data frame per MPM is required. MPMs to be run without density dependence should be set to NULL.

density_vr

An optional list of data frames of class lefkoDensVR, which provide details for density dependence in vital rate models and have been created with function link[lefko3]{density_vr}(). If used, then one such data frame per MPM is required. MPMs to be run without vital describing density dependence relationships in vital rates should be set to NULL. Can only be used with function-based projections.

err_check

A logical value indicating whether to include an extra list of output objects for error checking. Can also be set to the text value "extreme", in which case all err_check output plus a multiple level list with each MPM used in each time step will be output.

stochastic

A logical value indicating whether the projection will be run as a temporally stochastic projection. Defaults to FALSE.

integeronly

A logical value indicating whether to round the number of individuals projected in each stage at each occasion in each MPM 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.

nreps

The number of replicate projections. Defaults to 1.

times

Number of occasions to iterate per replicate. Defaults to 10000.

prep_mats

An integer value for use when creating function-based MPM projections. If using vrms input instead of mpms input, then this argument determines how many matrices should be used as a limit to develop matrices prior to running the projection. See Notes for further details.

force_fb

A logical value indicating whether to force function-based MPMs to be developed at each time step even if fewer than prep_mats. 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.

Value

A list of class adaptProj, with the following elements:

comm_out

A two-level list with the top level list having number of elements equal to the number of MPMs used as input, and the lower level corresponding to the number of replicates. Each element of the lower level list is a data frame showing the number of individuals in each stage at each time. Rows and columns in the data frames correspond to stages and time steps, respectively.

N_out

A list with the number of elements equal to the number of replicates. Each element within this list is data frame showing the number of individuals of each species or genotype alive at each time. The number of rows are equal to the number of MPMs used, and the columns correspond to the time steps.

stageframe_list

A list in which each element is the stageframe for each MPM used.

hstages_list

A list giving the used hstages data frames, which identify the correct stage pairing for each row / column in each historical MPM utilized.

agestages_list

A list giving the used agestages data frames, which identify the correct age-stage pairing for each row / column in each age-by-stage MPM utilized.

labels

A small data frame giving the the population and patch identities for each MPM entered.

err_check

An optional list composed of an additional six lists, each of which has the number of elements equal to the number of MPMs utilized. List output include allstages_all, which gives the indices of estimatedtransitions in MPMs constructed by function project3() from input vital rate models; allmodels_all, which provides all vital rate models as decomposed and interpreted by function project3(); equivalence_list, which gives the stage equivalence for density calculations across MPMs; density_list, which gives the density inputs utilized; dens_index_list, which provides indices used to identify matrix elements for density dependence; and density_vr_list, which gives the density_vr inputs utilized.

Notes

This function has been optimized in the function-based approach such that if there are relatively few matrices required per MPM to run the projection forward, then these matrices will be made prior to running the projection. This approach saves time, but only if there are relatively few unique matrices required for each MPM. If many or only unique MPMs are required at each time step, then the matrices will be made on the fly during the projection itself. Such a situation will most likely occur if each time step requires a new matrix resulting from a unique individual covariate value, or if the density_vr argument is used. The key argument determining this behavior is prep_mats, which provides the maximum limit for the number of matrices required per MPM in order to create matrices prior to projection.

Examples

library(lefko3)
data(cypdata)

data(cypa_data)

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)

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

cycaraw_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)
  
cyparaw_v1 <- verticalize3(data = cypa_data, noyears = 18, firstyear = 1994,
  individcol = "plant_id", blocksize = 2, sizeacol = "Inf.94",
  sizebcol = "Veg.94", repstracol = "Inf.94", fecacol = "Inf.94",
  stageassign = cypframe_raw, stagesize = "sizeadded", NAas0 = TRUE,
  NRasRep = TRUE)

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)
cyp_supp_list1 <- list(cypsupp2r, cypsupp2r)

cycamatrix2r <- rlefko2(data = cycaraw_v1, stageframe = cypframe_raw, 
  year = "all", patch = "all", stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added"), supplement = cypsupp2r,
  yearcol = "year2", patchcol = "patchid", indivcol = "individ")

cypamatrix2r <- rlefko2(data = cyparaw_v1, stageframe = cypframe_raw, 
  year = "all", stages = c("stage3", "stage2", "stage1"),
  size = c("size3added", "size2added"), supplement = cypsupp2r,
  yearcol = "year2", patchcol = "patchid", indivcol = "individ")

cyp_mpm_list <- list(cycamatrix2r, cypamatrix2r)

cyca2_start <- start_input(cycamatrix2r, stage2 = c("SD", "P1", "P2"),
  value = c(500, 100, 200))
cypa2_start <- start_input(cypamatrix2r, stage2 = c("SD", "P1", "P2"),
  value = c(5000, 1000, 2000))
cyp_start_list <- list(cyca2_start, cypa2_start)

cyp2_dv <- density_input(cypamatrix2r, stage3 = c("SD", "P1"),
  stage2 = c("rep", "rep"), style = c(1, 1), alpha = c(0.5, 1.2),
  beta = c(1.0, 2.0), type = c(2, 1))
cyp_dv_list <- list(cyp2_dv, cyp2_dv)

cyp_comm_proj <- project3(mpms = cyp_mpm_list, starts = cyp_start_list,
  density = cyp_dv_list, times = 10)
  
summary(cyp_comm_proj)


[Package adapt3 version 1.0.1 Index]