check_simulator_inputs: Helper function to check the validity of inputs to the...

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

Helper function to check the validity of inputs to the disease_simulator function.

Description

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.

Usage

check_simulator_inputs(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." 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

A list identical to the inputs, except with default values supplied to fill in any crucial missing values, as explained in the documentation above.

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