dataforscience / epidemik

Compartmental Epidemic Models in Python

epidemik

Compartmental Epidemic Models in Python

---

Table of contents

• Installation
• Tech Stack
• Basic Usage
• Documentation
• Contributing
• License

---

Installation

Use the package manager pip to install epidemik.

pip install epidemik

[ ↑ Back to top ↑ ]

---

Tech Stack

Here's a brief high-level overview of the tech stack the epidemik package uses:

• The model is implemented as a directed multigraph using networkx
• Ordinary Differential Equations are numerically integrated using scipy
• Random numbers are generated by numpy
• Model structure visualizations rely on matplotlib
• Progress bars generated by tqdm

[ ↑ Back to top ↑ ]

---

Basic Usage

epidemik provides three main modules, EpiModel, NetworkEpiModel and MetaEpiModel, usually imported directly from the epidemik package using the module name

from epidemik import EpiModel

• EpiModel -e Simple compartmental model in a homogeneously mixed population.
• NetworkEpiModel - Compartmental model on a network where nodes interact only along edges connecting them.
• MetaEpiModel - Meta population model where populations interact with one another along the edges of a network. Each sub-population has it's own internal EpiModel instance.

To instantiate a new compartmental model we just need to create a EpiModel object and add the relevant transitions:

beta = 0.2
mu = 0.1

SIR = EpiModel()
SIR.add_interaction('S', 'I', 'I', beta)
SIR.add_spontaneous('I', 'R', mu)

This fully defines the model. We can get a textual representation of the model using

print(SIR)

resulting in a simple description of hte model structure.

Epidemic Model with 3 compartments and 2 transitions:

S + I = I 0.200000
I -> R 0.100000

R0=2.00

or a graphical representation by calling draw_model():

SIR.draw_model()

The models value of the Basic Reproductive Number (R0) can be determined using the R0() function:

SIR.R0()

There are two ways to explore the dynamics of the model, each with it's corresponding method.

To integrate numerically the Ordinary Differential Equations that describe the model dynamics, we can call the integrate() method. The first argument is the number of time steps to integrate over and the remaining arguments are the initial populations of each compartment.

N = 10_000
I0 = 10

SIR.integrate(365, S=N-I0, I=I0, R=0)

The results of the integration are stored in the values_ field. A quick visualization of the results can be obtained using:

SIR.plot()

which produces:

[ ↑ Back to top ↑ ]

---

Documentation

The full documentation for this project is available at ReadTheDocs in html, PDF and ePub formats.

[ ↑ Back to top ↑ ]

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Join our project and provide assistance by:

• Checking out the list of open issues where we need help.
• If you need new features, please open a new issue or start a discussion.

Contact us for the feedback or new ideas.

[ ↑ Back to top ↑ ]

---

Spread The Word

If you want to say thank you and/or support active development of the epidemik package:

• Add a GitHub star to the repository to encourage contributors and helps to grow our community.
• Tweet about the project on your Twitter!
  • Tag @data4sci and/or @bgoncalves

Thank you so much for your interest in growing our community!

---

License

epidemik is free and open-source software licensed under the MIT License [2024] - Bruno Gonçalves, Data For Science, Inc. Please have a look at the LICENSE.md for more details.

[ ↑ Back to top ↑ ]

epidemik's Issues

Sphinx documentation

Now that integration with readthedocs is complete, we have to start populating the documentation. There are a few specific things that we should add:

• Brief overview of the structure of the library
• High level description of the three main modules
• Explanation of the arguments for each method
• Examples of the way to use the package. We can refer to the blog posts for examples of the full functionality

With some luck, the documentation can also serve as the starting point for defining a complete set of tests