# SynthPops
SynthPops is a module designed to generate synthetic populations that are used for COVID-19 (SARS-CoV-2) epidemic analyses. SynthPops can create generic populations with different network characteristics, as well as synthetic populations that interact in different layers of a multilayer contact network. **Note**: SynthPops is currently under active development and most features are fully tested and documented, but not all. We are in the process of expanding to include data and validation on additional regions beyond the original scope of the Seattle-King County region of Washington, USA. At the moment we have data for the following locations (in the synthpops/data folder) :
* Seattle Metro, Washington, USA
* Spokane County, Washington, USA
* Franklin County, Washington, USA
* Island County, Washington, USA
* Dakar, Dakar Region, Senegal
* Zimbabwe\*
* Malawi\*
* Nepal\*
\* Data for these locations are at the national scale. In the future, we hope to provide data at a more fine grained resolution for these locations.
The code was originally developed to explore the impact of contact tracing and testing in human contact networks in combination with our [Covasim repository](https://github.com/InstituteforDiseaseModeling/covasim). This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.
More extensive installation and usage instructions are in the [SynthPops documentation](https://docs.idmod.org/projects/synthpops/en/latest).
A scientific manuscript describing the model is currently in progress. If you use the model, in the mean time the recommended citation is:
**SynthPops: a generative model of human contact networks**. Mistry D, Kerr CC, Abeysuriya R, Wu M, Fisher M, Thompson A, Skrip L, Cohen JA, Althouse BM, Klein DJ (2021). (in preparation).
## Installation
Python >=3.7, <3.9 is required. Python 2 is not supported. Virtual environments are strongly recommended but not required.
To install, first clone the GitHub repository:
`git clone https://github.com/InstituteforDiseaseModeling/synthpops.git`
Then install via:
`python setup.py develop`
Note: while `synthpops` can also be installed via [pypi](https://pypi.org/project/synthpops), this method does not currently include the data files which are required to function, and thus is not recommended. We recommend using Python virtual environments managed with [Anaconda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#) to help with installation. Currently, our recommended installation steps are:
1. Install Anaconda.
2. Working either in an existing conda environment or creating a new environment with Anaconda, install synthpops by navigating to the directory for this package and running `python setup.py develop` via terminal.
## Quick Start
The following code creates and plots a the household layer of a synthetic population (using defaults for Seattle, Washington):
```python
import synthpops as sp
import matplotlib.pyplot as plt
n = 10000 # how many people in your population
pop = sp.Pop(n) # create the population
pop.plot_contacts() # plot the contact matrix
plt.show() # display contact matrix to screen
```
## Usage
In addition to the [documentation](https://docs.idmod.org/projects/synthpops/en/latest/usage.html), see the `examples` folder for usage examples.
## Structure
All core modeling is in the `synthpops` folder; standard usage is `import synthpops as sp`.
### data
The `data` folder contains demographic data used by the algorithms.
### synthpops
The `synthpops` folder contains the library, including:
* `base.py`: Frequently-used functions that do not neatly fit into other areas of the code base.
* `config.py`: Methods to set general configuration options.
* `contact_networks.py`: Functions to create a synthetic population with demographic data and places people into households, schools, and workplaces.
* `data_distributions.py`: Functions for processing the data.
* `households.py`: Functions for creating household contact networks.
* `ltcfs.py`: Functions for creating long-term care facility contact networks.
* `plotting.py`: Functions to plot age-mixing matrices.
* `pop.py`: The `Pop` class, which is the foundation of SynthPops.
* `process_census.py`: Functions to process US Census data.
* `sampling.py`: Statistical sampling functions.
* `schools.py`: Functions for creating school contact networks.
* `workplaces.py`: Functions for creating workplace contact networks.
### tests
The `tests` folder contains tests of different functions available in SynthPops.
## Disclaimer
The code in this repository was developed by IDM to support our research in disease transmission and managing epidemics. We’ve made it publicly available under the Creative Commons Attribution-ShareAlike 4.0 International License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as contemplated under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 License.
Raw data
{
"_id": null,
"home_page": "http://synthpops.org",
"name": "synthpops",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "human contact networks, synthetic population, age mixing patterns, census, demography",
"author": "Dina Mistry, Cliff Kerr, Meikang Wu, Mary Fisher, Ace Thompson, and Daniel Klein on behalf of the IDM COVID-19 Response Team",
"author_email": "covid@idmod.org",
"download_url": "https://files.pythonhosted.org/packages/3e/a5/aa14cc5ff1cf2d0b67b6b9631f809f02c55e13b4f4b079dcb9e763658985/synthpops-1.10.5.tar.gz",
"platform": "OS Independent",
"description": "# SynthPops\n\nSynthPops is a module designed to generate synthetic populations that are used for COVID-19 (SARS-CoV-2) epidemic analyses. SynthPops can create generic populations with different network characteristics, as well as synthetic populations that interact in different layers of a multilayer contact network. **Note**: SynthPops is currently under active development and most features are fully tested and documented, but not all. We are in the process of expanding to include data and validation on additional regions beyond the original scope of the Seattle-King County region of Washington, USA. At the moment we have data for the following locations (in the synthpops/data folder) :\n\n* Seattle Metro, Washington, USA\n* Spokane County, Washington, USA\n* Franklin County, Washington, USA\n* Island County, Washington, USA\n* Dakar, Dakar Region, Senegal\n* Zimbabwe\\*\n* Malawi\\*\n* Nepal\\*\n\n\\* Data for these locations are at the national scale. In the future, we hope to provide data at a more fine grained resolution for these locations.\n\n\nThe code was originally developed to explore the impact of contact tracing and testing in human contact networks in combination with our [Covasim repository](https://github.com/InstituteforDiseaseModeling/covasim). This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.\n\nMore extensive installation and usage instructions are in the [SynthPops documentation](https://docs.idmod.org/projects/synthpops/en/latest).\n\nA scientific manuscript describing the model is currently in progress. If you use the model, in the mean time the recommended citation is:\n\n**SynthPops: a generative model of human contact networks**. Mistry D, Kerr CC, Abeysuriya R, Wu M, Fisher M, Thompson A, Skrip L, Cohen JA, Althouse BM, Klein DJ (2021). (in preparation). \n\n\n## Installation\n\nPython >=3.7, <3.9 is required. Python 2 is not supported. Virtual environments are strongly recommended but not required.\n\nTo install, first clone the GitHub repository:\n\n`git clone https://github.com/InstituteforDiseaseModeling/synthpops.git`\n\nThen install via:\n\n`python setup.py develop`\n\nNote: while `synthpops` can also be installed via [pypi](https://pypi.org/project/synthpops), this method does not currently include the data files which are required to function, and thus is not recommended. We recommend using Python virtual environments managed with [Anaconda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#) to help with installation. Currently, our recommended installation steps are:\n\n1. Install Anaconda. \n\n2. Working either in an existing conda environment or creating a new environment with Anaconda, install synthpops by navigating to the directory for this package and running `python setup.py develop` via terminal.\n\n\n## Quick Start\n\nThe following code creates and plots a the household layer of a synthetic population (using defaults for Seattle, Washington):\n\n```python\nimport synthpops as sp\nimport matplotlib.pyplot as plt\n\nn = 10000 # how many people in your population\npop = sp.Pop(n) # create the population\npop.plot_contacts() # plot the contact matrix\nplt.show() # display contact matrix to screen\n```\n\n## Usage\n\nIn addition to the [documentation](https://docs.idmod.org/projects/synthpops/en/latest/usage.html), see the `examples` folder for usage examples.\n\n## Structure\n\nAll core modeling is in the `synthpops` folder; standard usage is `import synthpops as sp`.\n\n### data\n\nThe `data` folder contains demographic data used by the algorithms.\n\n### synthpops\n\nThe `synthpops` folder contains the library, including:\n\n* `base.py`: Frequently-used functions that do not neatly fit into other areas of the code base.\n* `config.py`: Methods to set general configuration options.\n* `contact_networks.py`: Functions to create a synthetic population with demographic data and places people into households, schools, and workplaces.\n* `data_distributions.py`: Functions for processing the data.\n* `households.py`: Functions for creating household contact networks.\n* `ltcfs.py`: Functions for creating long-term care facility contact networks.\n* `plotting.py`: Functions to plot age-mixing matrices.\n* `pop.py`: The `Pop` class, which is the foundation of SynthPops.\n* `process_census.py`: Functions to process US Census data.\n* `sampling.py`: Statistical sampling functions.\n* `schools.py`: Functions for creating school contact networks.\n* `workplaces.py`: Functions for creating workplace contact networks.\n\n### tests\n\nThe `tests` folder contains tests of different functions available in SynthPops.\n\n\n## Disclaimer\n\nThe code in this repository was developed by IDM to support our research in disease transmission and managing epidemics. We\u2019ve made it publicly available under the Creative Commons Attribution-ShareAlike 4.0 International License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as contemplated under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 License.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Synthetic contact network generation",
"version": "1.10.5",
"project_urls": {
"Homepage": "http://synthpops.org"
},
"split_keywords": [
"human contact networks",
" synthetic population",
" age mixing patterns",
" census",
" demography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d8079f9707cd4c60ecfa34a8924afd82c907fe6015d45badb1801a811b5c808",
"md5": "e143bb3454c938b3c8266c161a36d8a7",
"sha256": "9edabde5c042716cf8da57aa3dc782af63b25c03f0bdd935a82bdf48796d2c99"
},
"downloads": -1,
"filename": "synthpops-1.10.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e143bb3454c938b3c8266c161a36d8a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1531247,
"upload_time": "2024-04-02T20:47:47",
"upload_time_iso_8601": "2024-04-02T20:47:47.111662Z",
"url": "https://files.pythonhosted.org/packages/5d/80/79f9707cd4c60ecfa34a8924afd82c907fe6015d45badb1801a811b5c808/synthpops-1.10.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ea5aa14cc5ff1cf2d0b67b6b9631f809f02c55e13b4f4b079dcb9e763658985",
"md5": "56aac6ae45113471b1e8c967e266d4f7",
"sha256": "beea4c66447b228357226481009e77040713584344eb4c29daf075161792518b"
},
"downloads": -1,
"filename": "synthpops-1.10.5.tar.gz",
"has_sig": false,
"md5_digest": "56aac6ae45113471b1e8c967e266d4f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1582307,
"upload_time": "2024-04-02T20:47:48",
"upload_time_iso_8601": "2024-04-02T20:47:48.850262Z",
"url": "https://files.pythonhosted.org/packages/3e/a5/aa14cc5ff1cf2d0b67b6b9631f809f02c55e13b4f4b079dcb9e763658985/synthpops-1.10.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 20:47:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "synthpops"
}
JSON