rdapy

Redistricting Analytics in Python

This repository (rdapy) re-implements the main analytics used in Dave's Redistricting (DRA). Unlike the analytics used in the app (dra-analytics) which are implememented in TypeScript, these are implemented as a Python package to make them easier to use outside of DRA. There is also a command-line interface for high-volume scoring.

These are described in detail at the website for this repository.

To use it in your Python, install the package. To use the high-volume scoring scripts, set up the command-line interface.

Installing the Package

To install the package:

pip install rdapy

The latest version of the package is 3.2.0.

Then in your code, either import rdapy or from rdapy import ....

Installing Command-Line Interface

Before installing the command-line interface (CLI), make sure you have the prerequisites installed.

Install Prequisites

The high-volume scoring scripts require Python 3.12 or later. If that is not the default on your computer, you can use pyenv to manage multiple Python versions. These instructions assume you're using pyenv.

Install pyenv from Homebrew:

brew install pyenv

Completing that setup will involve adding a few lines to your shell profile file (like .bash_profile).

You can install Python 3.12 from Homebrew:

brew install python@3.12

Setting Up Your Environment

With the prequisites installed, clone the GitHub repository:

git clone https://github.com/dra2020/rdapy
cd rdapy

Then create a virtual environment that uses Python 3.12, and then reset Python outside the virtual environment to the normal setting:

pyenv shell 3.12
python3 -m venv /path/to/venvs/rdapy
source /path/to/venvs/rdapy/bin/activate
deactivate
pyenv shell --unset

Then activate the virtual environment again, and install the required dependencies:

source /path/to/venvs/rdapy/bin/activate
pip install -r requirements.txt
pip install --upgrade pip
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Finally, test that the automated tests run:

pytest

Then score some sample plans. On a Mac or Linux, use this bash script:

scripts/score/SCORE.sh \
--state NC \
--plan-type congress \
--geojson /dir/for/unzipped/files/NC_2020_VD_tabblock.vtd.datasets.geojson \
--graph /dir/for/unzipped/files/NC_2020_graph.json \
--precomputed testdata/examples/NC_congress_precomputed.json \
--plans testdata/plans/NC_congress_plans.tagged.jsonl \
--scores /path/to/TEST_scores.csv \
--by-district /path/to/TEST_by-district.jsonl

The --scores and by-district paths are where you want the scores CSV and by-district JSONL aggregates files to be saved, respectively.

Alternatively or on Windows, use this Python version of the script:

scripts/score/SCORE-PYTHON.py \
--state NC \
--plan-type congress \
--geojson /dir/for/unzipped/files/NC_2020_VD_tabblock.vtd.datasets.geojson \
--graph /dir/for/unzipped/files/NC_2020_graph.json \
--precomputed testdata/examples/NC_congress_precomputed.json \
--plans testdata/plans/NC_congress_plans.tagged.jsonl \
--scores /path/to/TEST_scores.csv \
--by-district /path/to/TEST_by-district.jsonl

It has the same arguments as the bash script, and will produce the same output files, but it is implemented in Python and can be run on Windows.

Development

There is a sample launch.json for VS Code debugging in the docs directory.

Testing

Run automated tests with:

pytest

Questions

Email questions to feedback.