# PyEI
[](https://doi.org/10.21105/joss.03397)
PyEI is a Python library for ecological inference. The target audience is the analyst with an interest in the phenomenon called Racially Polarized Voting.
Racially Polarized Voting is a legal concept developed through case law under the Voting Rights Act of 1965; its genesis is in the majority opinion of ***Thornburg v. Gingles (1982)***. Considered the “evidentiary linchpin” for vote dilution cases, RPV is a necessary, but not sufficient, condition that plaintiffs must satisfy for a valid claim.
Toward that end, ecological inference uses observed data (historical election results), pairing voting outcomes with demographic information
for each precinct in a given polity, to infer voting patterns for each demographic group.
PyEI brings together a variety of ecological inference methods in one place and facilitates reporting and plotting results; quantifying the uncertainty associated with results under a given model; making comparisons between methods; and bringing relevant diagnostic tools to bear on ecological inference methods.
PyEI is relatively new and under active development, so expect rough edges and bugs -- and for additional features and documentation to be coming quickly!
## Want to use PyEI? Start here.
### Installation
You can install the latest release from `PyPi` with:
```
pip install pyei
```
Or, install directly from GitHub for the most up-to-date (but potentially less stable) version:
```
pip install git+https://github.com/mggg/ecological-inference.git
```
If you would like to explore PyEI without installation, you can explore this [interactive Colab notebook](https://colab.research.google.com/drive/1Vr1kKAAHgdcUhPrpFsYc1Kz31nbcpZjP#scrollTo=_ASEm5L3UUAS) (just note that inference might be slow!)
### Example notebooks
Check out the [intro notebooks](https://github.com/mggg/ecological-inference/tree/main/pyei/intro_notebooks) and [example notebooks](https://github.com/mggg/ecological-inference/tree/main/pyei/examples) for sample code
that shows how to run and adjust the various models in PyEI on datesets.
If you are new to ecological inference generally, start with [`pyei/intro_notebooks/Introduction_toEI.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/Introduction_to_EI.ipynb).
If you are familiar with ecological inference and want an overview of PyEI and how to use it (with examples), then start with [`intro_notebooks/PyEI_overview.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/PyEI_overview.ipynb).
To explore EI's plotting functionality, check out [`pyei/intro_notebooks/Plotting_with_PyEI.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/Plotting_with_PyEI.ipynb).
For more work with two-by-two examples, see in [`pyei/examples/santa_clara_demo.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/santa_clara_demo.ipynb).
For more work with r-by-c examples, see [`pyei/examples/santa_clara_demo_r_by_c.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/santa_clara_demo_r_by_c.ipynb).
For examples of model comparison and checking steps with PyEI, see [`pyei/examples/model_eval_and_comparison_demo.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/model_eval_and_comparison_demo.ipynb).
### Issues
Feel free to file an issue if you are running into trouble or if there is a feature you'd particularly like to see, and we will do our best to get to it!
## Want to contribute to PyEI? Start here.
Contributions are welcome!
Uses Python 3.10. After cloning the environment, you should be able to use either `virtualenv` or `conda` to run the code. The second (`conda`) is probably easier for development, but `virtualenv` is used for the project's CI.
Here is how to create and activate each environment. See the docs for more elaborate details:
### Install with virtualenv
```bash
virtualenv pyei_venv # create virtualenv
source pyei_venv/bin/activate # activate virtualenv
python -m pip install -U pip # upgrade pip
python -m pip install -e . # install project locally
python -m pip install -r requirements-dev.txt # install dev requirements
```
### Install with conda
```bash
conda create --name pyei --channel conda-forge python=3.10 --file requirements.txt --file requirements-dev.txt # create conda environment and install requirements
conda activate pyei
pip install -e . #install project locally
```
### Testing
After making changes, make sure everything works by running
```bash
./scripts/lint_and_test.sh
```
This will also run automatically when you make a pull request, so if you have trouble getting that to run, just open the PR, and we can help!
## Citation
If you are using PyEI, please cite it as:
Knudson et al., (2021). PyEI: A Python package for ecological inference. Journal of Open Source Software, 6(64), 3397, https://doi.org/10.21105/joss.03397
BibTeX:
```
@article{Knudson2021,
doi = {10.21105/joss.03397},
url = {https://doi.org/10.21105/joss.03397},
year = {2021},
publisher = {The Open Journal},
volume = {6},
number = {64},
pages = {3397},
author = {Karin C. Knudson and Gabe Schoenbach and Amariah Becker},
title = {PyEI: A Python package for ecological inference},
journal = {Journal of Open Source Software}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/mggg/ecological-inference",
"name": "pyei",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Metric Geometry and Gerrymandering Group",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9f/64/f208aca16d81e019a32743ae61938c0312bf0d7d45494cc9c76c285034ec/pyei-1.1.2.tar.gz",
"platform": null,
"description": "# PyEI\n\n[](https://doi.org/10.21105/joss.03397)\n\nPyEI is a Python library for ecological inference. The target audience is the analyst with an interest in the phenomenon called Racially Polarized Voting.\n\nRacially Polarized Voting is a legal concept developed through case law under the Voting Rights Act of 1965; its genesis is in the majority opinion of ***Thornburg v. Gingles (1982)***. Considered the \u201cevidentiary linchpin\u201d for vote dilution cases, RPV is a necessary, but not sufficient, condition that plaintiffs must satisfy for a valid claim. \n\nToward that end, ecological inference uses observed data (historical election results), pairing voting outcomes with demographic information\nfor each precinct in a given polity, to infer voting patterns for each demographic group.\n\nPyEI brings together a variety of ecological inference methods in one place and facilitates reporting and plotting results; quantifying the uncertainty associated with results under a given model; making comparisons between methods; and bringing relevant diagnostic tools to bear on ecological inference methods.\n\nPyEI is relatively new and under active development, so expect rough edges and bugs -- and for additional features and documentation to be coming quickly!\n\n## Want to use PyEI? Start here.\n\n### Installation\nYou can install the latest release from `PyPi` with:\n\n```\npip install pyei\n```\n\nOr, install directly from GitHub for the most up-to-date (but potentially less stable) version:\n\n```\npip install git+https://github.com/mggg/ecological-inference.git\n ```\n \nIf you would like to explore PyEI without installation, you can explore this [interactive Colab notebook](https://colab.research.google.com/drive/1Vr1kKAAHgdcUhPrpFsYc1Kz31nbcpZjP#scrollTo=_ASEm5L3UUAS) (just note that inference might be slow!)\n\n\n### Example notebooks\n\nCheck out the [intro notebooks](https://github.com/mggg/ecological-inference/tree/main/pyei/intro_notebooks) and [example notebooks](https://github.com/mggg/ecological-inference/tree/main/pyei/examples) for sample code\nthat shows how to run and adjust the various models in PyEI on datesets. \n\nIf you are new to ecological inference generally, start with [`pyei/intro_notebooks/Introduction_toEI.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/Introduction_to_EI.ipynb).\n\nIf you are familiar with ecological inference and want an overview of PyEI and how to use it (with examples), then start with [`intro_notebooks/PyEI_overview.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/PyEI_overview.ipynb).\n\nTo explore EI's plotting functionality, check out [`pyei/intro_notebooks/Plotting_with_PyEI.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/intro_notebooks/Plotting_with_PyEI.ipynb).\n\nFor more work with two-by-two examples, see in [`pyei/examples/santa_clara_demo.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/santa_clara_demo.ipynb).\n\nFor more work with r-by-c examples, see [`pyei/examples/santa_clara_demo_r_by_c.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/santa_clara_demo_r_by_c.ipynb).\n\nFor examples of model comparison and checking steps with PyEI, see [`pyei/examples/model_eval_and_comparison_demo.ipynb`](https://github.com/mggg/ecological-inference/blob/main/pyei/examples/model_eval_and_comparison_demo.ipynb).\n\n### Issues\n\nFeel free to file an issue if you are running into trouble or if there is a feature you'd particularly like to see, and we will do our best to get to it!\n\n\n## Want to contribute to PyEI? Start here.\n\nContributions are welcome! \n\nUses Python 3.10. After cloning the environment, you should be able to use either `virtualenv` or `conda` to run the code. The second (`conda`) is probably easier for development, but `virtualenv` is used for the project's CI.\n\nHere is how to create and activate each environment. See the docs for more elaborate details:\n\n### Install with virtualenv\n\n```bash\nvirtualenv pyei_venv # create virtualenv\nsource pyei_venv/bin/activate # activate virtualenv\npython -m pip install -U pip # upgrade pip\npython -m pip install -e . # install project locally\npython -m pip install -r requirements-dev.txt # install dev requirements\n```\n\n### Install with conda\n\n```bash\nconda create --name pyei --channel conda-forge python=3.10 --file requirements.txt --file requirements-dev.txt # create conda environment and install requirements\nconda activate pyei\npip install -e . #install project locally\n```\n\n### Testing\n\nAfter making changes, make sure everything works by running\n\n```bash\n./scripts/lint_and_test.sh\n```\n\nThis will also run automatically when you make a pull request, so if you have trouble getting that to run, just open the PR, and we can help!\n\n\n## Citation\n\nIf you are using PyEI, please cite it as: \n\nKnudson et al., (2021). PyEI: A Python package for ecological inference. Journal of Open Source Software, 6(64), 3397, https://doi.org/10.21105/joss.03397\n\nBibTeX:\n\n```\n@article{Knudson2021,\n doi = {10.21105/joss.03397},\n url = {https://doi.org/10.21105/joss.03397},\n year = {2021},\n publisher = {The Open Journal},\n volume = {6},\n number = {64},\n pages = {3397},\n author = {Karin C. Knudson and Gabe Schoenbach and Amariah Becker},\n title = {PyEI: A Python package for ecological inference},\n journal = {Journal of Open Source Software}\n}\n```\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/mggg/ecological-inference"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6a8c13fbec9ac9594d0d60c0fec24c41a8610e0e2b803f4e37d3f2c1f83440b5",
"md5": "050f194f7c25aab23699a4a68af161af",
"sha256": "ad50a48cc388318bf772652648384d0f40a9e99a0ca20d2c2f40be13b07dd189"
},
"downloads": -1,
"filename": "pyei-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "050f194f7c25aab23699a4a68af161af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 43058,
"upload_time": "2024-12-11T02:16:44",
"upload_time_iso_8601": "2024-12-11T02:16:44.922085Z",
"url": "https://files.pythonhosted.org/packages/6a/8c/13fbec9ac9594d0d60c0fec24c41a8610e0e2b803f4e37d3f2c1f83440b5/pyei-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f64f208aca16d81e019a32743ae61938c0312bf0d7d45494cc9c76c285034ec",
"md5": "7231f03a7f1b545cf4ea14e3abe5bbcd",
"sha256": "e516f871acbbc0f1073eab9af00bdce11e75f8d5932a8e5ff22df71cbe79f92c"
},
"downloads": -1,
"filename": "pyei-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7231f03a7f1b545cf4ea14e3abe5bbcd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 47941,
"upload_time": "2024-12-11T02:16:47",
"upload_time_iso_8601": "2024-12-11T02:16:47.265444Z",
"url": "https://files.pythonhosted.org/packages/9f/64/f208aca16d81e019a32743ae61938c0312bf0d7d45494cc9c76c285034ec/pyei-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 02:16:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mggg",
"github_project": "ecological-inference",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pymc",
"specs": [
[
">=",
"5.18.0"
]
]
},
{
"name": "arviz",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "seaborn",
"specs": []
},
{
"name": "graphviz",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "jax",
"specs": []
},
{
"name": "numpyro",
"specs": []
},
{
"name": "jaxlib",
"specs": []
},
{
"name": "numba",
"specs": []
},
{
"name": "netCDF4",
"specs": []
}
],
"lcname": "pyei"
}
JSON
