Skip to main content

Tools for processing and visualizing districting plans.

Project description

gerrytools

CircleCI codecov PyPI version docs website Code style: black Imports: isort

A companion to GerryChain, GerryTools is a robust suite of geometric and algorithmic tools to analyze districting plans and related data. GerryTools is actively developed and used by the MGGG Redistricting Lab and our collaborators to prepare accurate, precise, and clean information for our projects. It is distributed under a 3-Clause BSD License.

Installation

Using pip (recommended)

To install GerryTools from PyPi, run

pip install gerrytools

from the command line. if you would like to use the mgrp and ben modules as well, you can invoke

pip install gerrytools[mgrp]

you will need to make sure that Docker Desktop is installed on your machine an updated to version >= 4.28.0. For more information on getting this set up, please see our documentation page

Usage

GerryTools is split up into multiple sub-packages, each designed to simplify and standardize redistricting workflows.

  • gerrytools.ben BEN (binary-ensemble) is our general purpose compression algorithm for working with ensembles of plans. In general, the ben algorithm can improve the storage of an ensemble of plans by an order of magnitude. When combined with the special XBEN (eXtreme BEN) portion of the algorithm, many ensembles of plans can be compressed small enough to fit into an email (~25Mb).

  • gerrytools.data deals with the retrieval and processing of data. Here, you can find tools for grabbing decennial Census ('10 and '20), ACS 5-year ('12-'20), ACS CVAP Special Tab ('12-'20), districtr portal, and 2020 decennial Census geometric data. You can also find tools for moving CVAP data to other levels of geometry (e.g. prorating 2019 CVAP on 2019 Census tracts to 2020 blocks).

  • gerrytools.geometry provides facilities for dealing with geometric and related data. There are tools for translating and evaluating GerryChain Partitions, performing fast geometric dissolutions, creating unit maps (e.g. 2020 blocks to 2020 VTDs), creating dual graphs for GerryChain, and optimization algorithms for renaming districts.

  • gerrytools.mgrp this module uses a Docker container to allow users to access several ensemble methods for generating districting plans on a state. In particular our Rust implementation of our gerrychain library, frcw, the Julia implementation of Forest Recom, and the R/C++ implementation of Sequential Monte Carlo (SMC) are available through this module.

  • gerrytools.plotting contains methods for generating extremely high-quality Lab-standard data visualizations.

  • gerrytools.scoring provides a vast array of redistricting plan scores. These can be used standalone or as GerryChain updaters.

  • gerrychain.utilities has ease-of-use methods for renaming directories containing shapefiles (which comes in handy more often than you'd think) and making JSON objects out of Python objects (useful when trying to organize information for many districting plans in a standard format).

Contributing

GerryTools is an active project, and has multiple contributors. If you'd like to contribute, here are a few house rules:

  1. After cloning this repository, run sh setup.sh to download and install necessary git hooks and linting configurations.

  2. Follow the PEP8 style guide. After installing the above git hooks, linting is performed before every push. PEP8 errors can be automatically corrected by running autopep8 --in-place --aggressive -r gerrytools on the command line from the root directory.

  3. Write tests. All changes, major or minor, must be accompanied by testing code. Code and tests will be immediately reviewed by Lab maintainers.

  4. Test coverage must stay at least the same; this can be checked by running pytest --cov=evaltools after the tests are added to tests/.

  5. Write documentation. All changes should be documented via docstrings, and code should be repletely commented. It's much easier to decipher commented code! Docstring documentation is compiled on every commit via git hooks.

We look forward to your contributions!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gerrytools-1.2.0.tar.gz (87.2 kB view details)

Uploaded Source

Built Distribution

gerrytools-1.2.0-py3-none-any.whl (107.3 kB view details)

Uploaded Python 3

File details

Details for the file gerrytools-1.2.0.tar.gz.

File metadata

  • Download URL: gerrytools-1.2.0.tar.gz
  • Upload date:
  • Size: 87.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.8

File hashes

Hashes for gerrytools-1.2.0.tar.gz
Algorithm Hash digest
SHA256 f3403fb5af246485c0023ff7d5b5c1386614b4aebf62ef71d141ffccee900b6b
MD5 6a4abb1ca77e28e14663fb9686d361c8
BLAKE2b-256 b693a01af7c3361a29c946c739a4a9a46d21c8bec4e6413101a06b6900376f15

See more details on using hashes here.

File details

Details for the file gerrytools-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: gerrytools-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 107.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.8

File hashes

Hashes for gerrytools-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8000dabbfe6e347d8d0029184696ecf36dac1f481c3f9c77931e5d86ce2f50db
MD5 d4db70cb0935c72f9de142cfd3dbd3de
BLAKE2b-256 fb99fb4c65855e6e6a02625d367014e8fbf54b935c60c7bbf3750f9b6a60c986

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page