epispot / epijs

A toolset for analyzing and creating epidemiological models.

---

epispot v3

A Python package for the mathematical modeling of infectious diseases via compartmental models. Originally designed for epidemiologists, epispot can be adapted for almost any type of modeling scenario.

Features

The epispot package currently only supports compartmental models, though we plan to expand the package to work for stochastic agent-based and spatial models as well. Currently, epispot offers the following:

• Quick compilation of compartmental models with the following compartments:
  • Susceptible
  • Infected
  • Recovered
  • Removed
  • Exposed
  • Dead
  • Critical
  • Hospitalized
• Custom-defined compartments for research
• Built-in graphing and visualization engine
  • Plots model predictions interactively
  • Creates comparisons between models

Due to its diverse range of features, epispot can be used for both research and experimental modeling. If you would like to add more modeling support, please see the contributing section.

Installation

Notice: The epispot nightly package is now officially deprecated.

The epispot package can be installed from PyPI, Anaconda, or be built from the source. Below are the steps for each installation process:

PyPI

This is the easiest way to install epispot. From a terminal, enter:

pip install epispot

Anaconda

The standard version of epispot is published to conda using the conda-forge channel. To install, please use:

conda config --add channels conda-forge
conda install -c conda-forge epispot

Building from the source

This is the hardest way to install epispot and it is recommended that you use either PyPI or Anaconda to install it instead. However, if you would like to contribute to the repository, this will be particularly useful.

Clone the repository and install the dependencies with:

git clone https://github.com/epispot/epispot
cd epispot
pip install -r requirements.txt
pip install -r bin/requirements.txt

Then, build the latest version with:

python setup.py install

For older releases, first checkout a version tag before installing; e.g.:

git checkout v2.1.1
python setup.py install

Quick Demo

Using epispot in a Python REPL to create the well-known SIR model (in less than three lines of code):

Documentation

Right now, documentation for some of the latest releases is quite shaky. The official docs are located at https://epispot.github.io/epispot/ but may be incomplete in many areas.

Examples

The GitHub repository has a vast array of samples using epispot. We are currently working on a tutorial, but for now the documentation is the best place to start.

Badges

PyPI:

LGTM:

Codecov:

Feedback

If you have any feedback, please

• Create a discussion on GitHub
• Create an issue if you've found a bug
• Submit a PR if you want to add a new feature
• Contact a CODEOWNER

Contributing

Contributions are always welcome! See CONTRIBUTING.md for instructions on how to get started, including environment setup and instructions to build from the source. Please note also that epispot has many guides dedicated to certain types of contributions. Please see

• DOCUMENTATION.md for documentation additions
• SECURITY.md for epispot's security policy

Citation

If you plan on using epispot in your project, please abide by the GPLv3 license. This requires that any changes you make to epispot are open-sourced under the GPLv3 license as well and that you give credit to the author, which you can do by citing the project in your research, linking back to the original repository, or mentioning the author @quantum9innovation.

For research, you can also use epispot's DOI to reference the project:

The recommended citation for epispot is:

quantum9innovation (2022, August 20). epispot/epispot: (Version 3.0.0-rc-1). Zenodo. http://doi.org/10.5281/zenodo.5136721

Related Work

There are many related projects to epispot, although we believe that epispot has greater extensibility than many of these other projects. Additionally, epispot is quite portable (graphs can be used as web components, displayed as images, etc.). However, below we would like to acknowledge a few projects that may be better suited to certain use cases:

• EpiJS by @Quantalabs contains the same functionality of epispot but in pure JavaScript, making it more suitable for use in a web browser
• covasim by the Institute for Disease Modeling offers agent-based stochastic models as opposed to epispot's compartmental modeling structure
• CovsirPhy by @lisphilar offers greater support for loading and analyzing real COVID-19 data instead of running simulations

Authors

Please see our CODEOWNERS file for authors. Because epispot is an open-source project, different pieces of our code have different authors. However, if citing epispot or using it in another project, you can cite @quantum9innovation as the lead author.

Acknowledgements

Idea & Inspiration

The original idea for epispot came from a 3Blue1Brown video on basic infectious disease dynamics and an interactive article in the Washington Post. This in turn inspired the very basic infectious disease dynamics simulated here. However, what finally set the package into motion was a series of articles by Henry Froese, available on Medium here, along with their corresponding interactive notebooks.

Code Development & Maintenance

The epispot project is built on open source code and is itself open-source. The initial core development was fueled by @quantum9innovation and much of the codebase was maintained by @Quantalabs. Additionally, thank you to all of epispot's open-source contributors!

epijs's Issues

Feature - Stochastic models

Is your feature request related to a problem? Please describe.
EpiJS's current feature set only allows for modeling through strict equations and never changes unless a parameter was changed.

Describe the solution you'd like
Adding stochastic models to both the model, pre, and com modules for more customizable models.

Describe alternatives you've considered
Manually adding noise to a key before passing into the function, and then running the function several times, which will only work on the model module and com module, and not the pre module.

Additional context
Work should start on patch-37 branch.

Feature - Allow key values to be a function of time

Is your feature request related to a problem? Please describe.
Users cannot pass in dynamic key values, that change overtime, which is useful when simulating a real world environment (ie. Users can change key values to model different restrictions that are lifted and added).

Describe the solution you'd like
Key values can still be passed through an object, but can be a function of time, with a single parameter, which is the iteration the model is on.

Describe alternatives you've considered
Other possibilities include users running the .get_data method for 1 day, changing the key value, running it again, and so on, which is inefficient and time consuming.

Additional context
This should be done with the v3a2 release.

Feature - Background Color Customization on Plots

Is your feature request related to a problem? Please describe.
In the plots module, users can select the border color, but not the background color of the module, which is defaulted to none.

Describe the solution you'd like
Allow users to have customization of the background color of the plots in the plot module.

Feature - Minification of browserify output

Is your feature request related to a problem? Please describe.
Browserify outputs gigantic files, unminified, and makes the code frequency graph look like this:

Notice that the lines of code reaches 100k. Perhaps minification will speed things up?

Describe the solution you'd like
Minifying the browserify output will make not only the run time faster for slow computers, but it helps save everyone's sanity.

Describe alternatives you've considered
None. This is the only way.

[v1.3.x] [Bug] Variables not properly declared

Describe the bug
Variables are not properly declared on line 63 of model.js.

EpiJS/EpiJS/model.js

Lines 63 to 64 in 32c102c

	key = this.key
	newkey = key

Expected behavior
When you run a command, perhaps:

model.get_data(20)

It returns an error:

$ node index.js
/home/user/project/node_modules/@epispot/epijs/EpiJS/model.js:63
key = this.key
         ^

ReferenceError: key is not defined

NPM

• NPM Version - 7.19.1
• Node.js Version - v16.4.2
• Operating System - Ubuntu (WSL)
• EpiJS Version - v1.3.1

Additional context
Solution can be easily fixed with:

var key = this.key 
var newkey = key

Feature - Extending Compartments

EpiJS's comp module currently has only the Idiom class, so extending this module would be extremely useful for people who don't know the equations behind each compartment.

Goals:

• Custom
• Susceptible Compartments
• Exposed Compartment
• Infected Compartment
• Hospitalized Compartment
• Critical Compartment
• Recovered Compartment
• Dead Compartment

These all should have the same format, so the model module can compile the models no matter the compartment:

CLASS - Compartment
     - constructor ()
     - get_data (key)

The constructor can have an optional equation parameter, and the pre-build compartments can have extra features for extensibility.

Feature - Plot models

Is your feature request related to a problem? Please describe.
Users currently cannot plot models from the model class, and instead only pre and com models, which limit the amount a user can extend there models

Describe the solution you'd like
Adding a plotting function for the plots module, which will allow plotting of models from the model module.

Describe alternatives you've considered
Manually plotting, which is time-consuming and inefficient.

[Bug] Switch from webpack to browserify

Describe the bug
Webpack's bundling of dependencies and code changes all function names, including those used in epijs. Browserify allows bundling of all dependencies and still allow for the code to be intact.

To Reproduce
Go to the web/index.min.js and search for "sir" or any other function/class name in EpiJS. It most likely isn't there.

Expected behavior
These functions/classes should show up, to allow for users on the web to access these commands.

Screenshots
Checking for the sir function in the pre module:

Checking for the Idiom function in the comp module:

Additional context
Browserify will be added on the patch-43 branch.

Feature - Version Lock

Currently EpiJS's package.json version numbers are not locked to a minor release and instead a major release, so new users can install new versions of packages that are minor changes and not patch changes, which could introduce incompatible changes and cause EpiJS to stop working. Version locking the versions with ~ instead of ^ at the begging of package.json would prevent these upgrades introducing incompatible changes.

Deprecation of the `com` module

As EpiJS grows more and more advanced, the uses for the com module grow smaller and smaller, and it makes it increasingly clear that we might need to deprecate the com module moving forward. There is an option of making this a completely separate package which would allow much more complex stats to be implemented. However, I do believe we should deprecate this in the v3 release.

Feature - Switch to mocha for testing

Is your feature request related to a problem? Please describe.
EpiJS cannot find errors for NodeJS, only the web or errors that span both.

Describe the solution you'd like
Switching to mocha allows us to use test NodeJS, and continue to test the web with puppeteer.

Describe alternatives you've considered
Manually testing, though that does not give us the same level of guarantee that there are no bugs, and code coverage cannot be reported.

Additional context
I am working on this in the v3-development branch.

Feature - Adding a `plots` module and no longer plotting charts in the `pre` module

Is your feature request related to a problem? Please describe.
Right now, the pre module only outputs a direct graph, unlike all the other modules.

Describe the solution you'd like
Instead, returning the output and then including a plots module, which could be extended in the future to also plot graphs from the com and model modules, which will take the data and plot it.

Describe alternatives you've considered
The only way to access the data is to use the ChartJS API to then fetch the chart and extract the data.

Additional context
Work is starting on the chart-fix branch built off the v2.0.0 branch.

Feature - Switch to `plotly` to allow graphing in node

Is your feature request related to a problem? Please describe.
The plots module is unavailable in NodeJS, and only accessible in the web, which can be a problem to those who need to use NodeJS. This builds a barrier between NodeJS and HTML, and makes the two seem like different libraries.

Describe the solution you'd like
However, using Plotly JavaScript we can extend this capability to NodeJS and keep web support. Plotly also allows for clean and more advanced graphing techniques.

Describe alternatives you've considered
Although users on Node could just use Plotly themselves, it prevents users from being able to quickly generate graphs and models.

Additional context
This would be a breaking change, and there are other ideas which might also bring breaking changes to the package. So, we'd need to make this a new v3 version. This would drop support for some v1 versions, but keeping support for v2 like we did when with v1 when v2 was first released is a good idea. This should also be shipped with #83 and #84, as they both will influence the redesign of the plots module. To put this into effect, we'd like approval from @quantum9Innovation.

Feature - Change `pre` module model structures to match `model` module strucutures

Is your feature request related to a problem? Please describe.
The pre module models and model module models have different structures which can be confusing and over-complicate things, when they can both be the same structure.

Describe the solution you'd like
Changing the structure of the pre module models to match the model module structures would be much easier, and minimize the number of functions needed in the plots module (no need to have one to plot pre-compiled models and another for custom models, plus a function to compare two models in the pre module, and the same for the model module).

Describe alternatives you've considered
It's much easier to change the structure of pre module models' structures to model structures, but not as easy to do vice-versa. In addition, it over complicates things to have two different structures that grow further apart as the package updates and changes.

Additional context
This will be worked on before implementation of #115 and #83.

Feature - Adding Testing and CI/CD pipelines

Is your feature request related to a problem? Please describe.
Testing on EpiJS is all done manually, and many CI/CD pipelines are failing.

Describe the solution you'd like
Using Travis CI for automatic testing on push, to prevent bugs faster and better, with open logs, and reform all the current pipelines so that we don't touch them again.

Additional context
Work has already started on ci/cd branch.

Feature - Importing and Exporting models Through Files

This feature would allow for users to export and import models through files, which I know, seems crazy and unnecessary, however, this would allow for users to quickly import and export models. For example, if a user has a very large JavaScript file, and just wants to port the model they have, they can then export it into a file, JSON, YAML, or TOML - we'll figure this out later on - and then import it in their other project and make modifications if they need to.

How?

It seems like JSON is the best choice for this feature, as we can load and export it quickly in JavaScript - after all, it is called JavaScript Object Notation - and most users will be familiar with this. I'll start work on this in patch-70.

Feature - Bundle dependencies with webpack

Is your feature request related to a problem? Please describe.
As EpiJS grows, we use more and more dependencies, which means more files to include in the user's HTML.

Describe the solution you'd like
Webpack allows you to bundle all files and dependencies in one file, and one command.

Additional context
Webpack - webpack.js.org
Work has already started on the webpack branch.

[Bug] Docs Not Working

Docs are somehow being hosted at ./ even though the docs are at ./latest and ./v2.0.0, and there are no docs in root. I'll start work on this right now.

Feature - Community Modelling with Models

Is your feature request related to a problem? Please describe.
Community Modelling is only available with pre-built models such as the SIR model.

Describe the solution you'd like
Expanding this and allowing modelling with different models that aren't integrated, such as perhaps a SIRS or even a non-SIR based model.

Additional context
Work will start on patch-40 branch.

Feature -SEIHCRD and other models

Feature request for a SEIHCRD model:
This includes:

• Susceptible
• Infected
  • Exposed
  • Infected
• Hospitalized
  • Hospitalized
  • Critical
• Removed
  • Recovered
  • Dead

This will allow more advanced modelling capabilities to better represent outbreaks.

Feature - Sub-compartments

Is your feature request related to a problem? Please describe.
Currently, sub-compartments in models are not supported. This prevents users from having more advanced models, perhaps a SIR model with an asymptomatic and symptomatic sub-compartments for the infected compartment, or even two sub-compartments for recorded and actual case data.

Describe the solution you'd like
Adding a simple way to include sub-compartments in a model, which will allow users to include more complex models like the examples above.

Describe alternatives you've considered
Users could instead create two separate compartments for each sub-compartment, however now if #83 is implemented, plotting will plot those as separate compartments, so in stacked charts, the plots will have an infected category, and then a symptomatic category, and asymptomatic category, all plotted separately.

Additional context
This feature should most likely be implemented before #83, or otherwise the issue will be reopened once finished.