,
National Science Foundation Biology Integration Institute 2213854 [fnd]| Title: | Spatially Explicit Population Models of Disease Transmission in Wildlife |
|---|---|
| Description: | This extension of the pattern-oriented modeling framework of the 'poems' package provides a collection of modules and functions customized for modeling disease transmission on a population scale in a spatiotemporally explicit manner. This includes seasonal time steps, dispersal functions that track disease state of dispersers, results objects that store disease states, and a population simulator that includes disease dynamics. |
| Authors: | July Pilowsky [aut, cre] ,
National Science Foundation Biology Integration Institute 2213854 [fnd] |
| Maintainer: | July Pilowsky <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 1.0.0 |
| Built: | 2024-11-02 04:59:36 UTC |
| Source: | https://github.com/viralemergence/epizootic |
This function is an internal one that does the aspatial simulations within one population for one timestep, for any given season.
aspatial_siri( initial_pop, season_length, mortality, transmission, recovery, fecundity, abundance_threshold, carrying_capacity, season )aspatial_siri( initial_pop, season_length, mortality, transmission, recovery, fecundity, abundance_threshold, carrying_capacity, season )
initial_pop |
A vector of length 8 showing the initial abundance for each combination of stage and compartment. |
season_length |
The length of the season in days. |
mortality |
A vector of length 8 with the mortality rates for each stage and compartment in the season in question. |
transmission |
A vector of length 8 with the transmission rates for each stage in the season in question. |
recovery |
A vector of length 8 with the recovery rates for each infected stage in the season in question. |
fecundity |
A vector of length 8 with the fecundity for each reproductive segment. |
abundance_threshold |
A quasi-extinction threshold below which a population becomes extinct. |
carrying_capacity |
A single numeric that indicates the carrying capacity of the population in this season. |
season |
Either "breeding" or "non-breeding." |
A vector of length 8 showing the abundance for each combination of stage and compartment at the end of the season.
aspatial_siri( initial_pop = c(50000, 50000, 0, 1, 0, 0, 0, 0), season_length = 100, mortality = c(0.004, 0, 0.00505, 0.00105, 0.004, 0, 0.0045, 5e-04), fecundity = c(0, 15/182, 0, 15/182, 0, 15/182, 0, 15/182), transmission = c(0.00002, 0.00001, 0, 0, 7.84e-06, 3.92e-06, 0, 0), recovery = c(0, 0, 0.05714286, 0.05714286, 0, 0, 0.1, 0.1), carrying_capacity = 150000, abundance_threshold = 10, season = "breeding" )aspatial_siri( initial_pop = c(50000, 50000, 0, 1, 0, 0, 0, 0), season_length = 100, mortality = c(0.004, 0, 0.00505, 0.00105, 0.004, 0, 0.0045, 5e-04), fecundity = c(0, 15/182, 0, 15/182, 0, 15/182, 0, 15/182), transmission = c(0.00002, 0.00001, 0, 0, 7.84e-06, 3.92e-06, 0, 0), recovery = c(0, 0, 0.05714286, 0.05714286, 0, 0, 0.1, 0.1), carrying_capacity = 150000, abundance_threshold = 10, season = "breeding" )
This is a RasterBrick object containing data on the breeding season
length in days of the house finch in North America from 1994 to 2016. I
created this dataset using a machine learning algorithm on season length data
from the eastern bluebird, which is noted to have a very similar breeding
season to the house finch. The raster has the same resolution as the
finch_region.
bsl_rasterbsl_raster
A RasterBrick with 17066 cells and 23 layers.
siri_model_summer
and siri_model_winter functions.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_aspatial_siri_inputs(inputs)check_aspatial_siri_inputs(inputs)
inputs |
A nested list with named elements:
|
A list identical to the inputs (if there are no errors.)
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)check_simulator_inputs(inputs)
inputs |
Nested list/object with named elements:
|
A list identical to the inputs, except with default values supplied to fill in any crucial missing values, as explained in the documentation above.
Modular functions for the disease simulator for performing dispersal of segment (stage by compartment) abundance at a specified time step via dispersal rates provided. Dispersal can be handled identically for all stages and compartments, or can be handled differently by stage, compartment, or both.
disease_dispersal( replicates, time_steps, populations, demographic_stochasticity, dispersal, dispersal_type, dispersal_source_n_k = NULL, dispersal_target_k = NULL, dispersal_target_n = NULL, dispersal_target_n_k = NULL, stages = NULL, compartments = NULL, simulator )disease_dispersal( replicates, time_steps, populations, demographic_stochasticity, dispersal, dispersal_type, dispersal_source_n_k = NULL, dispersal_target_k = NULL, dispersal_target_n = NULL, dispersal_target_n_k = NULL, stages = NULL, compartments = NULL, simulator )
replicates |
Number of replicate simulation runs. |
time_steps |
Number of simulation time steps. |
populations |
Number of populations. |
demographic_stochasticity |
Boolean for optionally choosing demographic stochasticity for the transformation. |
dispersal |
Must be a list. Either a list of matrices 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 optionally a list of lists of data frames showing
changing rates over time (as per class
returns the post-dispersal abundance matrix |
dispersal_type |
Must be "pooled", "stages", "compartments", or "segments". This indicates whether dispersal should be handled differently by stage and/or compartment. |
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 or vice versa. |
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. |
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 visa-versa. |
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. |
stages |
Number of life cycle stages. |
compartments |
Number of disease compartments. |
simulator |
|
Dispersal function: function(r, tm, carrying_capacity,
segment_abundance), where:
rSimulation replicate.
tmSimulation time step.
carrying_capacityArray of carrying capacity values for each population at time step.
segment_abundanceMatrix of abundance for each stage by compartment (rows) and population (columns) at time step.
returnsNew stage abundance matrix with dispersal applied.
Modular functions for the disease simulator for initializing, calculating and collecting simulator results.
disease_results( replicates, time_steps, seasons, stages, compartments, coordinates, initial_abundance, results_selection = NULL, results_breakdown = NULL )disease_results( replicates, time_steps, seasons, stages, compartments, coordinates, initial_abundance, results_selection = NULL, results_breakdown = NULL )
replicates |
Number of replicate simulation runs. |
time_steps |
Number of simulation time steps. |
seasons |
Number of seasons per time step. |
stages |
Number of life cycle stages. |
compartments |
Number of disease compartments. |
coordinates |
Data frame (or matrix) of X-Y population coordinates. |
initial_abundance |
Matrix of initial abundances at each combination of stage and compartment (in rows) for each population (in columns). |
results_selection |
List of results selection from: "abundance" (default), "ema", "extirpation", "extinction_location", "harvested", "occupancy"; "summarize" (default) or "replicate". "summarize" calculates mean, sd, min and max across replicates. "replicate" returns results separately for each 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. |
List of result functions:
initialize_attributes = function())Constructs and returns an initialized nested list for the selected result attributes.
initialize_replicate = function(results)Initializes and returns nested result attributes at the start of each replicate.
calculate_at_season = function(r, tm, season,
segment_abundance, harvested, results)Appends and calculates (non-NULL) results and returns nested result attributes at the end of each season within time step (tm) within replicate (r).
calculate_at_timestep = function(r, tm, segment_abundance,
harvested, results)Appends and calculates (non-NULL) results and returns nested result attributes at the end of each time step (tm) within replicate (r).
finalize_attributes = function(results)Finalizes result calculations at the end of the simulation.
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.
disease_simulator(inputs)disease_simulator(inputs)
inputs |
Nested list/object with named elements:
|
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:
abundanceMatrix or 3D array of simulation abundance: populations rows by time_steps columns (by replicates deep).
abundance_stagesList 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$abundanceArray or matrix of total abundance across populations: time_steps (rows by replicates columns).
all$abundance_stagesList of arrays or matrices of total abundance across populations for unique stage-compartment combinations when present: each time_steps (rows by replicates columns).
all$emaArray of expected minimum abundance at each time step (averaged across replicates).
extirpationArray or matrix of extirpation times: populations (rows by replicates columns).
all$extirpationArray of extirpation time across populations for each replicate.
all$extinction_locationThe weighted centroid of cells occupied in the time-step prior to the extirpation of all populations (if it occurred) for each replicate.
all$occupancyArray or matrix of the number of populations occupied at each time-step: time_steps (rows by replicates columns).
additional resultsAdditional results may be attached via
user-defined functions (using params$simulator$results).
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)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)
Modular functions for the disease simulator for performing a transformation of a population across stages and disease compartments (and optionally carrying capacity) at a specified time step via a user-defined function.
disease_transformation(params)disease_transformation(params)
params |
A list of parameters, which must contain all of the below,
except
|
Abundance (and capacity) transformation function:
function(r, tm, carrying_capacity, segment_abundance,
occupied_indices), where:
rSimulation replicate.
tmSimulation time step.
carrying_capacityArray of carrying capacity values for each population at time step.
segment_abundanceMatrix of abundance for each stage-compartment combo (rows) and population (columns) at time step.
occupied_indicesArray of indices for populations occupied at time step.
returnsList with transformed stage abundance matrix (and optionally carrying capacity).
Modular functions for the disease simulator to transition populations between stages and within disease compartments.
disease_transitions(stages, compartments)disease_transitions(stages, compartments)
stages |
Number of life cycle stages. |
compartments |
Number of disease compartments. |
Transition calculation function that takes as input:
segment_abundanceMatrix of (current) abundance for each stage-compartment combo (rows) and population (columns) at time step.
occupied_indicesArray of indices for populations occupied at (current) time step.
A R6::R6Class class representing fixed settings
for a spatially-explicit demographic-based SIRI model of disease dynamics. It
extends the poems::SimulationModel class with parameters for the
disease_simulator function. It inherits functionality for
creating a nested model, whereby a nested template model with fixed
parameters is maintained when a model is cloned for various sampled
parameters. Also provided are extensions to the methods for checking the
consistency and completeness of model parameters.
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::SimulationModel -> DiseaseModel
attachedA list of dynamically attached attributes (name-value pairs).
simulation_functionName (character string) or source path of the default simulation function, which takes a model as an input and returns the simulation results.
model_attributesA vector of model attribute names.
regionA poems::Region (or inherited class) object specifying
the study region.
coordinatesData frame (or matrix) of X-Y population (WGS84) coordinates in longitude (degrees West) and latitude (degrees North) (get and set), or distance-based coordinates dynamically returned by region raster (get only).
random_seedNumber to seed the random number generation for stochasticity.
replicatesNumber of replicate simulation runs.
time_stepsNumber of simulation time steps.
years_per_stepNumber of years per time step.
populationsNumber of population cells.
initial_abundanceArray (matrix) or raster (stack) of initial abundance values at each population cell (for each age/stage).
demographic_stochasticityBoolean for choosing demographic stochasticity for transition, dispersal, harvest and/or other processes.
standard_deviationStandard deviation matrix (or single value) for applying environmental stochasticity to transition rates.
correlationSimulator-dependent attribute or list of attributes
for describing/parameterizing the correlation strategy utilized when
applying environmental stochasticity and/or other processes (see
poems::population_simulator).
stagesNumber of life cycle stages (default 1).
compartmentsNumber of disease compartments (default 1).
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.
carrying_capacityArray (matrix), or raster (stack) of carrying capacity values at each population cell (across time).
density_dependenceSimulator-dependent function, attribute or list
of attributes for describing/parameterizing the density dependence
strategy utilized (see poems::population_simulator).
growth_rate_maxMaximum growth rate (utilized by density dependence processes).
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.
density_stagesArray of booleans or numeric (0-1) for each stage to indicate (the degree to) which stages are affected by density (default is 1 for all stages).
translocationSimulator-dependent function, attribute or list of
attributes for describing/parameterizing translocation (management)
strategies utilized (see poems::population_simulator).
harvestSimulator-dependent function, attribute or list of
attributes for describing/parameterizing a harvest (organism
removal/hunting) strategy (see poems::population_simulator).
mortalitySimulator-dependent function, attribute or list of
attributes to describe/parameterize a spatio-temporal mortality
strategy (see poems::population_simulator).
dispersalSimulator-dependent function, attribute or list of
attributes for describing/parameterizing the dispersal (migration)
strategy utilized (see disease_simulator).
dispersal_stagesArray of relative dispersal (0-1) for each stage to indicate the degree to which each stage participates in dispersal (default is 1 for all stages).
dispersal_source_n_kSimulator-dependent attribute for
describing/parameterizing dispersal dependent on source population
abundance divided by carrying capacity (see
disease_simulator).
dispersal_target_kSimulator-dependent attribute for
describing/parameterizing dispersal dependent on target population
carrying capacity (see disease_simulator).
dispersal_target_nSimulator-dependent attribute (default is list
with threshold and cutoff) of attributes for
describing/parameterizing dispersal dependent on target population
abundance (see disease_simulator).
dispersal_target_n_kSimulator-dependent attribute (default is
list with threshold and cutoff) of attributes for
describing/parameterizing dispersal dependent on target population
abundance/capacity (see poems::population_simulator).
abundance_thresholdAbundance threshold (that needs to be exceeded) for each population to persist.
seasonsNumber of seasons in a year (default 1.) The first one is always treated as the breeding season.
simulation_orderA vector of simulation process names in configured order of execution.
results_selectionList of attributes to be included in the returned results of each simulation run, selected from: "abundance", "ema", "extirpation", "extinction_location", "harvested", "occupancy"; "summarize" or "replicate".
attribute_aliasesA list of alternative alias names for model
attributes (form: alias = "attribute") to be used with the set
and get attributes methods.
template_modelNested template model for fixed (non-sampled) attributes for shallow cloning.
sample_attributesVector of sample attribute names (only).
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA vector of warning messages encountered when setting model attributes.
poems::GenericModel$get_attribute()poems::GenericModel$get_attribute_aliases()poems::SimulationModel$get_attribute_names()poems::SimulationModel$get_attributes()poems::SimulationModel$incomplete_attributes()poems::SimulationModel$inconsistent_attributes()poems::SimulationModel$is_complete()poems::SimulationModel$is_consistent()poems::SimulationModel$list_completeness()poems::SimulationModel$new_clone()poems::SimulationModel$set_attributes()new()
Initialization method sets default aliases and given attributes individually and/or from a list.
DiseaseModel$new(attribute_aliases = NULL, ...)
attribute_aliasesA list of alternative alias names for model
attributes (form: alias = "attribute") to be used with the set and
get attributes methods.
...Parameters passed via a params list or individually.
set_sample_attributes()
Sets the names (only - when params is a vector) and values (when params is a list and/or when name-value pairs are provided) of the sample attributes for the model.
DiseaseModel$set_sample_attributes(params = list(), ...)
paramsList of parameters/attributes (names and values) or array of names only.
...Parameters/attributes passed individually.
list_consistency()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent.
DiseaseModel$list_consistency(params = NULL)
paramsOptional array of parameter/attribute names.
List of booleans (or NAs) to indicate consistency of selected/all attributes.
clone()
The objects of this class are cloneable with this method.
DiseaseModel$clone(deep = FALSE)
deepWhether to make a deep clone.
This is a raster that defines the spatial extent and resolution of the house finch conjunctivitis example in the vignette. It encompasses terrestrial North America from southern Mexico to southern Canada. It has a resolution of 46.375 by 46.375 kilometers, adding up to 6,355 possible populations of house finches. The projected coordinate system for the study region is Albers equal-area conic, with a reference longitude of 94.5 W and standard parallels at 21.5 N and 47.5 N.
finch_regionfinch_region
A raster object with 1 layer and 17066 cells defining the spatial scope of a simulation.
This is a RasterStack containing data on habitat suitability for the house finch in North America from 1994 to 2016. This habitat suitability stack was generated using a species distribution model. The predictors for the SDM were the 12 bioclimatic variables, plus an urbanization index (proportion of each grid cell with urban land use.) The occurrences for the SDM came from quality-checked GBIF records.
habitat_suitabilityhabitat_suitability
A RasterStack with 17066 cells and 23 layers.
The raster has the same resolution and projection as the finch_region. Habitat suitability ranges from 0 to 1, with 1 being the most suitable.
This numeric matrix contains initial abundances of house finches in 1994 for
the house finch conjunctivitis vignette. These abundances were themselves
simulated using epizootic and do not represent empirical estimates of house
finch abundance in 1994. The matrix has 6,355 columns, one for each
population in the finch_region, and 8 rows, one for each combination of
life cycle stage and disease compartment (row 1: susceptible juveniles, row
2: susceptible adults, row 3: juveniles infected for the first time, row 4:
adults infected for the first time, row 5: recovered juveniles, row 6:
recovered adults, row 7: re-infected juveniles, row 8: re-infected adults.)
This initial abundance matrix has only zeroes in rows 3-8 because the disease
has not yet broken out at the start of the simulation.
initial_abundanceinitial_abundance
A numeric matrix with 8 rows and 6355 columns.
Simulate a Mycoplasma gallisepticum outbreak during the breeding season day-by-day in a population of house finches (Haemorhous mexicanus). Uses a SIRI model (Susceptible-Infected 1- Recovered-Infected 2+) and includes demographic stochasticity in fecundity, mortality, and infection.
siri_model_summer(inputs)siri_model_summer(inputs)
inputs |
A nested list with named elements:
|
The function can also handle the case in which there are no infected individuals. The principal difference between this function and the one for simulating an outbreak in the non-breeding season is that this one includes fecundity.
An abundance matrix with populations columns and
stages*compartments rows, updated from the segment_abundance input in
inputs according to demography and disease dynamics.
Simulate a Mycoplasma gallisepticum outbreak during the non-breeding season day-by-day in a population of house finches (Haemorhous mexicanus). Uses a SIRI model (Susceptible-Infected 1- Recovered-Infected 2+) and includes demographic stochasticity in fecundity, mortality, and infection.
siri_model_winter(inputs)siri_model_winter(inputs)
inputs |
A nested list with named elements:
|
The function can also handle the case in which there are no infected individuals. The principal difference between this function and the one for simulating an outbreak in the breeding season is that this one does not include fecundity.
An abundance matrix with populations columns and
stages*compartments rows, updated from the segment_abundance input in
inputs according to demography and disease dynamics.