GerryChain

GerryChain is a library for using Markov Chain Monte Carlo methods to study the problem of political redistricting. Development of the library began during the 2018 Voting Rights Data Institute (VRDI).

The project is in active development in the mggg/GerryChain GitHub repository, where bug reports and feature requests, as well as contributions, are welcome.

Installation

Supported Python Versions

The most recent version of GerryChain (as of April 2024) supports

• Python 3.11

• Python 3.12

• Python 3.13

If you do not have one of these versions installed on you machine, we recommend that you go to the Python website and download the installer for one of these versions.

Most users can install GerryChain using pip:

pip install gerrychain

For more detailed installation instructions, including instructions for setting up virtual environments, please see the following section: Installation.

User Guide

• Overview of the Chain
  • Parts of the chain
• Installation
  • Supported Python Versions
  • Setting Up a Virtual Environment
  • Making an Environment Reproducible
• Getting started with GerryChain
  • What you’ll need
  • Creating the initial partition
  • Running a chain
  • Next steps
• Running a chain with ReCom
  • A Simple Recom Chain
  • Region-Aware ReCom
  • What to do if the Chain Gets Stuck
  • A Real-World Example
• Working with Partitions
  • Creating a partition
  • partition.graph: the underlying graph
  • partition.assignment: assign nodes to parts
  • partition.parts: the nodes in each part
  • partition.subgraphs: the subgraphs of each part
  • Outputs of updaters
• Updaters
  • Useful updater functions in GerryChain
  • Writing your own updater function
• Good Data Practices
  • Writing Data to JSONL
  • Pandas DataFrames
• Working With Geometries
  • Loading and Running a Plan
• Optimization Methods of GerryChain
  • Using SingleMetricOptimizer
  • Using Gingleator
• Advanced Example: Optimizing Using Geographic Quantities
  • Getting the Data
  • Preparing the Data
  • Using SingleMetricOptimizer

We also highly recommend the resources prepared by Daryl R. DeFord of MGGG for the 2019 MIT IAP course Computational Approaches for Political Redistricting.

API Reference

• API Reference
  • Adjacency graphs
  • Partitions
  • Markov chains
  • Proposals
  • Binary constraints
  • Updaters
  • Elections
  • Grids
  • Spanning tree methods
  • Metrics
  • Diversity stats

Topics

• Reproducibility
• Evaluating districting plans in the real world
• Contributing to GerryChain
• Reporting Issues

Index

• Full Package Reference
  • Accept
  • Chain
  • Constraints
  • Graph
  • Grid
  • Meta
  • Metagraph
  • Metrics
  • Optimization
  • Partition
  • Proposals
  • Tree
  • Updaters