# summer2: compartmental disease modelling in Python
[](https://github.com/monash-emu/summer2/actions/workflows/tests.yml)
summer2 is a Python-based framework for the creation and execution of [compartmental](https://en.wikipedia.org/wiki/Compartmental_models_in_epidemiology) (or "state-based") epidemiological models of infectious disease transmission.
It provides a range of structures for easily implementing compartmental models, including structure for some of the most common features added to basic compartmental frameworks, including:
- A variety of inter-compartmental flows (infections, transitions, births, deaths, imports)
- Force of infection multipliers (frequency, density)
- Post-processing of compartment sizes into derived outputs
- Stratification of compartments, including:
- Adjustments to flow rates based on strata
- Adjustments to infectiousness based on strata
- Heterogeneous mixing between strata
- Multiple disease strains
Some helpful links to learn more:
- **[Documentation](https://summer2.readthedocs.io/)** with [code examples](https://summer2.readthedocs.io/en/latest/examples/index.html)
- [Available on PyPi](https://pypi.org/project/summerepi2/) as `summerepi2`.
## Installation and Quickstart
This project requires at least Python 3.8
Set up and activate an appropriate virtual environment, then install the `summerepi2` package from PyPI
```bash
pip install summerepi2
```
Important note for Windows users:
summerepi2 relies on the Jax framework for fast retargetable computing. This is automatically
installed under Linux, OSX, and WSL environments.
It is strongly recommended that you use WSL, but in instances were you are unable to do so,
an unofficial build of jax can be installed by running the following command
```bash
pip install jax[cpu]==0.3.24 -f https://whls.blob.core.windows.net/unstable/index.html
```
Then you can now use the library to build and run models. See [here](https://summer2.readthedocs.io/en/latest/examples/index.html) for some code examples.
## Optional (recommended) extras
Summer has advanced interactive plotting tools built in - but they are greatly improved with the
addition of the pygraphviz library.
If you are using conda, the simplest method of installation is as follows:
```bash
conda install --channel conda-forge pygraphviz
```
For other install methods, see
https://pygraphviz.github.io/documentation/stable/install.html
## Development
[Poetry](https://python-poetry.org/) is used for packaging and dependency management.
Initial project setup is documented [here](./docs/dev-setup.md) and should work for Windows or Ubuntu, maybe for MacOS.
Some common things to do as a developer working on this codebase:
```bash
# Activate summer conda environment prior to doing other stuff (see setup docs)
conda activate summer
# Install latest requirements
poetry install
# Publish to PyPI - use your PyPI credentials
poetry publish --build
# Add a new package
poetry add
# Run tests
pytest -vv
# Format Python code
black .
isort . --profile black
```
## Releases
Releases are numbered using [Semantic Versioning](https://semver.org/)
- 1.0.0/1:
- Initial release
- 1.2.1
- Dropped support for Python 3.7. Variety of bugfixes and expanded features, see documentation
- 1.2.2
- Added capture utils
- Removed inner jit in model building to improve debugging
- 1.2.4
- CompartmentValues not functioning previously; include more comprehensive check in graph split
- 1.2.5
- Previous issue was not resolved correctly; bugfix-bugfix release
- 1.2.6
- Make full (comparment) outputs optional for jax runners
- 1.2.8
- Improve time varying functions (allow GraphObjects in x values)
- 1.2.9
- Derived output functions matching pandas.Series functionality (rolling, diff)
- 1.3.0
- Support initializing whole population via GraphObject
- 1.3.1
- Enforce jax minimum version in requirements
- 1.3.2
- Fix parameter bug in test models
- 1.3.3
- Fix issue with binary search for piecewise functions
- 1.3.4
- Update import in ode.py for changed jax API
- 1.3.5
- Force specific jax (0.4.24) to stop breaking changes
## Release process
To do a release:
- Commit any code changes and push them to GitHub
- Choose a new release number accoridng to [Semantic Versioning](https://semver.org/)
- Add a release note above
- Edit the `version` key in `pyproject.toml` to reflect the release number
- Publish the package to [PyPI](https://pypi.org/project/summerepi/) using Poetry, you will need a PyPI login and access to the project
- Commit the release changes and push them to GitHub (Use a commit message like "Release 1.1.0")
- Update `requirements.txt` in Autumn to use the new version of Summer
```bash
poetry build
poetry publish
```
Raw data
{
"_id": null,
"home_page": "http://summerepi.com/",
"name": "summerepi2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10.0",
"maintainer_email": null,
"keywords": "epidemiology, disease, compartmental, infectious",
"author": "David Shipman",
"author_email": "dshipman@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7a/68/480ca5ab09f3bd83e28e80c49a2d8c94e3e8c295efcf6a79b483fdd81adf/summerepi2-1.3.5.tar.gz",
"platform": null,
"description": "# summer2: compartmental disease modelling in Python\n\n[](https://github.com/monash-emu/summer2/actions/workflows/tests.yml)\n\nsummer2 is a Python-based framework for the creation and execution of [compartmental](https://en.wikipedia.org/wiki/Compartmental_models_in_epidemiology) (or \"state-based\") epidemiological models of infectious disease transmission.\n\nIt provides a range of structures for easily implementing compartmental models, including structure for some of the most common features added to basic compartmental frameworks, including:\n\n- A variety of inter-compartmental flows (infections, transitions, births, deaths, imports)\n- Force of infection multipliers (frequency, density)\n- Post-processing of compartment sizes into derived outputs\n- Stratification of compartments, including:\n - Adjustments to flow rates based on strata\n - Adjustments to infectiousness based on strata\n - Heterogeneous mixing between strata\n - Multiple disease strains\n\nSome helpful links to learn more:\n\n- **[Documentation](https://summer2.readthedocs.io/)** with [code examples](https://summer2.readthedocs.io/en/latest/examples/index.html)\n- [Available on PyPi](https://pypi.org/project/summerepi2/) as `summerepi2`.\n\n## Installation and Quickstart\n\nThis project requires at least Python 3.8\n\nSet up and activate an appropriate virtual environment, then install the `summerepi2` package from PyPI\n\n```bash\npip install summerepi2\n```\n\nImportant note for Windows users:\nsummerepi2 relies on the Jax framework for fast retargetable computing. This is automatically\ninstalled under Linux, OSX, and WSL environments. \nIt is strongly recommended that you use WSL, but in instances were you are unable to do so,\nan unofficial build of jax can be installed by running the following command\n\n```bash\npip install jax[cpu]==0.3.24 -f https://whls.blob.core.windows.net/unstable/index.html\n```\n\nThen you can now use the library to build and run models. See [here](https://summer2.readthedocs.io/en/latest/examples/index.html) for some code examples.\n\n## Optional (recommended) extras\n\nSummer has advanced interactive plotting tools built in - but they are greatly improved with the\naddition of the pygraphviz library.\n\nIf you are using conda, the simplest method of installation is as follows:\n\n```bash\nconda install --channel conda-forge pygraphviz\n```\n\nFor other install methods, see\nhttps://pygraphviz.github.io/documentation/stable/install.html\n\n## Development\n\n[Poetry](https://python-poetry.org/) is used for packaging and dependency management.\n\nInitial project setup is documented [here](./docs/dev-setup.md) and should work for Windows or Ubuntu, maybe for MacOS.\n\nSome common things to do as a developer working on this codebase:\n\n```bash\n# Activate summer conda environment prior to doing other stuff (see setup docs)\nconda activate summer\n\n# Install latest requirements\npoetry install\n\n# Publish to PyPI - use your PyPI credentials\npoetry publish --build\n\n# Add a new package\npoetry add\n\n# Run tests\npytest -vv\n\n# Format Python code\nblack .\nisort . --profile black\n```\n\n## Releases\n\nReleases are numbered using [Semantic Versioning](https://semver.org/)\n\n- 1.0.0/1:\n - Initial release\n- 1.2.1\n - Dropped support for Python 3.7. Variety of bugfixes and expanded features, see documentation\n- 1.2.2\n - Added capture utils\n - Removed inner jit in model building to improve debugging\n- 1.2.4\n - CompartmentValues not functioning previously; include more comprehensive check in graph split\n- 1.2.5\n - Previous issue was not resolved correctly; bugfix-bugfix release\n- 1.2.6\n - Make full (comparment) outputs optional for jax runners\n- 1.2.8\n - Improve time varying functions (allow GraphObjects in x values)\n- 1.2.9\n - Derived output functions matching pandas.Series functionality (rolling, diff)\n- 1.3.0\n - Support initializing whole population via GraphObject\n- 1.3.1\n - Enforce jax minimum version in requirements\n- 1.3.2\n - Fix parameter bug in test models\n- 1.3.3\n - Fix issue with binary search for piecewise functions\n- 1.3.4\n - Update import in ode.py for changed jax API\n- 1.3.5\n - Force specific jax (0.4.24) to stop breaking changes\n\n## Release process\n\nTo do a release:\n\n- Commit any code changes and push them to GitHub\n- Choose a new release number accoridng to [Semantic Versioning](https://semver.org/)\n- Add a release note above\n- Edit the `version` key in `pyproject.toml` to reflect the release number\n- Publish the package to [PyPI](https://pypi.org/project/summerepi/) using Poetry, you will need a PyPI login and access to the project\n- Commit the release changes and push them to GitHub (Use a commit message like \"Release 1.1.0\")\n- Update `requirements.txt` in Autumn to use the new version of Summer\n\n```bash\npoetry build\npoetry publish\n```\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Summer is a compartmental disease modelling framework, written in Python. It provides a high-level API to build and run models.",
"version": "1.3.5",
"project_urls": {
"Documentation": "http://summerepi.com/",
"Homepage": "http://summerepi.com/",
"Repository": "https://github.com/monash-emu/summer2"
},
"split_keywords": [
"epidemiology",
" disease",
" compartmental",
" infectious"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fd034d7baaa0a777a40adeb77b691af910c17ec574babc62bfeaa9c2e96334f",
"md5": "ba42aaf31796a076ff8261b8b03a7a45",
"sha256": "9f86786feb6bf230f773cb1f268fa38d672505059e899056525e91cfcae95715"
},
"downloads": -1,
"filename": "summerepi2-1.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba42aaf31796a076ff8261b8b03a7a45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.0",
"size": 72641,
"upload_time": "2024-03-26T00:28:00",
"upload_time_iso_8601": "2024-03-26T00:28:00.527580Z",
"url": "https://files.pythonhosted.org/packages/0f/d0/34d7baaa0a777a40adeb77b691af910c17ec574babc62bfeaa9c2e96334f/summerepi2-1.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a68480ca5ab09f3bd83e28e80c49a2d8c94e3e8c295efcf6a79b483fdd81adf",
"md5": "9210a214144300a7fcd71b052a9c0933",
"sha256": "f2a071792250a0087b994e9694f2e414eb862210aa556b7a1b37070444ca2ea6"
},
"downloads": -1,
"filename": "summerepi2-1.3.5.tar.gz",
"has_sig": false,
"md5_digest": "9210a214144300a7fcd71b052a9c0933",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.0",
"size": 64958,
"upload_time": "2024-03-26T00:28:03",
"upload_time_iso_8601": "2024-03-26T00:28:03.591854Z",
"url": "https://files.pythonhosted.org/packages/7a/68/480ca5ab09f3bd83e28e80c49a2d8c94e3e8c295efcf6a79b483fdd81adf/summerepi2-1.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-26 00:28:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "monash-emu",
"github_project": "summer2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "summerepi2"
}
JSON
