disease_simulator: Stage-based seasonal spatially explicit population-level...

In epizootic: Spatially Explicit Population Models of Disease Transmission in Wildlife

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:

1. Stage transition (stochastic) calculations

2. Population growth/decline calculations

3. Disease outbreak according to a compartmental model

4. Dispersal calculations (default or user-defined)

5. 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)

epizootic documentation built on Oct. 2, 2024, 5:07 p.m.