# 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 are implemented as prefactors of the infectivity rate as

##### 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 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.