disease_simulator {epizootic} | R Documentation |
Stage-based seasonal spatially explicit population-level disease model.
Description
Simulates a stage-based demographic population model and returns simulation
results across multiple replicate runs. Processes run at each simulation
time-step include:
Stage transition (stochastic) calculations
Population growth/decline calculations
Disease outbreak according to a compartmental model
Dispersal calculations (default or user-defined)
Results collection
Note that the breeding season is
always treated as the first season.
Usage
disease_simulator(inputs)
Arguments
inputs |
Nested list/object with named elements:
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."
"season_functions" will be matched to the appropriate season (i.e., if
"season_functions" appears in element 1 of the list, season_functions[[1]]
will be called.) If the simulation processes are the same across seasons,
then a single character vector may be provided. Required input.
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.
|
Value
Selected simulation results as a nested list summarized (mean, sd,
min, max) across multiple replicates (default), or 2-3D arrays including
results for each replicate:
abundance
Matrix or 3D array of simulation abundance:
populations rows by time_steps columns (by replicates
deep).
abundance_stages
List of matrices or 3D arrays of simulation
abundance for unique stage-compartment combinations when present: each
populations rows by time_steps columns (by replicates
deep).
all$abundance
Array or matrix of total abundance across
populations: time_steps (rows by replicates columns).
all$abundance_stages
List of arrays or matrices of total
abundance across populations for unique stage-compartment combinations when
present: each time_steps (rows by replicates columns).
all$ema
Array of expected minimum abundance at each time step
(averaged across replicates).
extirpation
Array or matrix of extirpation times:
populations (rows by replicates columns).
all$extirpation
Array of extirpation time across populations
for each replicate.
all$extinction_location
The weighted centroid of cells
occupied in the time-step prior to the extirpation of all populations
(if it occurred) for each replicate.
all$occupancy
Array or matrix of the number of populations
occupied at each time-step: time_steps (rows by replicates
columns).
additional results
Additional results may be attached via
user-defined functions (using params$simulator$results
).
Examples
inputs <- list(
time_steps = 5,
seasons = 2,
populations = 25,
stages = 2,
compartments = 4,
coordinates = data.frame(x = rep(seq(177.01, 177.05, 0.01), 5),
y = rep(seq(-18.01, -18.05, -0.01), each = 5)),
initial_abundance = c(c(5000, 5000, 0, 1, 0, 0, 0, 0),
rep(c(5000, 5000, 0, 0, 0, 0, 0, 0), 24)) |>
matrix(nrow = 8),
carrying_capacity = matrix(100000, nrow = 25, ncol = 5),
breeding_season_length = rep(100, 25),
mortality = c(0.4, 0, 0.505, 0.105, 0.4, 0, 0.45, 0.05),
mortality_unit = 1,
fecundity = 15,
fecundity_unit = 1,
fecundity_mask = c(0, 1, 0, 1, 0, 1, 0, 1),
transmission = c(0.00002, 0.00001, 7.84e-06, 3.92e-06),
transmission_unit = 0,
transmission_mask = c(1, 1, 0, 0, 1, 1, 0, 0),
recovery = c(0.05714286, 0.05714286, 0.1, 0.1),
recovery_unit = rep(0, 8),
recovery_mask = c(0, 0, 1, 1, 0, 0, 1, 1),
season_functions = list(siri_model_summer, siri_model_winter),
simulation_order = c("transition", "season_functions", "results")
)
disease_simulator(inputs)
[Package
epizootic version 1.0.0
Index]