DEV Community: q9i

Disease Modeling with epispot

q9i — Tue, 20 Apr 2021 23:06:28 +0000

To get started with this post, install epispot, one of the largest epidemiological modelers for Python. Fire up a command line and type one of the following:

pip install epispot # pip
pip install epispot-nightly # pip (nightly version)
conda install epispot # Anaconda

Alternatively, you can install epispot from the source via:

git clone https://github.com/epispot/epispot
cd epispot
git checkout master
# git checkout nightly (nightly version)
python setup.py install

Now let's get started! In this tutorial, we will be recreating the SIR model, the most basic of compartmental models in epidemiology. At its core, the SIR model consists of three "classes:"

Susceptible (not infected yet)
Infected (infected and actively spreading disease)
Removed (either dead or recovered --i.e. not spreading the disease)

Parameters

Before we dive into creating the Model, we need to
establish some of the parameters that will be used to
define our model.

Note: if you aren't sure about which parameters are
needed for a specific model, always consult the
compartment docstrings using the built-in Python
help() command.

1. `R_0` (basic reproductive number)

This number represents the number of
Susceptibles one Infected will infect,
assuming that everyone else is Susceptible. A
number greater than one means the disease is still
spreading, whereas a number less than one means
the disease is dying out. For reference, most
epidemics have an R_0 value of around 2.

2. `gamma` (recovery rate)

This variable is set to:

1 / avg time to recover

This acts as a buffer between the time an individual
is infected and when that individual recovers.

3. `N` (total population)

This is, of course, the total population of the
region in question.

4. `p_recovery` (probability of recovery)

The probability of recovery determines an individual's
chances of recovering after 1 / gamma days. This can
be used as a proxy measure to increase or decrease
gamma or can just be left as 1.

Before we finish this section, it is important to
understand how parameters are implemented in epi-spot.
All parameters are functions. This is because many
parameters change over the course of a disease. Take
R_0 for example. As social distancing and
quarantining measures are put in place, the disease
spreads more slowly and Infecteds are only able to
spread the disease to a fewer number of people, if at
all. This essentially lowers R_0 during the course
of the disease. In order to do this in epi-spot, we
simply change R_0 as time progresses, as we will be
doing in this example.

Coding

For R_0 we will use a simple logistic model,
something that lowers R_0 as a function of time:
slowly at the beginning, fast as the outbreak emerges,
and then slowly as R_0 creeps to 0 in order to end
the outbreak. We will use the following values:

R_0 start value: 2.0
R_0 end value: 0.0
gamma: 0.2
N: 100,000
p_recovery: 1.0

Each function takes in a parameter t representing
the time in days from the beginning of the outbreak.
This is implemented in lines 1-27.

Next, we create an instance of each layer in the
Model. These are listed in epispot.comps. Each
layer contains a certain category of people, whether
that be Susceptible, Infected, or Recovered. Before
using any of them, be sure to look at which parameters
to include depending on the next and previous layers.
Here, we implement them as:

Susceptible = epi.comps.Susceptible(0, R_0, gamma, N)  # Susceptible layer
Infected = epi.comps.Infected(1, N, R_0=R_0, gamma=gamma, p_recovery=p_recovery, recovery_rate=gamma)  # Infected layer
Recovered = epi.comps.Recovered(2, p_from_inf=p_recovery, from_inf_rate=gamma)  # Recovered layer

Next, we compile the Model class in epispot.models.

Model = epi.models.Model(N(0), 
        layers=[Susceptible, Infected, Recovered], 
        layer_names=['Susceptible', 'Infected', 'Recovered'],
        layer_map=[[Infected], [Recovered], []])

The layer_map parameter here contains an array with
an instance of the class of the next layer to each of
the layers in the Model. It will be more useful later
in complex models where we want to create different
paths through each of the layers.

Lastly, we call

epi.plots.plot_comp_nums(Model, range(0, 150, 1))

passing in our Model as one parameter and a time
range that we would like to plot. This will return a
matplotlib plot showing the values of each of those
compartments over the timerange specified.

There you have it! You've completed the basic tutorial
and understand the three main modules of epi-spot
(comps, models, and plots) and how to use them! To see the exact source code for this model, check out the GitHub source!

Contributing to epispot: made easy

q9i — Sat, 17 Apr 2021 19:27:07 +0000

Epispot is an open-source Python package for modeling infectious
diseases with support for compartmental models and graphing
utilities.

Epispot started small. In fact, when epispot was first launched, it was little more than a few scraps of code. But over time, with inspiration from other demos, epispot has become one of the largest Python packages for infectious disease modeling. As epispot turns a new corner, we hope to grow our open-source community and reach more contributors. This article outlines the main ways you can help contribute to the epispot/epispot repository on GitHub.

1. Fixing Bugs

Epispot categorizes issues by priority level. On the repository, each issue, after being processed, will be tagged with either a high-priority or low-priority label. A great way to contribute is to try and work on as many high-priority issues as possible. These issues tend to be bugs, vulnerabilities, or critical issues and your help will go a long way. But you don't need to fix a bug to actually help. Even adding more information about what the behavior of a certain bug is can help. However, if you do want to start working on a bugfix, run the following on a local computer:

$ git clone https://github.com/epispot/epispot
$ cd epispot
$ git checkout master
$ git branch patch-1
$ git checkout patch-1

Then, once you're done fixing the bug:

$ git add .
$ git commit -m "Fixed #[Issue Number]"
$ git push

After this you can successfully submit your PR to the main repo. After build and code quality tests run, your PR will be tagged and linked to the issue and then merged.

2. Documentation

One important misconception with contributing to open-source is that you have to code. However, documentation is a great way to contribute without actually coding.

Epispot's docs are generated using pdoc3, which automatically creates documentation for docstrings on the nightly branch. The nightly branch is essentially epispot's development branch--it's where all new changes and features go to get tested (and it even has its own package! To contribute, run the following in a git shell:

$ git clone https://github.com/epispot/epispot
$ cd epispot
$ git checkout nightly
$ git branch docs-1

Now you can start adding docs! Before starting, checkout DOCUMENTATION.md if you're unfamiliar with pdoc3. Then go into the epispot (package) directory, and edit the docstrings. To preview the docs, run

$ pdoc --html --output-dir docs epispot

This will create a docs/epispot folder which will be automatically gitignored so you can preview the docs and not have to delete them before committing. When you're done, run:

$ git add .
$ git commit -m "Added Documentation on [module name]"
$ git push

Now you can safely submit your PR and tag it with documentation. Most doc PRs will be merged soon since tests don't have to run.

3. Localization

One of the other great ways you can contribute to epispot, without even using a terminal or code editor, is through localization. Epispot uses gitlocalize to localize documentation. If you speak another language, you can add it and start working on localizing it. Then, submit a review request. This will get approved soon and a PR will be created in GitHub. Note that all localizations are pushed to the gh-pages branch by default where they will be deployed instantly after merging.

Conclusion

Epispot hopes that through our open-source efforts we can grow our contributors. If you are interested in contributing, head on over to the repo and check out our contributing guidelines! In the meanwhile, 👋

The epispot Project Roadmap

q9i — Thu, 15 Apr 2021 22:49:18 +0000

Epispot is one of the largest and simplest epidemiological modeling tools for Python. Install via one of the following:

pip install epispot
conda install epispot

Alternatively, you can install it from the source:

git clone https://github.com/epispot/epispot
cd epispot
python setup.py install

If you're new to epispot, start by reading the information provided on the READMEs in PyPI or GitHub here

While the epispot package has had tremendous success and now has over 15 releases (just counting the master package), the epispot team would like to announce a preview of what's to come. We present to you the epispot project roadmap:

In Maintenance:

In Automation:
- Automate release notes on master & nightly
- Automate documentation on master & nightly
- Dependabot automation everywhere
In Packaging:
- Automatic conda deployment on nightly
- Direct conda packaging (without conda-forge)?
In Issue Management:
- Automate issue labels
In Branch Management:
- Automatic code coverage reports on pull requests and commits
- Automate merge conflict resolutions for master→nightly
- Automate merge conflict resolutions for nightly→master

In Development:

In Compartments:
- Vaccinated
- Severe
- Mild
- Immune
- Asymptomatic
- Quarantined
In Model Types:
- Cluster
- Probabilistic
- Monte-Carlo Simulation
- Large Area Simulation
In Small Updates:
- Anything?
In Major Changes:
- Demographic modeling within compartments
- More information on integrate()
  - inflection points
  - extrema
  - herd immunity markers
  - Pre-built support for geographic modeling
In Integrations:
- Live COVID-19 data
- Live national cases data
- Live city/county data

In Simulations:

Small-Scale
- Use spatial models get to accurate small-scale predictions
- Implement in large cities:
  - San Francisco
  - London
  - Tokyo
  - New York
  - Mexico City
  - Mumbai
  - Add an open-source platform for more cities to be added
Build a web dashboard
Large-Scale
- Add large-scale modeling to CLI
- Implement a Cluster model to simulate travel across major hotspots
- Get a geographic model ready for world mapping

Lastly: The long-awaited command line-interface (is here! 🎆)--no, really, check it out

Reopening Safely: A Tale of Four Cities

q9i — Sun, 13 Dec 2020 00:42:16 +0000

The follow-up to “Reopening Safely: The Data Science Approach.” We examine the use of lockdowns, social distancing and other citywide measures and their effectiveness.

Photo by Waldemar Brandt on Unsplash

Notes:

This article is the second in a series about using data science to analyze reopening strategies. If you haven’t already, read the first article before this one.
All the code in this article has been based off of the covid-19 repository set up by epispot to help fight the coronavirus. The complete source code for the simulations in this article can be found there.

The last article has clearly proven that doing nothing is not a strategy when it comes to reopening cities in wake of the coronavirus. The speed at which the coronavirus spreads is too fast and uncontrollable to be left up to chance. However, the secret to mitigating the spread of COVID-19 lies in its predictability. As explained in the previous article, the SIR Model, and many others, can quite accurately model how a virus spreads. In fact, there exist many free open-source libraries that can run these models and give predictions. Just like in the last article, we will be using epispot throughout this article for modeling and analysis.

Part 1: Tracking Hospitalizations

In order to compare the various reopening strategies employed across the globe, we have randomly selected 4 cities with sufficient COVID-19-related hospitalization data. The cities are:

Tokyo, Japan
San Francisco, US
New York, US
London, UK

The associated hospitalization data has been linked along with the city names.

First, let’s take a look at how hospitalizations* in each of the five cities has progressed since the start of the coronavirus:

No data for New York and London was available before their trend lines begin. Note that the y-axis is proportional to city size, recording the portion of hospitalized individuals (think percentage of people hospitalized / 100)

*We examine COVID-19-related hospitalization data because this data is the most accurate of all other data sources. Other sources, like case counting, rely on testing efforts which can only reach a small portion of the population each day.

Clearly, there is one trend line that completely dominates this graph — those hospitalizations are from Tokyo. Upon closer analysis, we can see that the peak begins to flatten after about the 40th day after 3/04/20, which corresponds with the date Japan imposed a nationwide state of emergency. After further lockdowns were implemented, Tokyo’s hospitalizations plummet within just 20 days, again highlighting the importance of small changes on a citywide or national level.

Even small changes made on a large-scale can have profound impacts on the change in coronavirus cases.

In order to focus on the more minute fluctuations of the hospitalizations, we zoom in on the bottom-right corner of the graph. Here are an additional two views:

The second of two distinct “waves” of coronavirus hospitalizations is shown for both San Francisco and Tokyo while London and New York seem to have almost no hospitalizations.

San Francisco’s all-time low nearly matches London and New York’s all-time high in hospitalizations. London’s and New York’s hospitalizations barely change as San Francisco’s increases again and Tokyo’s skyrockets (not visible on this graph).

Part 2: Tracking Cases

Example: San Francisco

Great! We have the hospitalization data, but there’s one crucial piece of information that is escaping these graphs: the confirmed cases! Without case information, it is impossible to truly understand how fast the disease will continue to spread. Thankfully, that’s not too hard to implement in epispot.

For those of you who are interested in the full source code, definitely check out the covid-19 repo from epispot, where all the code from this article is hosted. Here’s a quick snippet of the code used to fit the model:

If this code looks confusing to you, don’t worry! The goal here is to analyze the results, not worry about the code. Again, if you are interested in understanding this code, the epispot documentation is a great place to start (all resources linked at the end of this article). Essentially, the goal of this code is to fit a model to the hospitalization data that we downloaded earlier. Then, we can use epispot to predict the number of cases:

The difference between predicted hospitalizations and actual hospitalizations is due to random noise in the data.

This graph reveals two important ideas, one of which we have already discussed. That is the fact that even small changes in some parts of the model (like changes in hospitalizations) can result in huge changes in other parts of the model (like changes in cases). This massive surge in cases over San Francisco’s coronavirus “waves” tell us that the rate that the disease is spreading will continue to increase, causing an exponential increase in the number of cases.

In other words, if the spread is controlled quickly by the use of lockdowns or other preventive measures, it won’t take long before San Francisco or any city is completely overwhelmed with coronavirus cases (and hospitalizations).

For the second and last part of the analysis, we examine the crucial R Naught parameter, also known as the basic reproductive number. This was one of the important parameters in SIR Model because it tells us how fast an outbreak is growing. In its most basic form, it measures how many people one infected infects over their entire infectious period.

R Naught > 1: Epidemic is growing

R Naught = 1: Epidemic has stopped growing

R Naught < 1: Epidemic is ending

Here is the corresponding R Naught graph for the cases in San Francisco:

San Francisco’s outbreak seems to be declining for the most part (R Naught is less than 1), but as soon as reopening began, the R Naught value peaked again at a value over 1 indicating that the coronavirus is beginning to spread yet again.

The Wrap-Up (Not Quite)

Clearly, we have seen how the coronavirus has developed in many cities across the globe. We have used hospitalization data to generate case data, understand how different factors affect the growth rate of COVID-19, and seen some amazing visualizations of the spread of the coronavirus. Of course, there is still much, much more to be done. To start, we have not even started with predictions … and we still have not examined the hospitalization spike in Tokyo, and the slow case growth in New York and London as they begin reopening. All this and more in the next article in this series …

This is article two of the series “Reopening Safely”

References

epispot: The code library on GitHub used for the predictions and analysis shown in this article

matplotlib: The amazing Python graphics library used for the stunning visualizations shown throughout this article

covid-19: The repo where all code in this article is stored at (hosted by epispot & GitHub). You can find the full code, data, and sources for this article there.

Reopening Safely Part One: The first article in this series (goes over epispot, the SIR Model, and basic modeling techniques)

epispot documentation: For creating “Lessons Learned from Japan’s Response to the First Wave of COVID-19: A Content Analysis”models of your own! (make sure to check out the repo for instructions as well)

“Lessons Learned from Japan’s Response to the First Wave of COVID-19: A Content Analysis”: A paper for more information on Tokyo and Japan’s response as a whole to the coronavirus

Reopening Safely: The Data Science Approach

q9i — Mon, 02 Nov 2020 03:21:24 +0000

The great reopening debate attacked using infectious disease modeling

With the coronavirus raging through major cities all over the world, the question remains the same: when is it safe to reopen? The answer is not simple, so as usual, data science comes to the rescue. Using an SIR-based model in multiple experiments will give clues to how the reopening of the world might look, and whether it will last.

The SIR Model

The SIR model is one of the most sacred disease modeling tools. Its versatility, simplicity, and effectiveness make it one of the most powerful tools in epidemiological modeling. Here is a simple breakdown of the key ideas behind the model:

The S, I, and R

The first step in the SIR model is to break down the population into three possible states: Susceptible (S), Infected (I), or Recovered (R). The states themselves are quite self-explanatory. However, the last state, removed, is also commonly referred to as the “Removed” state because it can contain individuals who are recovered or dead.

The Dynamics

As with many problems involving populations, it is much easier to describe the change of a state rather than it is to describe the state itself. Essentially, this means that differential equations are necessary.

The equations above might look intimidating at first glance, but when understood in the right context, they make perfect sense. In order to understand these equations, we need to define a few variables, notably:

Beta = infection rate * number of individuals a person makes contact with (essentially how many people 1 infected infects)

Gamma = 1 / days to recover (the recovery rate)

The first equation means that the number of people exiting the susceptible compartment per timestep is beta * I * S/N. This makes sense because each infected infects beta people (see the definition of beta). The last part, S/N, represents the portion of the population that is susceptible because an infected or recovered person cannot be reinfected*.

Now, since everyone who “leaves” the Susceptible compartment must go to the Infected compartment (you can’t jump to the Removed compartment without first being infected), the Infected compartment simply gets whatever population leaves the Susceptible compartment (notice the derivative of the Infected compartment is just the negated derivative of the Susceptible compartment with one other term). The extra term at the end represents the people leaving the Infected compartment after recovering (the recovery rate * the infected population). And lastly, the same number of people leaving the Infected compartment join the Recovered compartment.

*The idea that someone who has recovered from an illness cannot be susceptible to it again is one of the assumptions behind the SIR model which is mostly true for COVID-19

Setting it Up

Coding the SIR Model might seem quite intimidating at first, but luckily, there is a software library that can help — check out epispot on GitHub. Epispot can handle the SIR model and even more complex models (where there are exposed and hospitalized states). Coding this model in epispot will be covered in the following sections. The code itself is not that important (you can always consult the documentation), but its predictions and the reasons behind them are.

If you are interested in the code, there is one other parameter that epidemiologists frequently use (and one that epispot uses). That parameter is of course R Naught. R Naught is essentially beta / gamma or the net gain in the infected category per infected if 100% of the population is fully susceptible. Essentially, this tells epidemiologists how infectious a certain disease is (e.g. for COVID-19, this number is around 2.5).

The Case Study

San Francisco

The entire code would be too much to explain for this article, but if you are interested, see the sf-case-study-covid-19.py in the epispot repo. However, the rest of the article will be mostly code snippets.

After we import the epispot library and get everything configured, we load the San Francisco case data from 3/19 to 7/11 from DataSF. If you want to download the data yourself, this is in the epispot repo under tests/data . Here is a sample of the data:

Now we set up the model. Again, the full code for this can be found on GitHub, but for the sake of simplicity, only an important snippet is shown. After the coronavirus data loads, the model is set up in just a few lines of code:

Before we get the predictions, there is a little bit of setup required. The parameters used in this model ( R_0, gamma, N, delta, alpha ) have all been gathered using open data sets and a regression algorithm. This means that we have essentially fitted our model to the data to get more accurate estimates. In case you are interested, the regression was performed using data from the infamous Diamond Princess cruise ship.

Lastly, the model outputs the predictions (using the epi.plots.compare method), plotted on a logarithmic scale. The predictions are from 7/11 to 8/10 (1 month ahead)*. The predictions are calculated as if there is no social distancing at all (that is, San Francisco completely reopened). Finally, the question is answered:

*Yes, this is not exactly happening right now, but it still is useful because it gives a general idea of what could happen in the future. The modeling is also still necessary because we are simulating what would happen after a complete reopening, so we need to predict.

The infected and hospitalized cases before and after a full theoretical reopening

This graph can be a lot to take in at one time, especially since all the important details are stashed away in the right corner. Zooming in on days 120–140 yield the following graph:

A zoom-in of the predicted infecteds (light blue) and predicted hospitalized (dark blue)

The gigantic yellow box on top is the period where San Francisco’s maximum hospital capacity is passed (i.e. not everyone can be treated). At this point, there is a clear public health disaster — so how long did San Francisco’s pretend lockdown really last?

7 days.

What Happened?

Seven days is quite a surprising number. Only one week. That is the maximum duration of a complete reopening. Reopening clearly does not mean that there will be no safety precautions, but in many cases it does make some sacrifices. Aside from that, there are still many reasons why this model is an exaggeration: it is from a few months ago, the parameters are all estimated, etc. However, this model does show something important:

small changes in awareness, precautionary measures, or anything that is carried out on an even citywide scale can have major impacts.

Of course, several questions remain. For example, what would happen if there was just a partial reopening, or what if this was in a suburb, or New York, or what happened it Italy? See you in the next blog post …

This is article one of the series “Reopening Safely”

While you wait …

See the epispot repo on GitHub
See these Medium posts on infectious disease modeling
Look at the San Francisco case data

Credits

Epispot is built using numpy for managing multidimensional arrays. The plots shown in this article are using epispot’s plot feature, which relies on matplotlib for the stunning graphics and annotations.