Skip to content

SEIRSModel Class

Jump to bottom
Ryan Seamus McGee edited this page Aug 9, 2020 · 2 revisions

Contents:

Initializing the model

All model parameter values, including the normal and (optional) quarantine interaction networks, are set in the call to the SEIRSModel constructor. The basic SEIR parameters beta, sigma, gamma, and initN are the only required arguments. All other arguments represent parameters for optional extended model dynamics; these optional parameters take default values that turn off their corresponding dynamics when not provided in the constructor.

Specifying parameters

Constructor Argument Parameter Description Data Type Default Value
beta rate of transmission float REQUIRED
sigma rate of progression float REQUIRED
gamma rate of recovery float REQUIRED
xi rate of re-susceptibility float 0
mu_I rate of infection-related mortality float 0
mu_0 rate of baseline mortality float 0
nu rate of baseline birth float 0
beta_Q rate of transmission for detected cases float None (set equal to beta)
sigma_Q rate of progression for detected cases float None (set equal to sigma)
gamma_Q rate of recovery for detected cases float None (set equal to gamma)
mu_Q rate of infection-related mortality for detected cases float None (set equal to mu_I)
theta_E rate of testing for exposed individuals float 0
theta_I rate of testing for infectious individuals float 0
psi_E probability of positive tests for exposed individuals float 0
psi_I probability of positive tests for infectious individuals float 0
initN initial total number of individuals int 10
initI initial number of infectious individuals int 10
initE initial number of exposed individuals int 0
initQ_E initial number of detected exposed individuals int 0
initQ_I initial number of detected infectious individuals int 0
initR initial number of recovered individuals int 0
initF initial number of deceased individuals int 0
Basic SEIR
model = SEIRSModel(beta=0.155, sigma=1/5.2, gamma=1/12.39, initN=100000, initI=100)
Basic SEIRS
model = SEIRSModel(beta=0.155, sigma=1/5.2, gamma=1/12.39, xi=0.001, initN=100000, initI=100)
SEIR with testing and different progression rates for detected cases (theta and psi testing params > 0, rate parameters provided for detected states)
model = SEIRSModel(beta=0.155, sigma=1/5.2, gamma=1/12.39, initN=100000, initI=100,
                   beta_Q=0.100, sigma_Q=1/4.0, gamma_Q=1/9.0, theta_E=0.02, theta_I=0.02, psi_E=1.0, psi_I=1.0)

Running the Model

Running a simulation

Once a model is initialized, a simulation can be run with a call to the following function:

model.run(T=300)

The run() function has the following arguments

Argument Description Data Type Default Value
T runtime of simulation numeric REQUIRED
checkpoints dictionary of checkpoint lists (see section below) dictionary None
print_interval (network model only) time interval to print sim status to console numeric 10
verbose if True, print count in each state at print intervals, else just the time bool False

Changing parameters during a simulation

Checkpoints

Model parameters can be easily changed during a simulation run using checkpoints. A dictionary holds a list of checkpoint times (checkpoints['t']) and lists of new values to assign to various model parameters at each checkpoint time.

Example of running a simulation with checkpoints:

checkpoints = {'t':       [20, 100], 
               'G':       [G_distancing, G_normal], 
               'p':       [0.1, 0.5], 
               'theta_E': [0.02, 0.02], 
               'theta_I': [0.02, 0.02], 
               'phi_E':   [0.2, 0.2], 
               'phi_I':   [0.2, 0.2]}

The checkpoints shown here correspond to starting social distancing and testing at time t=20 (the graph G is updated to G_distancing and locality parameter p is decreased to 0.1; testing params theta_E, theta_I, phi, and phi_I are set to non-zero values) and then stopping social distancing at time t=100 (G and p changed back to their "normal" values; testing params remain non-zero).

Any model parameter listed in the model constructor can be updated in this way. Only model parameters that are included in the checkpoints dictionary have their values updated at the checkpoint times, all other parameters keep their pre-existing values.

Use cases of this feature include:

  • Changing parameters during a simulation, such as changing transition rates or testing parameters every day, week, on a specific sequence of dates, etc.
  • Starting and stopping interventions, such as social distancing (changing interaction network), testing and contact tracing (setting relevant parameters to non-zero or zero values), etc.

Consecutive runs: You can also run the same model object multiple times. Each time the run() function of a given model object is called, it starts a simulation from the state it left off in any previous simulations. For example:

model.run(T=100)    # simulate the model for 100 time units
# ... 
# do other things, such as processing simulation data or changing parameters 
# ...
model.run(T=200)    # simulate the model for an additional 200 time units, picking up where the first sim left off

Accessing simulation results

Model parameter values and the variable time series generated by the simulation are stored in the attributes of the SEIRSModel or SEIRSNetworkModel being used and can be accessed directly as follows:

S = model.numS      # time series of S counts
E = model.numE      # time series of E counts
I = model.numI      # time series of I counts
Q_E = model.numQ_E  # time series of Q_E counts
Q_I = model.numQ_I  # time series of Q_I counts
R = model.numR      # time series of R counts
F = model.numF      # time series of F counts

t = model.tseries   # time values corresponding to the above time series

G_normal     = model.G    # interaction network graph
G_quarantine = model.Q    # quarantine interaction network graph

beta = model.beta   # value of beta parameter (or list of beta values for each node if using network model)
# similar for other parameters

Note: convenience methods for plotting these time series are included in the package. See below.

Specifying Interaction Networks

This model includes a model of SEIRS dynamics for populations with a structured interaction network (as opposed to standard deterministic SIR/SEIR/SEIRS models, which assume uniform mixing of the population). When using the network model, a graph specifying the interaction network for the population must be specified, where each node represents an individual in the population and edges connect individuals who have regular interactions.

The interaction network can be specified by a networkx Graph object or a numpy 2d array representing the adjacency matrix, either of which can be defined and generated by any method.

This SEIRS+ model also implements dynamics corresponding to testing individuals for the disease and moving individuals with detected infections into a state where their rate of recovery, mortality, etc may be different. In addition, given that this model considers individuals in an interaction network, a separate graph defining the interactions for individuals with detected cases can be specified (i.e., the "quarantine interaction" network).

Epidemic scenarios of interest often involve interaction networks that change in time. Multiple interaction networks can be defined and used at different times in the model simulation using the checkpoints feature (described in the section below).

Note: Simulation time increases with network size. Small networks simulate quickly, but have more stochastic volatility. Networks with ~10,000 are large enough to produce per-capita population dynamics that are generally consistent with those of larger networks, but small enough to simulate quickly. We recommend using networks with ~10,000 nodes for prototyping parameters and scenarios, which can then be run on larger networks if more precision is required.

Visualization

Visualizing the results

The SEIRSModel and SEIRSNetworkModel classes have a plot() convenience function for plotting simulation results on a matplotlib axis. This function generates a line plot of the frequency of each model state in the population by default, but there are many optional arguments that can be used to customize the plot.

These classes also have convenience functions for generating a full figure out of model simulation results (optionally, arguments can be provided to customize the plots generated by these functions, see below).

  • figure_basic() calls the plot() function with default parameters to generate a line plot of the frequency of each state in the population.
  • figure_infections() calls the plot() function with default parameters to generate a stacked area plot of the frequency of only the infection states (E, I, DE, DI) in the population.

Parameters that can be passed to any of the above functions include:

Argument Description
plot_S 'line', shaded, 'stacked', or False
plot_E 'line', shaded, 'stacked', or False
plot_I 'line', shaded, 'stacked', or False
plot_R 'line', shaded, 'stacked', or False
plot_F 'line', shaded, 'stacked', or False
plot_Q_E 'line', shaded, 'stacked', or False
plot_Q_I 'line', shaded, 'stacked', or False
combine_Q True or False
color_S matplotlib color of line or stacked area
color_E matplotlib color of line or stacked area
color_I matplotlib color of line or stacked area
color_R matplotlib color of line or stacked area
color_F matplotlib color of line or stacked area
color_Q_E matplotlib color of line or stacked area
color_Q_I matplotlib color of line or stacked area
color_reference matplotlib color of line or stacked area
dashed_reference_results seirsplus model object containing results to be plotted as a dashed-line reference curve
dashed_reference_label string for labeling the reference curve in the legend
shaded_reference_results seirsplus model object containing results to be plotted as a dashed-line reference curve
shaded_reference_label string for labeling the reference curve in the legend
vlines list of x positions at which to plot vertical lines
vline_colors list of matplotlib colors corresponding to the vertical lines
vline_styles list of matplotlib linestyle strings corresponding to the vertical lines
vline_labels list of string labels corresponding to the vertical lines
ylim max y-axis value
xlim max x-axis value
legend display legend, True or False
title string plot title
side_title string plot title along y-axis
plot_percentages if True plot percentage of population in each state, else plot absolute counts
figsize tuple specifying figure x and y dimensions
use_seaborn if True import seaborn and use seaborn styles

Extended SEIRS Model

Basic SEIRS Model

Network Generation

Simulation Demos

Clone this wiki locally