density_vr: Set Density Dependence Relationships in Vital Rates

Description

Function density_vr() provides all necessary data to incorporate density dependence into the vital rate functions used to create matrices in function-based projections using function f_projection3(). Four forms of density dependence are allowed, including the Ricker function, the Beverton-Holt function, the Usher function, and the logistic function. In each case, density must have an effect with at least a one time-step delay (see Notes).

Usage

density_vr(
  density_yn = c(FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,
    FALSE, FALSE, FALSE, FALSE),
  style = c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0),
  time_delay = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
  alpha = c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0),
  beta = c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
)

Value

A data frame of class lefkoDensVR with 14 rows, one for each vital rate in the order of: survival probability, observation probability, primary size transition, secondary size transition, tertiary size transition, reproductive status probability, fecundity rate, juvenile survival probability, juvenile observation probability, juvenile primary size transition, juvenile secondary size transition, juvenile tertiary size transition, juvenile reproductive status probability, and juvenile maturity status probability. This object can be used as input in function f_projection3().

Variables in this object include the following:

vital_rate: The vital rate to be modified.
density_yn: Logical value indicating whether vital rate will be subject to density dependence.
style: Style of density dependence, coded as 1, 2, 3, 4, or 0 for the Ricker, Beverton-Holt, Usher, or logistic function, or no density dependence, respectively.
time_delay: The time delay on density dependence, in time steps.
alpha: The value of alpha in the Ricker, Beverton-Holt, or Usher function, or the value of carrying capacity, K, in the logistic function.
beta: The value of beta in the Ricker, Beverton-Holt, or Usher function.

Arguments

density_yn: A 14 element logical vector denoting whether each vital rate is subject to density dependence. The order of vital rates is: survival probability, observation probability, primary size transition, secondary size transition, tertiary size transition, reproductive status probability, fecundity rate, juvenile survival probability, juvenile observation probability, juvenile primary size transition, juvenile secondary size transition, juvenile tertiary size transition, juvenile reproductive status probability, and juvenile maturity status probability. Defaults to a vector of 14 FALSE values.
style: A 14 element vector coding for the style of density dependence on each vital rate. Options include 0: no density dependence, 1, ricker, ric, or r for the Ricker function; 2, beverton, bev, and b for the Beverton-Holt function; 3, usher, ush, and u for the Usher function; and 4, logistic, log, and l for the logistic function. Defaults to 14 values of 0.
time_delay: A 14 element vector indicating the number of occasions back on which density dependence operates. Defaults to 14 values of 1, and may not include any number less than 1.
alpha: A 14 element vector indicating the numeric values to use as the alpha term in the two parameter Ricker, Beverton-Holt, or Usher function, or the value of the carrying capacity K to use in the logistic equation (see Notes for more on this term). Defaults to 14 values of 0.
beta: A 14 element vector indicating the numeric values to use as the beta term in the two parameter Ricker, Beverton-Holt, or Usher function. Used to indicate whether to use K as a hard limit in the logistic equation (see Notes below). Defaults to 14 values of 0.

Notes

This function provides inputs when density dependence is operationalized directly on vital rates. It can be used only in function f_projection3(). Users wishing to modify matrix elements directly by density dependence functions for use in function-based or raw projections with functions projection3() and f_projection3() should use function density_input() to provide the correct inputs.

The parameters alpha and beta are applied according to the two-parameter Ricker function, the two-parameter Beverton-Holt function, the two-parameter Usher function, or the one-parameter logistic function. Although the default is that a 1 time step delay is assumed, greater time delays can be set through the time_delay option.

When using the logistic function, it is possible that the time delay used in density dependent simulations will cause matrix elements to become negative. To prevent this behavior, set the associated beta term to 1.0. Doing so will set K as the hard limit in the logistic equation, essentially setting a minimum limit at 0 for all matrix elements modified.

Examples

Run this code

# \donttest{
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)

lathvertln_adults <- subset(lathvertln, stage2index > 2)
surv_model <- glm(alive3 ~ sizea2 + sizea1 + as.factor(patchid) +
  as.factor(year2), data = lathvertln_adults, family = "binomial")

obs_data <- subset(lathvertln_adults, alive3 == 1)
obs_model <- glm(obsstatus3 ~ as.factor(patchid), data = obs_data,
  family = "binomial")

size_data <- subset(obs_data, obsstatus3 == 1)
siz_model <- lm(sizea3 ~ sizea2 + sizea1 + repstatus1 + as.factor(patchid) +
  as.factor(year2), data = size_data)

reps_model <- glm(repstatus3 ~ sizea2 + sizea1 + as.factor(patchid) +
  as.factor(year2), data = size_data, family = "binomial")

fec_data <- subset(lathvertln_adults, repstatus2 == 1)
fec_model <- glm(feca2 ~ sizea2 + sizea1 + repstatus1 + as.factor(patchid),
  data = fec_data, family = "poisson")

lathvertln_juvs <- subset(lathvertln, stage2index < 3)
jsurv_model <- glm(alive3 ~ as.factor(patchid), data = lathvertln_juvs,
  family = "binomial")

jobs_data <- subset(lathvertln_juvs, alive3 == 1)
jobs_model <- glm(obsstatus3 ~ 1, family = "binomial", data = jobs_data)

jsize_data <- subset(jobs_data, obsstatus3 == 1)
jsiz_model <- lm(sizea3 ~ as.factor(year2), data = jsize_data)

jrepst_model <- 0
jmatst_model <- 1

mod_params <- create_pm(name_terms = TRUE)
mod_params$modelparams[3] <- "patchid"
mod_params$modelparams[4] <- "alive3"
mod_params$modelparams[5] <- "obsstatus3"
mod_params$modelparams[6] <- "sizea3"
mod_params$modelparams[9] <- "repstatus3"
mod_params$modelparams[11] <- "feca2"
mod_params$modelparams[12] <- "sizea2"
mod_params$modelparams[13] <- "sizea1"
mod_params$modelparams[18] <- "repstatus2"
mod_params$modelparams[19] <- "repstatus1"

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", data = lathvertln,
  stageframe = lathframeln, supplement = lathsupp3, paramnames = mod_params,
  surv_model = surv_model, obs_model = obs_model, size_model = siz_model,
  repst_model = reps_model, fec_model = fec_model, jsurv_model = jsurv_model,
  jobs_model = jobs_model, jsize_model = jsiz_model,
  jrepst_model = jrepst_model, jmatst_model = jmatst_model, reduce = FALSE)

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

dyn7 <- c(TRUE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,
  FALSE, FALSE, FALSE, FALSE, FALSE)
dst7 <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
dal7 <- c(0.5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
dbe7 <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)

e3d_vr <- density_vr(density_yn = dyn7, style = dst7, alpha = dal7,
  beta = dbe7)

trial7_dvr_1 <- f_projection3(format = 1, data = lathvertln, supplement = lathsupp3,
  paramnames = mod_params, stageframe = lathframeln, nreps = 2,
  surv_model = surv_model, obs_model = obs_model, size_model = siz_model,
  repst_model = reps_model, fec_model = fec_model, jsurv_model = jsurv_model,
  jobs_model = jobs_model, jsize_model = jsiz_model,
  jrepst_model = jrepst_model, jmatst_model = jmatst_model,
  times = 100, stochastic = TRUE, standardize = FALSE, growthonly = TRUE,
  integeronly = FALSE, substoch = 0, sp_density = 0, start_frame = e3m_sv,
  density_vr = e3d_vr)
# }