SIR Model Calculator

Program to model an epidemic outbreak, using a basic SIR Model, then visualise in matplotlib
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Tests
     • Unit Tests
     • Linter
3. Usage
4. Contributing
5. Releases
6. License
7. Contact

About The Project

This project aims to use the SIR Model to simulate an epidemic outbreak in a closed population. This was originally a coursework question for my Degree which I found particularly intriguing, so I figured I'd redo my answer in Python and add some nifty data visualisation to boot.

Note that instructions in the readme are for setting up a local development environment, whereas releases will contain instructions on how to utilise outside of a local development environment.

(back to top)

Built With

• matplotlib

(back to top)

Getting Started

The steps below detail how to get a local version up the program up and running.

Prerequisites

• Windows
  • Python 3
• Linux
  • Python 3

Installation

• Windows

  • Clone repo and cd into repo

  git clone https://github.com/Sudoblark/SIR_Model_Animation.git
  cd SIR_Model_Animation

  • Setup Python venv and activate

  python3 -m venv venv
  venv\Scripts\activate

  • Install dependencies

  pip3 install -r requirements

• Linux

  • Clone repo and cd into repo

  git clone https://github.com/Sudoblark/SIR_Model_Animation.git
  cd SIR_Model_Animation

  • Setup Python venv

  python3 -m venv venv
  source venv/bin/activate

  • Install dependencies

  pip3 install -r requirements.txt

(back to top)

Tests

Unit Tests

Unit tests are run on every commit, but you can do them yourself if working locally by following the below instructions.

• Setup a venv as per installation instructions
• Install the following packages:

pip install pytest

• Run pytest with Python executor to implicitly add current path to PYTHONPATH

python -m pytest

(back to top)

Linter

PyLint is run on every commit, but you can run it yoruself if working locally by following the below instructions.

• Setup a venv as per installation instructions
• Install the following packages:

pip install pylint
pip install pylint_gitlab

• Run PyLint with HTML output

pylint src --exit-zero --load-plugins=pylint_gitlab --output-format=gitlab-pages-html --output=index.html

Usage

Now your virtual environment is setup, change to the src directory and run help to determine what options are available:

(venv) C:\temp\sir_model_calculator\src>python -m main -h

For example, running the below will output a line graph showing SIR data:

(venv) C:\temp\SIR_Model_Animation\src>python -m main matplotlib 150 4 60 0.43 0.18

(back to top)

CI

CircleCI is used to run unit tests, generate code coverage reports, run pylint and both build and push docker images to dockerhub.

This follows a rather standard workflow of:

• Commits not on main cause CI to kick in, and to push docker images with a tag of dev
• Commits on main (i.e. an approved PR that is merged) causes CI to ckick in, but pushes docker images with a tag of qa rather than dev
• Marking a release in Github triggers CI, but pushes docker images with the following tags:
  • latest
  • VERSION corresponding to the release, e.g. 0.1.0

Setup

• Code coverage reports are uploaded to codecov, using CODECOV_TOKEN for the authorisation token
• DOCKER_USER and DOCKER_PASS env vars are needed for dockerhub authorisation

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Releases

Releases are both distributed as source code and a docker image.

Docker

Images are pushed to dockerhub via circleCI.

Both dockerfile and README.md for dockerhub are inside the docker folder

Manually building and pushing

To manually build and push run the following commands:

docker build -f .\docker\dockerfile . -t sudoblark/sir-model-calculator:tagname
# Done so we also push the readme.md
cd docker 
docker push sudoblark/sir-model-calculator:tagname

Source Code

TODO

(back to top)

License

Distributed under the GNU General Public License. See LICENSE.txt for more information.

(back to top)

Contact

Sudoblark - @linkedin_handle

Project Link: sir_model_calculator

(back to top)