# Summer: compartmental disease modelling in Python
[](https://github.com/monash-emu/summer/actions/workflows/tests.yml)
Summer 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:
- [Rationale](http://summerepi.com/rationale.html) for why we are building Summer
- **[Documentation](http://summerepi.com/)** with [code examples](http://summerepi.com/examples)
- [Available on PyPi](https://pypi.org/project/summerepi/) as `summerepi`.
- [Performance benchmarks](https://monash-emu.github.io/summer/)
## Installation and Quickstart
This project requires at least Python 3.7 (and is actively targeted at 3.9)
Install the `summerepi` package from PyPI
```bash
pip install summerepi
```
Then you can use the library to build and run models. See [here](http://summerepi.com/examples) for some code examples.
## 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.1.0:
- Add stochastic integrator
- 2.0.2:
- Rename fractional flow to transition flow
- Remove sojourn flow
- Add vectorized backend and other performance improvements
- 2.0.3:
- Set default IVP solver to use a maximum step size of 1 timestep
- 2.0.4:
- Add runtime derived values
- 2.0.5:
- Remove legacy Summer implementation
- 2.1.0:
- Add AdjustmentSystems
- Improve vectorization of flows
- Add computed_values inputs to flow and adjustment parameters
- 2.1.1:
- Fix for invalid/unused package imports (cachetools)
- 2.2.0
- Add validation and compartment caching optimizations
- 2.2.1
- Derived output index caching
- Optimized fast-tracks for infectious multipliers
- 2.2.2
- JIT infectiousness calculations
- Various micro-optimizations
- 2.2.3
- Bugfix release (clamp outputs to 0.0)
- 2.2.4
- Datetime awareness, DataFrame outputs
- 2.2.5
- Performance improvements (frozenset), no API changes
- 2.2.6
- Verify strata in flow adjustments (prevent unexpected behaviour)
- 2.2.7
- Rename add_flow_adjustments -> set_flow_adjustments
- 2.2.8
- Split imports functionality (add_importation_flow now requires split_imports arg)
- 2.2.9
- Post-stratification population restribution
- 2.3.0
- First official version to support only Python 3.7
- 2.5.0
- Support Python 3.9
- 2.6.0
- Merge 3.9/master branches
- 2.7.0
- Include Python 3.10 support and update requirements
- 3.6.0
- Summer 'classic' end-of-line release
- 3.6.3
- Small compatibility fixed for numpy deprecations
## 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
```
## Documentation
Sphinx is used to automatically build reference documentation for this library.
The documentation is automatically built and deployed to [summerepi.com](http://summerepi.com/) whenever code is pushed to `master`.
To run or edit the code examples in the documentation, start a jupyter notebook server as follows:
```bash
jupyter notebook --config docs/jupyter_notebook_config.py
# Go to http://localhost:8888/tree/docs/examples in your web browser.
```
You can clean outputs from all the example notbooks with
```bash
./docs/scripts/clean.sh
```
To build and deploy
```bash
./docs/scripts/build.sh
./docs/scripts/deploy.sh
```
To work on docs locally
```bash
./docs/scripts/watch.sh
```
Raw data
{
"_id": null,
"home_page": "http://summerepi.com/",
"name": "summerepi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.1,<3.11",
"maintainer_email": "",
"keywords": "epidemiology,disease,compartmental,infectious",
"author": "James Trauer",
"author_email": "james.trauer@monash.edu",
"download_url": "https://files.pythonhosted.org/packages/3a/d0/3d645964dedc8a2766e385ef894c7184d78f62e5606361bb0eac35095234/summerepi-3.6.4.tar.gz",
"platform": null,
"description": "# Summer: compartmental disease modelling in Python\n\n[](https://github.com/monash-emu/summer/actions/workflows/tests.yml)\n\nSummer 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- [Rationale](http://summerepi.com/rationale.html) for why we are building Summer\n- **[Documentation](http://summerepi.com/)** with [code examples](http://summerepi.com/examples)\n- [Available on PyPi](https://pypi.org/project/summerepi/) as `summerepi`.\n- [Performance benchmarks](https://monash-emu.github.io/summer/)\n\n## Installation and Quickstart\n\nThis project requires at least Python 3.7 (and is actively targeted at 3.9)\nInstall the `summerepi` package from PyPI\n\n```bash\npip install summerepi\n```\n\nThen you can use the library to build and run models. See [here](http://summerepi.com/examples) for some code examples.\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.1.0:\n - Add stochastic integrator\n- 2.0.2:\n - Rename fractional flow to transition flow\n - Remove sojourn flow\n - Add vectorized backend and other performance improvements\n- 2.0.3:\n - Set default IVP solver to use a maximum step size of 1 timestep\n- 2.0.4:\n - Add runtime derived values\n- 2.0.5:\n - Remove legacy Summer implementation\n- 2.1.0:\n - Add AdjustmentSystems\n - Improve vectorization of flows\n - Add computed_values inputs to flow and adjustment parameters\n- 2.1.1:\n - Fix for invalid/unused package imports (cachetools)\n- 2.2.0\n - Add validation and compartment caching optimizations\n- 2.2.1\n - Derived output index caching\n - Optimized fast-tracks for infectious multipliers\n- 2.2.2\n - JIT infectiousness calculations\n - Various micro-optimizations\n- 2.2.3\n - Bugfix release (clamp outputs to 0.0)\n- 2.2.4\n - Datetime awareness, DataFrame outputs\n- 2.2.5\n - Performance improvements (frozenset), no API changes\n- 2.2.6\n - Verify strata in flow adjustments (prevent unexpected behaviour)\n- 2.2.7\n - Rename add_flow_adjustments -> set_flow_adjustments\n- 2.2.8\n - Split imports functionality (add_importation_flow now requires split_imports arg)\n- 2.2.9\n - Post-stratification population restribution\n- 2.3.0\n - First official version to support only Python 3.7\n- 2.5.0\n - Support Python 3.9\n- 2.6.0\n - Merge 3.9/master branches\n- 2.7.0\n - Include Python 3.10 support and update requirements\n- 3.6.0\n - Summer 'classic' end-of-line release\n- 3.6.3\n - Small compatibility fixed for numpy deprecations\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\n## Documentation\n\nSphinx is used to automatically build reference documentation for this library.\nThe documentation is automatically built and deployed to [summerepi.com](http://summerepi.com/) whenever code is pushed to `master`.\n\nTo run or edit the code examples in the documentation, start a jupyter notebook server as follows:\n\n```bash\njupyter notebook --config docs/jupyter_notebook_config.py\n# Go to http://localhost:8888/tree/docs/examples in your web browser.\n```\n\nYou can clean outputs from all the example notbooks with\n\n```bash\n./docs/scripts/clean.sh\n```\n\nTo build and deploy\n\n```bash\n./docs/scripts/build.sh\n./docs/scripts/deploy.sh\n```\n\nTo work on docs locally\n\n```bash\n./docs/scripts/watch.sh\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": "3.6.4",
"project_urls": {
"Documentation": "http://summerepi.com/",
"Homepage": "http://summerepi.com/",
"Repository": "https://github.com/monash-emu/summer"
},
"split_keywords": [
"epidemiology",
"disease",
"compartmental",
"infectious"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8edc9e0da0ef7a98cb6f87f831ef6c37a9faea90a9f58577dba03dbcfb59f3c0",
"md5": "a620f88940756eef3d6be7923678ed67",
"sha256": "bc6de076569027338831a72e6a94679fa62d5087a4e551c7ed11bef8b7bbcd14"
},
"downloads": -1,
"filename": "summerepi-3.6.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a620f88940756eef3d6be7923678ed67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.1,<3.11",
"size": 50261,
"upload_time": "2023-05-03T02:59:03",
"upload_time_iso_8601": "2023-05-03T02:59:03.805088Z",
"url": "https://files.pythonhosted.org/packages/8e/dc/9e0da0ef7a98cb6f87f831ef6c37a9faea90a9f58577dba03dbcfb59f3c0/summerepi-3.6.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ad03d645964dedc8a2766e385ef894c7184d78f62e5606361bb0eac35095234",
"md5": "336a8b0741ecc5a7afae7550af926cfd",
"sha256": "42b1c9e32a4a60f3612579a5972e4900595d8573ef797c590d4141ac19c75250"
},
"downloads": -1,
"filename": "summerepi-3.6.4.tar.gz",
"has_sig": false,
"md5_digest": "336a8b0741ecc5a7afae7550af926cfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.1,<3.11",
"size": 44736,
"upload_time": "2023-05-03T02:59:05",
"upload_time_iso_8601": "2023-05-03T02:59:05.766790Z",
"url": "https://files.pythonhosted.org/packages/3a/d0/3d645964dedc8a2766e385ef894c7184d78f62e5606361bb0eac35095234/summerepi-3.6.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-03 02:59:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "monash-emu",
"github_project": "summer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "summerepi"
}
JSON
