SPARSEMODr (version 1.2.0)

model_interface: Universal Model Interface to the SPARSE-MOD Models

Description

model_interface determines which SPARSE-MOD model to run based on the arguments and runs the specified model.

Usage

model_interface(
        control,
        arg.list
    )

Value

Two named lists:

1. pops: Integer vectors that provide the number of individuals in each model class at each time step. Different realizations of the model are distinguised by the user-provided values for the random seeds.

2. events: Integer vectors that provide the number of individuals that newly transitioned to specific, key model classes at each time step. Different realizations of the model are distinguised by the user-provided values for the random seeds. For the COVID-19 model, these event vectors are defined as:

   • pos: Number of newly positive individuals. Sum of new asymptomatic and pre-symptomatic individuals.

   • sym: Number of newly symptomatic individuals.

   • total_hosp: Number of newly hospitalized individuals. Sum of new Hospital admits and new Symptomatic-to-ICU1 admits.

   • total_icu: Number of new ICU admits. Sum of new Symptomatic-to-ICU1 admits and new Hospital-to-ICU1 admits.

   • n_death: Number of newly deceased individuals.

   For the SEIR model, these event vectors are defined as:

   • birth: Number of newly susceptible hosts through the process of reproduction.

   • exposed: Number of newly exposed hosts.

   • infectious: Number of newly infectious hosts.

   • recov: Number of newly recovered hosts.

   • death: Number of newly deceased hosts.

Arguments

control

Either a covid19_control or seir_control named list. The control used will determine which model to run.

arg.list

A named list of arguments used in all models including:

• input_dist_mat

• input_census_area

• input_realz_seeds

• input_tw: A time window object (see time_windows)

• trans_type: Transmission type (see details below)

• dd_trans_monod_k: The Monod equation parameter 'k', for when transmission is density-dependent (see details below)

• stoch_sd: The standard deviation of the stochastic transmission rate (see details below)

Author

Joseph Mihaljevic,
Seth Borkovec,

Details

This is the universal interface to all of the SPARSE-MOD models. Currently the models available are the COVID-19 Model, and the SEIR Model.

The SPARSE-MOD COVID-19 Model describes transmission using 11 classes of individuals. Please see the vignettes for a more detailed explanation of the model structure.

The SPARSE-MOD SEIR Model describes transmission using 4 classes of individuals. Please see the vignettes for a more detailed explanation of the model structure.

Transmisison types: The day-specific transmission rate (beta) must be supplied. We allow for two transmission types:

1. Frequency-dependent transmission: In this case the transmission function is: $$beta_scaled = beta / pop_N.$$ This is calculated per sub-population.

2. Density-dependent transmission: In this case, we allow a user-defined Monod equation to scale the beta term by sub-population density, where \(pop_density = pop_N / census_area\) : $$ beta_scaled = (beta * pop_dens / (dd_trans_monod_k + pop_dens)) / pop_N $$

Stochastic transmission: We implement daily stochastic variation in the transmission rate that scales with the number of infectious individuals in the focal population. In other words, as the number of infectious individuals increases, the variation in transmission rate reduces, emphasizing that stochasticity has larger effects in smaller populations (i.e., larger effects when there are few infectious individuals). To implement this stochasticity, we draw a random variate from a normal distribution with a mean of zero and a standard deviation of stoch_sd, and this random variate is termed noise. We calculate the total number of infectious individuals across infectious sub-classes (e.g., Pre-symptomatic, Hospital, etc.), and this variable is termed infect_sum. The functional form of stochasticity is then: $$beta_realized = | beta_scaled * (1 + (noise / sqrt(infect_sum))) |$$

See Movement for details of how movement dynamics are implemented and controlled in the model.

See Also

model_parallel, time_windows, covid19_control, seir_control

Examples

## See vignettes for more detailed work-ups.

##########################################
## See model_parallel()
## for an example to run realizations in parallel

##########################################
# Required for run:
require(lubridate)

## Using supplied example data:

# Read in the example data:
ex_dir <- system.file(
  "extdata", "sparsemodr_example.Rdata", package="SPARSEMODr", mustWork=TRUE)
load(ex_dir)
n_pop <- length(dat_list[["pop_N"]])

# Set up realizations:
realz_seeds <- 1:2
n_realz <- length(realz_seeds)

# Set up time windows (see time_windows for other ways to do this)
input_beta <-           c(   0.3,   0.3,  0.08,  0.08,  0.15)
input_dist_phi <-       c(   200,   200,    20,   150,   150)
input_m <-              c( 0.002, 0.002, 0.002,  0.02,  0.02)
input_imm_frac <-       c(   0.0,   0.0,   0.0,  0.02,  0.02)
# Window intervals
start_dates = c(mdy("1-1-20"),  mdy("2-1-20"),  mdy("2-16-20"), mdy("3-11-20"),  mdy("3-22-20"))
end_dates =   c(mdy("1-31-20"), mdy("2-15-20"), mdy("3-10-20"), mdy("3-21-20"), mdy("5-1-20"))


# User creates the time_windows object here
tw <- time_windows(beta = input_beta,
                   dist_phi = input_dist_phi,
                   m = input_m,
                   imm_frac = input_imm_frac,
                   start_dates = start_dates,
                   end_dates = end_dates)

# Randomly generate initial conditions for
# EXPOSED class:
E_pops <- vector("numeric", length = n_pop)
n_initial_E <- 40
# (more exposed in larger populations)
these_E <- sample.int(n_pop,
                     size = n_initial_E,
                     replace = TRUE,
                     prob = dat_list$pop_N)
for(i in 1:n_initial_E){
  E_pops[these_E[i]] <- E_pops[these_E[i]] + 1
}

# Inputs for the models
N_pops <- as.integer(dat_list[["pop_N"]])
S_pops <- N_pops - E_pops

# User created control list of parameters
covid19_control <- covid19_control(input_N_pops = N_pops,
                                   input_S_pops = S_pops,
                                   input_E_pops = E_pops)

arg.list <- list(
    input_dist_mat =    dat_list$dist_vec,
    input_census_area = dat_list$census_area,
    input_tw =          tw,
    input_realz_seeds = realz_seeds
)

# Using all default parameter values,
# these are the minimum inputs
covid_model_output <-
  model_interface(
    control = covid19_control,
    arg.list
  )