f_projection3 {lefko3} | R Documentation |
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: |
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 |
start_age |
The age from which to start the matrix. Defaults to
|
last_age |
The final age to use in the matrix. Defaults to |
fecage_min |
The minimum age at which reproduction is possible. Defaults
to |
fecage_max |
The maximum age at which reproduction is possible. Defaults
to |
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 |
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 |
growthonly |
A logical value indicating whether to produce only the
projected population size at each occasion ( |
repvalue |
A logical value indicating whether to calculate reproductive
value vectors at each time step. Can only be set to |
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 |
substoch |
An integer value indicating whether to force survival-
transition matrices to be substochastic in density dependent and density
independent simulations. Defaults to |
ipm_cdf |
A logical value indicating whether to estimate size
transitions using the cumulative density function in cases with continuous
distributions. Defaults to |
nreps |
The number of replicate projections. Defaults to |
times |
Number of occasions to iterate per replicate. Defaults to
|
repmod |
A scalar multiplier of fecundity. Defaults to |
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
|
theta_tol |
A numeric value used to indicate a maximum value to theta as
used in the negative binomial probability density kernel. Defaults to
|
random_inda |
A logical value denoting whether to treat individual
covariate |
random_indb |
A logical value denoting whether to treat individual
covariate |
random_indc |
A logical value denoting whether to treat individual
covariate |
err_check |
A logical value indicating whether to append extra output
for debugging purposes. Defaults to |
quiet |
A logical value indicating whether warning messages should be
suppressed. Defaults to |
data |
The historical vertical demographic data frame used to estimate
vital rates (class |
stageframe |
An object of class |
supplement |
An optional data frame of class |
repmatrix |
An optional reproduction matrix. This matrix is composed
mostly of |
overwrite |
An optional data frame developed with the
|
modelsuite |
A |
paramnames |
A data frame with three columns, the first describing all
terms used in linear modeling, the second (must be called |
year |
Either a single integer value corresponding to the year to
project, or a vector of |
patch |
A value of |
sp_density |
Either a single numeric value of spatial density to use in
vital rate models in all time steps, or a vector of |
ind_terms |
An optional data frame with 3 columns and |
dev_terms |
An optional data frame with 14 columns and |
surv_model |
A linear model predicting survival probability. This can
be a model of class |
obs_model |
A linear model predicting sprouting or observation
probability. This can be a model of class |
size_model |
A linear model predicting primary size. This can be a model
of class |
sizeb_model |
A linear model predicting secondary size. This can be a
model of class |
sizec_model |
A linear model predicting tertiary size. This can be a
model of class |
repst_model |
A linear model predicting reproduction probability. This
can be a model of class |
fec_model |
A linear model predicting fecundity. This can be a model of
class |
jsurv_model |
A linear model predicting juvenile survival probability.
This can be a model of class |
jobs_model |
A linear model predicting juvenile sprouting or observation
probability. This can be a model of class |
jsize_model |
A linear model predicting juvenile primary size. This
can be a model of class |
jsizeb_model |
A linear model predicting juvenile secondary size. This
can be a model of class |
jsizec_model |
A linear model predicting juvenile tertiary size. This
can be a model of class |
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 |
jmatst_model |
A linear model predicting maturity probability of an
individual that was immature in time t. This can be a model of class
|
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 |
tweights |
An optional numeric vector or matrix denoting the probabilities of choosing each matrix in a stochastic projection. If a matrix is input, 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 a vector is input, then the choice of annual matrix is assumed to be independent of the current matrix. Defaults to equal weighting among matrices. |
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 |
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 |
sparse |
A text string indicating whether to use sparse matrix encoding
( |
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 |
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 |
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 |
pop_size |
A list of matrices showing the total population size in each
occasion per replicate (row within matrix) per pop-patch or population
(list element). Only a single pop-patch or population is allowed in
|
labels |
A data frame showing the order of populations and patches in
item |
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 |
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.
Some issues may arise in first-order Markovian stochastic projections if
the year
argument is used. Use the matrix input in the
tweights
argument to eliminate any years from consideration that are
not needed.
See Also
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)
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)