SEIR

Build SEIR PackageRun Testshttps://img.shields.io/pypi/v/SEIR.svg Documentation Status Dependabot Enabled

SEIR modelling of covid19

Compartmentalized SEIR

Python package for modeling epidemics using the SEIR model.

Installation

The package is available in the Python Package Index, and can be installed using pip

pip install seir

An up-to-date version can be found in the master branch of the repository at Github, and can be installed with pip like

pip install git+https://github.com/covid19-bh-biostats/seir

Command line simulation tool

Quickstart

Run the following command for an overview of all commands

SEIR --help

Run the following command from the root of this repository for a full demonstration of SEIR’s features

SEIR -cf example_configs/finland_with_restrictions -cm contacts_matrices/finland --visualize-compartments

Config-files

The SEIR package includes a command line interface for the simulation of a simple compartmentalized SEIR model. Basic use looks like the following

$ SEIR --config_file config

Here config is a configuration file containing information on the epidemic and the population. Examples of configuration files can be found in the example_configs/ directory of the Github repository.

The configuration file should contain three sections, [simulation], [model], and [initial state]. Example files are provided in the example_configs/ directory at the root of the repository.

[simulation]

The [simulation] section defines parameters relating to the numerical simulation of the SEIR ordinary differential equation. Supported parameters are

[simulation]
max_simulation_time = 300
method = DOP853
max_step = 0.5

Here the only required parameter is max_simulation_time, i.e., the number of simulated days.

The parameter method can be used to change the numerical integration routine. For supported values, please check the documentation of scipy.integrate.solve_ivp.

max_step defines the maximum time-step used in the integration.

[model] (no compartmentalization)

The [model] section defines the parameters of the disease model. In its simplest form, where you wish to model the entire population and do not wish to compartmentalize it, the [model] section looks like

[model]
population = 5e6
incubation_period = 3
infectious_period = 7
initial_R0 = 2.5
hospitalization_probability = 0.1
hospitalization_duration = 20
hospitalization_lag_from_onset = 7
icu_probability = 0.01
icu_duration = 10
icu_lag_from_onset = 11
death_probability = 0.1
death_lag_from_onset = 25

Here the parameters are

incubation_period
Incubation period of the disease in days.
infectious_period
How long a patient can infect others (in days) after the incubation period.
initial_R0
Basic reproductive number of the disease
hospitalization_probability
Probability that an infected person needs hospitalization
hospitalization_duration
Average duration of a hospitalization in days.
hospitalization_lag_from_onset
Average time (in days) from the onset of symptoms to admission to hospital
icu_probability
Probability that an infected person needs hospitalization.
icu_duration
Average duration of the need for intensive care in days.
icu_lag_from_onset
Average time (in days) from the onset of symptoms to admission to ICU.
death_probability
Probability that an infected person dies from the disease.
death_lag_from_onset
Average time from the onset of symptoms to death (in days).
population
The total population.

[model] (compartmentalization)

The [model] section defines the parameters of the disease model. When you wish to separate your population into various compartments (e.g., age groups), your [model] section becomes more involved.

As an example, consider the population of Finland, divided to three compartments by ages: 0…15, 16…65, and 65+

[model]
compartments =
    0-15,
    16-65,
    65+

population =
    871036,
    3422996,
    1231274

incubation_period = 3
infectious_period = 7
initial_R0 = 2.5

hospitalization_probability =
    0.11,
    0.17,
    0.29

hospitalization_duration = 20
hospitalization_lag_from_onset = 7
icu_probability = 0.01
icu_duration = 10
icu_lag_from_onset = 11
death_probability = 0.1
death_lag_from_onset = 25

Here the parameters are

compartments
A comma-separated list of the compartment names
population
A comma-separated list of population of each compartment
incubation_period
Incubation period of the disease in days. If a single number, the same number is used for all compartments. You can define a different incubation period for each compartment by supplying a comma-separated list.
infectious_period
How long a patient can infect others (in days) after the incubation period. If a single number, the same number is used for all compartments. You can use a different value for each compartment by supplying a comma-separated list.
initial_R0
Basic reproductive number of the disease. A single number.
hospitalization_probability
Probability that an infected person needs hospitalization. If a single number, the same number is used for all compartments. You can use a different value for each compartment by supplying a comma-separated list.
hospitalization_duration
Average duration of a hospitalization in days.
hospitalization_lag_from_onset
Average time (in days) from the onset of symptoms to admission to hospital.
icu_probability
Probability that an infected person needs hospitalization. If a single number, the same number is used for all compartments. You can use a different value for each compartment by supplying a comma-separated list.
icu_duration
Average duration of the need for intensive care in days.
icu_lag_from_onset
Average time (in days) from the onset of symptoms to admission to ICU.
death_probability
Probability that an infected person dies from the disease. If a single number, the same number is used for all compartments. You can use a different value for each compartment by supplying a comma-separated list.
death_lag_from_onset
Average time from the onset of symptoms to death (in days).

[initial state] (no compartmentalization)

When there are no compartments in the model, the [initial state] section of the configuration file should look something like

[initial state]
probabilities = True
population_susceptible = 0.8
population_exposed = 0.15
population_infected = 0.05

Here the parameters are

probabilities
If true, the rest of the parameters in this section are considered as probabilities, and the total number of exposed/infected people is computed by multiplying the total population by the provided value.
population_exposed
The total number (or probability) of exposed people
population_infected
The total number (or probability) of infected people

[initial state] (compartmentalized)

When there are compartments in the model, the [initial state] section of the configuration file should look something like

[initial state]
probabilities = True
population_exposed =
    0.001,
    0.01,
    0.005
population_infected =
    0.001,
    0.01,
    0.005

Here the parameters are

probabilities
If true, the rest of the parameters in this section are considered as probabilities, and the total number of exposed/infected people is computed by multiplying the total population by the provided value.
population_exposed
The total number (or probability) of exposed people
population_infected
The total number (or probability) of infected people

[restrictions]

We can model restrictions such as social distancing and closing of schools by introducing time-dependence in the infectivity rate (matrix, if compartmentalized model).

Restrictions can be defined in the config file within sections named [restriction TITLE]. You can define multiple restrictions in the same file.

The restrictions Rat are implemented as prefactors of the infectivity rate Infmat as

https://latex.codecogs.com/svg.latex?\mathcal{I}\to,R_0\circ,R_1\circ\dots\circ,R_{M-1}\mathcal{I}
Restrictions on all interactions

Define the day the restriction begins, the day the restriction is lifted, and the prefactor for the infectivity rate matrix between (and including) these days.

[restriction social-distancing]
day-begins = 20
day-ends = 180
infectivity modifier = 0.7
Restrictions on all some interactions

Define the day the restriction begins, the day the restriction is lifted, and the matrix-elements of the prefactor matrix R of the infectivity rate matrix.

You can define multiple elements of the prefactor-matrix on separate lines. For example, to decrease the contacts between the compartments 0-4, 5-9, 15-19 with the compartments 35-39,:code:40-44 (and vice versa) by 20%, and contacts between all compartments and the compartments 60-64 and 65+ by 80%, you specify the following

[restriction social-distancing experiment 2]
day-begins = 20
day-ends = 180
infectivity modifier =
    [ 0-4, 5-9, 15-19 ] : [ 35-39, 40-44 ] : 0.8
    all : [ 60-64, 65+ ] : 0.2
Restrictions from a file

Define the day the restriction begins, the day the restriction is lifted, and the file where the prefactor matrix Rat is stored in CSV format,

[restriction social-distancing experiment 2]
day-begins = 20
day-ends = 180
infectivity modifier = file://my_data/restrictions_prefactor.csv

Contact patterns (compartmentalized models)

Sometimes we have the knowledge of how many different daily contacts a person in compartment i has with persons from compartment j. This is called the contacts matrix, C[i,j].

The contacts matrix can be supplied to the SEIR command line tool with the flag -c

$ SEIR -cm my_contacts_matrix.csv configfile

The contacts matrix should be a space or comma separated file with the same number of columns and rows as there are compartments defined in the configuration file. For an example, please try:

$ SEIR -cm contacts_matrices/finland -cf example_configs/finland --visualize-compartments

Example contact pattern matrix can be found in the contacts_matrices/ directory of the repository in Github.

Output file

The SEIR tool outputs the computed model in a file called outfile.csv (can be changed with the -o option). The outputfile is a comma separated table containing the following simulation results:

time
Array of days from the beginning of the simulation
('susceptible', <compartment name>)
Number of susceptible people of compartment <compartment name> corresponding to each day in the ‘time’ array.
susceptible
Number of susceptible people in all compartments.
('exposed', <compartment name>)
Number of exposed people of compartment <compartment name> corresponding to each day in the ‘time’ array.
exposed
Number of exposed people in all compartments.
('infected (active)', <compartment name>)
Number of people with an active infection of compartment <compartment name> corresponding to each day in the ‘time’ array.
infected (active)
Number of people with an active infection in all compartments.
('infected (total)', <compartment name>)
Number of people who have an active infection (or have had one in the history) from compartment <compartment name> corresponding to each day in the ‘time’ array.
infected (total)
Number of people who have an active infection (or have had one in the history) in all compartments.
('removed', <compartment name>)
Number of removed of compartment <compartment name> corresponding to each day in the ‘time’ array.
removed
Number of removed people in all compartments.
('hospitalized (active)', <compartment name>)
Number of people who need hospitalization from compartment <compartment name> corresponding to each day in the ‘time’ array.
hospitalized (active)
Total number of people who need hospitalization.
('in ICU', <compartment name>)
Number of people who (currently) need intensive care from compartment <compartment name> corresponding to each day in the ‘time’ array.
in ICU (active)
Total number of people who currently need intensive care.
('deaths', <compartment name>)
Number of people from compartment <compartment name> who have died (cumulative sum).
deaths
Total number of people who have died.