PyEI is a Python library for inferential techniques related to group voting behavior. The target audience is the analyst who seeks to identify and measure Racially Polarized Voting (RPV).
Here, RPV refers specifically to the legal concept developed through case law around the Voting Rights Act of 1965, especially following the landmark Supreme Court case Thornburg v. Gingles (1982). Considered the “evidentiary linchpin” for vote dilution cases, demonstrating meaningful levels of polarization is a necessary, but not sufficient, condition that plaintiffs must satisfy to advance a VRA claim.
Toward that end, inference methods use observed data (historical election results), pairing voting outcomes with demographic information for the precincts in a given jurisdiction, to infer voting patterns by demographic group.
PyEI brings together a variety of 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 under active development, so expect rough edges -- bug reports and feature requests are welcome.
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 (just note that inference might be slow!)
Check out the intro notebooks and example notebooks 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.
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.
To explore EI's plotting functionality, check out pyei/intro_notebooks/Plotting_with_PyEI.ipynb.
For more work with two-by-two examples, see in pyei/examples/santa_clara_demo.ipynb.
For more work with r-by-c examples, see 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.
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!
Contributions are welcome!
Uses Python 3.10. After cloning the repository, you should be able to use either virtualenv or conda to set up your environment. 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:
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 requirementsconda 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 locallyAfter making changes, make sure everything works by running
./scripts/lint_and_test.shThis 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!
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}
}