Package: gerrychain
GerryChain is a Python library for building ensembles of districting plans
usingMarkov chain Monte Carlo. It is developed and maintained by theMetric Geometry and Gerrymandering Groupand our network of volunteers.
It is distributed under the3-Clause BSD License.The basic workflow is to start with the geometry of an initial plan and
generate a large collection of sample plans for comparison. Usually, we
will constrain these sampled plans in such a way that they perform at
least as well as the initial plan according to traditional districting
principles, such as population balance or compactness. Comparing the
initial plan to the ensemble provides quantitative tools for measuring
whether or not it is an outlier among the sampled plans.Getting startedSee ourGetting started guidefor the basics of using GerryChain.We also highly recommend the resources prepared by Daryl R. DeFord of MGGG
for the 2019 MIT IAP courseComputational Approaches for Political Redistricting.Useful linksDocumentationBug reports and feature requestsContributions welcome!InstallationSupported Python VersionsThe most recent version of GerryChain (as of February 2024) supportsPython 3.9Python 3.10Python 3.11If you do not have one of these versions installed on you machine, we
recommend that you go to thePython websiteand
download the installer for one of these versions.[1]A Note for Windows UsersIf you are using Windows and are new to Python, we recommend that you
still install Python using the installation package available on
the Python website. There are several versions of Python available
on the Windows Store, but they can be… finicky, and experience seems
to suggest that downloadable available on the Python website produce
better results.In addition, we recommend that you install theWindows Terminalfrom the Microsoft Store. It is still possible to use PowerShell or
the Command Prompt, but Windows Terminal tends to be more beginner
friendly and allows for a greater range of utility than the natively
installed terminal options (for example, it allows for you to install
the more recent version of PowerShell,PowerShell 7,
and for the use of the Linux Subsystem for Windows).Setting Up a Virtual EnvironmentOnce Python is installed on your system, you will want to open the terminal
and navigate to the working directory of your project. Here are some brief
instructions for doing so on different systems:MacOS: To open the terminal, you will likely want to use the
Spotlight Search (the magnifying glass in the top right corner of
your screen) to find the “Terminal” application (you can also access
Spotlight Search by pressing “Command (⌘) + Space”). Once you have
the terminal open, typecdfollowed by the path to your working
directory. For example, if you are working on a project calledmy_projectin yourDocumentsfolder, you may access by typing
the commandcd ~/Documents/my_projectinto the terminal (here the~is a shortcut for your home directory).
If you do not know what your working directory is, you can find it by
navigating to the desired folder in your file explorer, and clicking
on “Get Info”. The path will be labeled “Where” and from there you
can copy the path to your clipboard and paste it in the terminal.Linux: Most Linux distributions have the keyboard shortcutCtrl + Alt + Tset to open the terminal. From there you may navigate
to your working directory by typingcdfollowed by the path to your
working directory. For example, if you are working on a project calledmy_projectin yourDocumentsfolder, you may access this via
the commandcd ~/Documents/my_project(here the~is a shortcut for your home directory). If you do not
know what your working directory is, you can find it by navigating to
the desired folder in your file explorer, and clicking on “Properties”.
The path will be labeled “Location” and from there you can copy the path
to your clipboard and paste it in the terminal (to paste in the terminal
in Linux, you will need to use the keyboard shortcutCtrl + Shift + Vinstead ofCtrl + V).Windows: Open the Windows Terminal and typecdfollowed by the
path to your working directory. For example, if you are working on a
project calledmy_projectin yourDocumentsfolder, you may
access this by typing the commandcd ~\Documents\my_projectinto the terminal (here the~is a shortcut for your home directory).
If you do not know what your working directory is,
you can find it by navigating to the desired folder in your file
explorer, and clicking on “Properties”. The path will be labeled
“Location” and from there you can copy the path to your clipboard
and paste it in the terminal.Once you have navigated to your working directory, you will want to
set up a virtual environment. This is a way of isolating the Python
packages you install for this project from the packages you have
installed globally on your system. This is useful because it allows
you to install different versions of packages for different projects
without worrying about compatibility issues. To set up a virtual
environment, type the following command into the terminal:python -m venv .venvThis will create a virtual environment in your working directory which
you can see if you list all the files in your working directory via
the commandls-a(diron Windows). Now we need to activate the
virtual environment. To do this, type the following command into the
terminal:Windows:.venv\Scripts\activateMacOS/Linux:source .venv/bin/activateYou should now see(.venv)at the beginning of your terminal prompt
now. This indicates that you are in the virtual environment, and are now
ready to install GerryChain.To install GerryChain fromPyPI, runpip install gerrychainfrom
the command line.If you plan on using GerryChain’s GIS functions, such as computing
adjacencies or reading in shapefiles, then runpip install gerrychain[geo]from the command line.This approach sometimes fails due to compatibility issues between our
different Python GIS dependencies, likegeopandas,pyproj,fiona, andshapely. If you run into this issue, try installing
the dependencies using thegeo_settings.txtfile. To do this, runpip install-rgeo_settings.txtfrom the
command line.NoteIf you plan on following through the tutorials present within the
remainder of this documentation, you will also need to installmatplotlibfromPyPI. This can also be accomplished with
a simple invocation ofpip install matplotlibfrom the command
line.[1]Of course, if you are using a Linux system, you will either need to use your
system’s package manager or install from source. You may also find luck installing
Python directly from the package manager if you find installing from source to be
troublesome.Making an Environment ReproducibleIf you are working on a project wherein you would like to ensure
particular runs are reproducible, it is necessary to invokeMacOS/Linux:export PYTHONHASHSEED=0Windows:PowerShell$env:PYTHONHASHSEED=0Command Promptset PYTHONHASHSEED=0before running your code. This will ensure that the hash seed is deterministic
which is important for the replication of spanning trees across your runs. If you
would prefer to not have to do this every time, then you need to modify the
activation script for the virtual environment. Again, this is different depending
on your operating system:MacOS/Linux: Open the file.venv/bin/activatelocated in your working
directory using your favorite text editor
and add the lineexport PYTHONHASHSEED=0after theexport PATHcommand.
So you should see something like:_OLD_VIRTUAL_PATH="$PATH"
PATH="$VIRTUAL_ENV/Scripts:$PATH"
export PATH

export PYTHONHASHSEED=0Then, verify that the hash seed is set to 0 in your Python environment by
runningpythonfrom the command line and typingimport os;print(os.environ['PYTHONHASHSEED']).Windows: To be safe, you will need to modify 3 files within your virtual
environment:.venv\Scripts\activate: Add the lineexport PYTHONHASHSEED=0after
theexport PATHcommand. So you should see something like:_OLD_VIRTUAL_PATH="$PATH"
PATH="$VIRTUAL_ENV/Scripts:$PATH"
export PATH

export PYTHONHASHSEED=0.venv\Scripts\activate.bat: Add the lineset PYTHONHASHSEED=0to the
end of the file. So you should see something like:if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH%
if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH%

set PATH=%VIRTUAL_ENV%\Scripts;%PATH%
rem set VIRTUAL_ENV_PROMPT=(.venv)
set PYTHONHASHSEED=0.venv\Scripts\Activate.ps1: Add the line$env:PYTHONHASHSEED=0to the
end of the before the signature block. So you should see something like:# Add the venv to the PATH
Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH
$Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH"

$env:PYTHONHASHSEED=0

# SIG # Begin signature blockAfter you have made these changes, verify that the hash seed is set to 0 in your
Python environment by runningpythonfrom the command line and typingimport os;print(os.environ['PYTHONHASHSEED'])in the Python prompt.A Note on JupyterIf you are using a jupyter notebook, you will need to make sure that you have
installed theipykernelpackage in your virtual environment as well as
eitherjypyternotebookorjupyterlab. To install these packages, runpip install<package-name>from the command line. Then, to use the virtual
python environment in your jupyter notebook, you need to invokejupyter notebookorjupyter labfrom the command line of your working directorywhile your virtual environment
is activated. This will open a jupyter notebook in your default browser. You may
then check that the hash seed is set to 0 by running the following code in a cell
of your notebook:importosprint(os.environ['PYTHONHASHSEED'])