random_seed
Number to seed the random number generation for
stochasticity.
replicates
Number of replicate simulation runs (default is
1.)
time_steps
Number of simulation years. Required input.
seasons
Number of seasons per year (default is 2.)
populations
Number of populations. Required input.
coordinates
Data frame (or matrix) of X-Y population
coordinates.
stages
Number of life cycle stages. Default: 1.
compartments
Number of disease compartments (e.g., 3 for a
SIR model). Default: 1.
region
A poems::Region
object
defining the study region.
initial_abundance
Array (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_capacity
Array (matrix) of carrying capacity values
at each population cell (populations
rows by time_steps
columns when across time). Required input.
breeding_season_length
Array (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_lengths
Vector 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
.
correlation
List 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.
mortality
A 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_unit
A 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.
fecundity
A 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_unit
A 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_mask
A 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_threshold
A quasi-extinction threshold at which a
population becomes extinct. Default: 0.
demographic_stochasticity
Boolean for choosing demographic
stochasticity for transition, dispersal, and/or other processes (default is
TRUE).
transmission
A 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_unit
A 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_mask
A 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.
recovery
A 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_unit
A 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_mask
A
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.
dispersal
A 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_k
Dispersal 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_k
Dispersal 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_n
Dispersal
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_k
Dispersal 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_functions
A 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:
replicates
Number of replicate simulation runs
(default is 1.)
time_steps
Number of simulation years. Required
input.
seasons
Number of seasons per year (default is 2.)
populations
Number of populations. Required input.
stages
Number of life cycle stages. Default: 1.
compartments
Number of disease compartments (e.g., 3
for a SIR model). Default: 1.
breeding_season_length
Array (matrix) of breeding
season length values in days at each population cell
(populations
rows by time_steps
columns when across
time).
season_lengths
Vector of season lengths in days.
Length must equal seasons
.
mortality
A vector of mortality rates, one for each
combination of stages and compartments. Assumed by default to be
daily mortality rates. Required input.
mortality_unit
A vector indicating whether mortality
rates are daily or seasonal. 1 indicates seasonal, 0 indicates
daily. Default: all 0.
fecundity
A vector of fecundity rates, one for each
combination of stages and compartments for which fecundity applies
(see fecundity_mask
below). Required input.
fecundity_unit
A vector indicating whether mortality
rates are daily or seasonal. 1 indicates seasonal, 0 indicates
daily. Default: all 0.
fecundity_mask
A vector indicating which stages and
compartments reproduce. Must be the same length as
stages * compartments
.
abundance_threshold
A quasi-extinction threshold below
which a population becomes extinct. Default: 0.
demographic_stochasticity
Boolean for choosing
demographic stochasticity for transition, dispersal, and/or other
processes (default is TRUE).
transmission
A vector of transmission rates, one for
each combination of stages and compartments. Assumed by default to
be daily transmission rates. Required input.
transmission_unit
A vector indicating whether
mortality rates are daily or seasonal. 1 indicates seasonal, 0
indicates daily. Default: all 0.
recovery
A vector of recovery rates, one for each
combination of stages and compartment for which recovery applies
(see recovery_mask
below.)
recovery_unit
A vector indicating whether mortality
rates are daily or seasonal. 1 indicates seasonal, 0 indicates
daily. Default: all 0.
recovery_mask
A vector indicating which compartments
are subject to recovery (i.e., infected classes that can recover.)
Must be the same length as compartments
.
r
Simulation replicate.
tm
Simulation time step.
carrying_capacity
Array of carrying capacity values
for each population at time step.
segment_abundance
Matrix of abundance for each
combination of stage and compartment (rows) and population (columns)
at time step.
occupied_indices
Array of indices for populations
occupied at time step.
simulator
poems::SimulatorReference
object
with dynamically accessible attached and results
lists.
additional attributes
Additional attributes when the
transformation is optionally nested in a list.
and returns a transformed stage abundance matrix.
simulation_order
A 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_type
A 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_selection
List of results selection from: "abundance"
(default), "ema", "extirpation", "extinction_location",
"occupancy"; "summarize" (default) or "replicate".
results_breakdown
A 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.
verbose
TRUE or FALSE, indicating if the user wants informative
messages throughout the simulation process.