disease_simulator
function.This is an internal function that checks inputs to the disease_simulator
function to make sure they are valid, and sets default values for needed
inputs if their values are not supplied. The possible inputs for this
function are the same as the possible inputs to the disease_simulator
function.
check_simulator_inputs(inputs)A list identical to the inputs, except with default values supplied to fill in any crucial missing values, as explained in the documentation above.
Nested list/object with named elements:
random_seedNumber to seed the random number generation for stochasticity.
replicatesNumber of replicate simulation runs (default is 1.)
time_stepsNumber of simulation years. Required input.
seasonsNumber of seasons per year (default is 2.)
populationsNumber of populations. Required input.
coordinatesData frame (or matrix) of X-Y population coordinates.
stagesNumber of life cycle stages. Default: 1.
compartmentsNumber of disease compartments (e.g., 3 for a SIR model). Default: 1.
regionA poems::Region object
defining the study region.
initial_abundanceArray (or matrix) of initial abundances.
There must be one column per population and one row per compartment/stage
combination. By default, this should be in the order compartment by stage,
e.g., 2 stage classes plus a SI model should be ordered as S1, S2, I1, I2.
If a region object is attached, then initial abundance may be provided in
the form of a raster with the same specs as the region raster and one
layer per stage/compartment combination. If there is only one
stage/compartment combination you may provide a vector with length
populations. Required input.
carrying_capacityArray (matrix) of carrying capacity values
at each population cell (populations rows by time_steps
columns when across time). Required input.
breeding_season_lengthArray (matrix) of breeding season
length values in days at each population cell (populations rows by
time_steps columns when across time). Can also be a vector of length
populations if the breeding season length does not change over
time.
season_lengthsVector of season lengths in days. Length must
equal seasons. If neither breeding_season_length nor
season_lengths are provided, season lengths will default to
365/seasons.
correlationList containing either an environmental
correlation matrix (correlation_matrix), a pre-calculated transposed
(Cholesky) decomposition matrix (t_decomposition_matrix), or a compact
transposed (Cholesky) decomposition matrix (t_decomposition_compact_matrix)
and a corresponding map of population indices (t_decomposition_compact_map),
as per poems::SpatialCorrelation class attributes.
mortalityA vector of mortality rates, one for each
combination of stages and compartments. Assumed by default to be daily
mortality rates unless indicated otherwise (see below). If mortality varies
by season, a list of mortality vectors with the same length as seasons
may be provided instead. Required input.
mortality_unitA vector indicating whether mortality rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0. A list of vectors may be provided if this varies by season.
fecundityA vector of fecundity rates, one for each
combination of stages and compartments for which fecundity applies (see
fecundity_mask below). If fecundity varies among seasons, a list of
fecundity vectors with the same length as seasons may be provided.
Required input.
fecundity_unitA vector indicating whether fecundity rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0. A list of vectors may be provided if this varies by season.
fecundity_maskA vector indicating which stages and
compartments reproduce. Must be the same length as
stages * compartments. A list of vectors may be provided if this
varies by season. If no fecundity mask is provided, then it is assumed that
all stages and compartments reproduce.
abundance_thresholdA quasi-extinction threshold at which a population becomes extinct. Default: 0.
demographic_stochasticityBoolean for choosing demographic stochasticity for transition, dispersal, and/or other processes (default is TRUE).
transmissionA vector of transmission rates, one for each
combination of stages and compartment for which transmission applies (see
transmission_mask below). If transmission varies by season, a list of
transmission vectors with the same length as seasons may be provided
instead. Required input.
transmission_unitA vector indicating whether transmission is daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0. A list of vectors may be provided if this varies by season.
transmission_maskA vector indicating which stages and
compartments are subject to transmission (i.e., classes susceptible to
infection.) Must be the same length as compartments. A list of
vectors may be provided if this varies by season. If no transmission mask is
provided, then it is assumed that all stages in the first compartment are
susceptible to infection.
recoveryA vector of recovery rates, one for each
combination of stages and compartment for which recovery applies (see
recovery_mask below.) If recovery varies by season, a list of
recovery vectors the same length as seasons may be provided instead.
recovery_unitA vector indicating whether recovery rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0. A list of vectors may be provided if this varies by season.
recovery_maskA
vector indicating which compartments are subject to recovery (i.e., infected
classes that can recover.) Must be the same length as compartments.
A list of vectors may be provided if this varies by season. If no recovery
mask is provided, then it is assumed that all stages in the second
compartment can recover, if there is a second compartment.
dispersalA list that is either length 1 or the same length as
stages. If it is length 1, the same dispersal will be applied across
all stages. Within each element of the list, there should be either a function,
a matrix of dispersal rates between populations (source columns to target
rows) or a list of data frames of non-zero dispersal rates and indices for
constructing a compact dispersal matrix, and optional changing rates over
time (as per class poems::DispersalGenerator dispersal_data
attribute).
dispersal_source_n_kDispersal proportion (p) density dependence via source population abundance divided by carrying capacity (n/k), where p is reduced via a linear slope (defined by two list items) from n/k <= cutoff (p = 0) to n/k \>= threshold (aliases: dispersal_n_k_cutoff & dispersal_n_k_threshold).
dispersal_target_kDispersal rate (r) density dependence via target population carrying capacity (k), where r is reduced via a linear slope (through the origin) when k <= threshold (alias: dispersal_k_threshold).
dispersal_target_nDispersal rate (r) density dependence via target population abundance (n), where r is reduced via a linear slope (defined by two list items) from n \>= threshold to n <= cutoff (r = 0) or vice versa (aliases: dispersal_n_threshold & dispersal_n_cutoff).
dispersal_target_n_kDispersal rate (r) density dependence via target population abundance divided by carrying capacity (n/k), where r is reduced via a linear slope (defined by two list items) from n/k \>= threshold to n/k <= cutoff (r = 0) or vice versa.
season_functionsA list of population transformation functions
(functions that change abundance across stages and compartments) the same
length as seasons. The function must be in the form
function(params), where params is a list passed to the
function containing:
replicatesNumber of replicate simulation runs (default is 1.)
time_stepsNumber of simulation years. Required input.
seasonsNumber of seasons per year (default is 2.)
populationsNumber of populations. Required input.
stagesNumber of life cycle stages. Default: 1.
compartmentsNumber of disease compartments (e.g., 3 for a SIR model). Default: 1.
breeding_season_lengthArray (matrix) of breeding
season length values in days at each population cell
(populations rows by time_steps columns when across
time).
season_lengthsVector of season lengths in days.
Length must equal seasons.
mortalityA vector of mortality rates, one for each combination of stages and compartments. Assumed by default to be daily mortality rates. Required input.
mortality_unitA vector indicating whether mortality rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0.
fecundityA vector of fecundity rates, one for each
combination of stages and compartments for which fecundity applies
(see fecundity_mask below). Required input.
fecundity_unitA vector indicating whether mortality rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0.
fecundity_maskA vector indicating which stages and
compartments reproduce. Must be the same length as
stages * compartments.
abundance_thresholdA quasi-extinction threshold below which a population becomes extinct. Default: 0.
demographic_stochasticityBoolean for choosing demographic stochasticity for transition, dispersal, and/or other processes (default is TRUE).
transmissionA vector of transmission rates, one for each combination of stages and compartments. Assumed by default to be daily transmission rates. Required input.
transmission_unitA vector indicating whether mortality rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0.
recoveryA vector of recovery rates, one for each
combination of stages and compartment for which recovery applies
(see recovery_mask below.)
recovery_unitA vector indicating whether mortality rates are daily or seasonal. 1 indicates seasonal, 0 indicates daily. Default: all 0.
recovery_maskA vector indicating which compartments
are subject to recovery (i.e., infected classes that can recover.)
Must be the same length as compartments.
rSimulation replicate.
tmSimulation time step.
carrying_capacityArray of carrying capacity values for each population at time step.
segment_abundanceMatrix of abundance for each combination of stage and compartment (rows) and population (columns) at time step.
occupied_indicesArray of indices for populations occupied at time step.
simulatorpoems::SimulatorReference object
with dynamically accessible attached and results
lists.
additional attributesAdditional attributes when the transformation is optionally nested in a list.
and returns a transformed stage abundance matrix.
simulation_orderA list the same length as seasons.
Each element in the list is a vector of named simulation processes in the
desired order. Processes must be one of "transition", "dispersal",
"season_functions", or "results."
dispersal_typeA character vector that may contain "pooled"
(if all individuals disperse the same), "stages", "compartments", or
"segments", if different stages, compartments, or stage-compartment
combinations disperse differently. If "pooled" is chosen,
dispersal must be a list of length 1. If "stages" is chosen, it
must be the same length as stages, if "compartments" is chosen,
it must be the same length as compartments, and if "segments" is
chosen, it must be the same length as stages*compartments. The default
value is "pooled".
results_selectionList of results selection from: "abundance" (default), "ema", "extirpation", "extinction_location", "occupancy"; "summarize" (default) or "replicate".
results_breakdownA string with one of these values: "segments" (default), "compartments", "stages" or "pooled." "segments" returns results for each segment (stage x compartment combination.) "compartments" returns results for each disease compartment. "stages" returns results for each life cycle stage. "pooled" returns results that are not broken down by stage or compartment.
verboseTRUE or FALSE, indicating if the user wants informative messages throughout the simulation process.