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

Using conda (recommended)

To install GerryChain from conda-forge using conda, run

conda install -c conda-forge gerrychain

For this command to work as intended, you will first need to activate the conda environment that you want to install GerryChain in. If the environment you want to activate is called vrdi (for example), then you can do this by running

conda activate vrdi

If this command causes problems, make sure conda is up-to-date by running

conda update -n base conda
conda init

For more information on using conda to install packages and manage dependencies, see Getting started with conda.

Using pip

To install GerryChain from PyPI, run pip install gerrychain from the command line.

This approach often fails due to compatibility issues between our different Python GIS dependencies, like geopandas, pyproj, fiona, and shapely. For this reason, we recommend installing from conda-forge for most users.

User Guide

• Installation
  • Using conda (recommended)
  • Using pip
• Getting started with GerryChain
  • What you’ll need
  • Creating the initial partition
  • Running a chain
  • Next steps
• Running a chain with ReCom
  • Imports
  • Setting up the initial districting plan
  • Setting up the Markov chain
  • Running the chain
  • Create a plot
• 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
• What to do about islands and connectivity
  • Figuring out what is going on
  • Strategy 1: delete the problem components
  • Strategy 2: connect the components manually
  • Discontiguous plans
• Using maup to use a real-life plan in GerryChain
  • Downloading a plan
  • Getting the assignment
  • Creating a Partition with the real-life assignment

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

Topics

• Reproducibility
  • Share your code on GitHub
  • Use the same versions of all of your dependencies
  • Import random from gerrychain.random
  • Set PYTHONHASHSEED=0