API Reference¶
Table of Contents
Adjacency graphs¶

class
gerrychain.
Graph
(incoming_graph_data=None, **attr)[source]¶ Represents a graph to be partitioned. It is based on
networkx.Graph
.We have added some classmethods to help construct graphs from shapefiles, and to save and load graphs as JSON files.
Initialize a graph with edges, name, or graph attributes.
 incoming_graph_data : input graph (optional, default: None)
 Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a NumPy matrix or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
 attr : keyword arguments, optional (default= no attributes)
 Attributes to add to graph as key=value pairs.
convert
>>> G = nx.Graph() # or DiGraph, MultiGraph, MultiDiGraph, etc >>> G = nx.Graph(name='my graph') >>> e = [(1, 2), (2, 3), (3, 4)] # list of edges >>> G = nx.Graph(e)
Arbitrary graph attribute pairs (key=value) may be assigned
>>> G = nx.Graph(e, day="Friday") >>> G.graph {'day': 'Friday'}

add_data
(df, columns=None)[source]¶ Add columns of a DataFrame to a graph as node attributes using by matching the DataFrame’s index to node ids.
Parameters:  df – Dataframe containing given columns.
 columns – (optional) List of dataframe column names to add.

classmethod
from_file
(filename, adjacency='rook', cols_to_add=None, reproject=False, ignore_errors=False)[source]¶ Create a
Graph
from a shapefile (or GeoPackage, or GeoJSON, or any other library thatgeopandas
can read. Seefrom_geodataframe()
for more details.Parameters: cols_to_add – (optional) The names of the columns that you want to add to the graph as node attributes. By default, all columns are added.

classmethod
from_geodataframe
(dataframe, adjacency='rook', cols_to_add=None, reproject=False, ignore_errors=False)[source]¶ Creates the adjacency
Graph
of geometries described by dataframe. The areas of the polygons are included as node attributes (with key area). The shared perimeter of neighboring polygons are included as edge attributes (with key shared_perim). Nodes corresponding to polygons on the boundary of the union of all the geometries (e.g., the state, if your dataframe describes VTDs) have a boundary_node attribute (set to True) and a boundary_perim attribute with the length of this “exterior” boundary.By default, areas and lengths are computed in a UTM projection suitable for the geometries. This prevents the bizarro area and perimeter values that show up when you accidentally do computations in LongitudeLatitude coordinates. If the user specifies reproject=False, then the areas and lengths will be computed in the GeoDataFrame’s current coordinate reference system. This option is for users who have a preferred CRS they would like to use.
Parameters:  dataframe –
geopandas.GeoDataFrame
 adjacency – (optional) The adjacency type to use (“rook” or “queen”). Default is “rook”
 cols_to_add – (optional) The names of the columns that you want to add to the graph as node attributes. By default, all columns are added.
 reproject – (optional) Whether to reproject to a UTM projection before
creating the graph. Default is
True
.  ignore_errors – (optional) Whether to ignore all invalid geometries and
attept to create the graph anyway. Default is
False
.
Returns: The adjacency graph of the geometries from dataframe.
Return type:  dataframe –

classmethod
from_json
(json_file)[source]¶ Load a graph from a JSON file in the NetworkX json_graph format. :param json_file: Path to JSON file. :return: Graph

islands
¶ The set of degree0 nodes.

join
(dataframe, columns=None, left_index=None, right_index=None)[source]¶ Add data from a dataframe to the graph, matching nodes to rows when the node’s left_index attribute equals the row’s right_index value.
Parameters: dataframe – DataFrame. Columns: (optional) The columns whose data you wish to add to the graph. If not provided, all columns are added. Left_index: (optional) The node attribute used to match nodes to rows. If not provided, node IDs are used. Right_index: (optional) The DataFrame column name to use to match rows to nodes. If not provided, the DataFrame’s index is used.

to_json
(json_file, *, include_geometries_as_geojson=False)[source]¶ Save a graph to a JSON file in the NetworkX json_graph format.
Parameters:  json_file – Path to target JSON file.
 include_geometry_as_geojson (bool) – (optional) Whether to include
any
shapely
geometry objects encountered in the graph’s node attributes as GeoJSON. The default (False
) behavior is to remove all geometry objects because they are not serializable. Including the GeoJSON will result in a much larger JSON file.
Partitions¶

class
gerrychain.partition.
Partition
(graph=None, assignment=None, updaters=None, parent=None, flips=None)[source]¶ Bases:
object
Partition represents a partition of the nodes of the graph. It will perform the first layer of computations at each step in the Markov chain  basic aggregations and calculations that we want to optimize.
Variables:  graph (gerrychain.Graph) – The underlying graph.
 assignment (gerrychain.Assignment) – Maps node IDs to district IDs.
 parts (dict) – Maps district IDs to the set of nodes in that district.
 subgraphs (dict) – Maps district IDs to the induced subgraph of that district.
Parameters:  graph – Underlying graph.
 assignment – Dictionary assigning nodes to districts.
 updaters – Dictionary of functions to track data about the partition. The keys are stored as attributes on the partition class, which the functions compute.

crosses_parts
(edge)[source]¶ Answers the question “Does this edge cross from one part of the partition to another?
Parameters: edge – tuple of node IDs Return type: bool

flip
(flips)[source]¶ Returns the new partition obtained by performing the given flips on this partition.
Parameters: flips – dictionary assigning nodes of the graph to their new districts Returns: the new Partition
Return type: Partition

classmethod
from_districtr_file
(graph, districtr_file, updaters=None)[source]¶ Create a Partition from a districting plan created with Districtr, a free and opensource web app created by MGGG for drawing districts.
The provided
graph
should be created from the same shapefile as the Districtr module used to draw the districting plan. These shapefiles may be found in a repository in the mgggstates GitHub organization, or by request from MGGG.Parameters:  graph –
Graph
 districtr_file – the path to the
.json
file exported from Districtr  updaters – dictionary of updaters
 graph –

plot
(geometries=None, **kwargs)[source]¶ Plot the partition, using the provided geometries.
Parameters:  geometries – A
geopandas.GeoDataFrame
orgeopandas.GeoSeries
holding the geometries to use for plotting. ItsIndex
should match the node labels of the partition’s underlyingGraph
.  **kwargs – Additional arguments to pass to
geopandas.GeoDataFrame.plot()
to adjust the plot.
 geometries – A

class
gerrychain.partition.
GeographicPartition
(graph=None, assignment=None, updaters=None, parent=None, flips=None)[source]¶ Bases:
gerrychain.partition.partition.Partition
A
Partition
with areas, perimeters, and boundary information included. These additional data allow you to compute compactness scores like PolsbyPopper.Parameters:  graph – Underlying graph.
 assignment – Dictionary assigning nodes to districts.
 updaters – Dictionary of functions to track data about the partition. The keys are stored as attributes on the partition class, which the functions compute.
Markov chains¶

class
gerrychain.
MarkovChain
(proposal, constraints, accept, initial_state, total_steps)[source]¶ MarkovChain is an iterator that allows the user to iterate over the states of a Markov chain run.
Example usage:
chain = MarkovChain(proposal, constraints, accept, initial_state, total_steps) for state in chain: # Do whatever you want  print output, compute scores, ...
Parameters:  proposal – Function proposing the next state from the current state.
 constraints – A function with signature
Partition > bool
determining whether the proposed next state is valid (passes all binary constraints). Usually this is aValidator
class instance.  accept – Function accepting or rejecting the proposed state. In the most basic
use case, this always returns
True
. But if the user wanted to use a MetropolisHastings acceptance rule, this is where you would implement it.  initial_state – Initial
gerrychain.partition.Partition
class.  total_steps – Number of steps to run.
Proposals¶

gerrychain.proposals.
recom
(partition, pop_col, pop_target, epsilon, node_repeats=1, method=<function bipartition_tree>)[source]¶ ReCom proposal.
Description from MGGG’s 2018 Virginia House of Delegates report: At each step, we (uniformly) randomly select a pair of adjacent districts and merge all of their blocks in to a single unit. Then, we generate a spanning tree for the blocks of the merged unit with the Kruskal/Karger algorithm. Finally, we cut an edge of the tree at random, checking that this separates the region into two new districts that are population balanced.
Example usage:
from functools import partial from gerrychain import MarkovChain from gerrychain.proposals import recom # ...define constraints, accept, partition, total_steps here... # Ideal population: pop_target = sum(partition["population"].values()) / len(partition) proposal = partial( recom, pop_col="POP10", pop_target=pop_target, epsilon=.05, node_repeats=10 ) chain = MarkovChain(proposal, constraints, accept, partition, total_steps)

gerrychain.proposals.
spectral_recom
(partition, weight_type=None, lap_type='normalized')[source]¶ Spectral ReCom proposal.
Uses spectral clustering to bipartition a subgraph of the original graph formed by merging the nodes corresponding to two adjacent districts.
Example usage:
from functools import partial from gerrychain import MarkovChain from gerrychain.proposals import recom # ...define constraints, accept, partition, total_steps here... proposal = partial( spectral_recom, weight_type=None, lap_type="normalized" ) chain = MarkovChain(proposal, constraints, accept, partition, total_steps)
Binary constraints¶
The gerrychain.constraints
module provides a collection of constraint
functions and helper classes for the validation step in GerryChain.
Helper classes  

Validator 
Collection of constraints 
Bounds 
Bounds on numeric constraints 
UpperBound 
Upper bounds on numeric constraints 
LowerBound 
Lower bounds on numeric constraints 
SelfConfiguringUpperBound 
Automatic upper bounds on numeric constraints 
SelfConfiguringLowerBound 
Automatic lower bounds on numeric constraints 
WithinPercentRangeOfBounds 
Percentage bounds for numeric constraints 
Binary constraint functions  

no_worse_L1_reciprocal_polsby_popper() 
Lower bounded L1reciprocal PolsbyPopper 
no_worse_L_minus_1_reciprocal_polsby_popper() 
Lower bounded L(1)reciprocal PolsbyPopper 
contiguous() 
Districts are contiguous (with NetworkX methods) 
single_flip_contiguous() 
Districts are contiguous (optimized for propose_random_flip proposal) 
no_vanishing_districts() 
No districts may be completely consumed 
Each new step proposed to the chain is passed off to the “validator” functions here to determine whether or not the step is valid. If it is invalid (breaks contiguity, for instance), then the step is immediately rejected.
A validator should take in a Partition
instance,
and should return whether or not the instance is valid according to their
rules. Many toplevel functions following this signature in this module are
examples of this.

class
gerrychain.constraints.
LowerBound
(func, bound)[source]¶ Wrapper for numericvalidators to enforce lower limits.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set lower limit, andFalse
otherwise.Parameters:  func – Numeric validator function. Should return a comparable value.
 bounds – Comparable lower bound.

class
gerrychain.constraints.
SelfConfiguringLowerBound
(func, epsilon=0.05)[source]¶ Wrapper for numericvalidators to enforce automatic lower limits.
When instantiated, the initial lower bound is set as the initial value of the numericvalidator minus some configurable ε.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set lower limit, andFalse
otherwise.Parameters:  func – Numeric validator function.
 epsilon – Initial “wiggle room” that the validator allows.

class
gerrychain.constraints.
SelfConfiguringUpperBound
(func)[source]¶ Wrapper for numericvalidators to enforce automatic upper limits.
When instantiated, the initial upper bound is set as the initial value of the numericvalidator.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set upper limit, andFalse
otherwise.Parameters: func – Numeric validator function.

class
gerrychain.constraints.
UpperBound
(func, bound)[source]¶ Wrapper for numericvalidators to enforce upper limits.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set upper limit, andFalse
otherwise.Parameters:  func – Numeric validator function. Should return a comparable value.
 bounds – Comparable upper bound.

gerrychain.constraints.
contiguous
(partition)[source]¶ Check if the parts of a partition are connected using
networkx.is_connected()
.Parameters: partition – The proposed next Partition
Returns: whether the partition is contiguous Return type: bool

gerrychain.constraints.
contiguous_bfs
(partition)[source]¶ Checks that a given partition’s parts are connected as graphs using a simple breadthfirst search.
Parameters: partition – Instance of Partition Returns: Whether the parts of this partition are connected Return type: bool

gerrychain.constraints.
single_flip_contiguous
(partition)[source]¶ Check if swapping the given node from its old assignment disconnects the old assignment class.
Parameters: partition – The proposed next Partition
Returns: whether the partition is contiguous Return type: bool We assume that removed_node belonged to an assignment class that formed a connected subgraph. To see if its removal left the subgraph connected, we check that the neighbors of the removed node are still connected through the changed graph.

class
gerrychain.constraints.
Validator
(constraints)[source]¶ A single callable for checking that a partition passes a collection of constraints. Intended to be passed as the
is_valid
parameter when instantiatingMarkovChain
.This class is meant to be called as a function after instantiation; its return is
True
if all validators pass, andFalse
if any one fails.Example usage:
is_valid = Validator([constraint1, constraint2, constraint3]) chain = MarkovChain(proposal, is_valid, accept, initial_state, total_steps)
Parameters: constraints – List of validator functions that will check partitions.

gerrychain.constraints.
districts_within_tolerance
(partition, attribute_name='population', percentage=0.1)[source]¶ Check if all districts are within a certain percentage of the “smallest” district, as defined by the given attribute.
Parameters:  partition – partition class instance
 attrName – string that is the name of an updater in partition
 percentage – what percent difference is allowed
Returns: whether the districts are within specified tolerance
Return type: bool

gerrychain.constraints.
no_vanishing_districts
(partition)[source]¶ Require that no districts be completely consumed.

gerrychain.constraints.
refuse_new_splits
(partition_county_field)[source]¶ Refuse all proposals that split a county that was previous unsplit.
Parameters: partition_county_field – Name of field for county information generated by county_splits()
.

gerrychain.constraints.
within_percent_of_ideal_population
(initial_partition, percent=0.01, pop_key='population')[source]¶ Require that all districts are within a certain percent of “ideal” (i.e., uniform) population.
Ideal population is defined as “total population / number of districts.”
Parameters:  initial_partition – Starting partition from which to compute district information.
 percent – (optional) Allowed percentage deviation. Default is 1%.
 pop_key – (optional) The name of the population
Tally
. Default is"population"
.
Returns: A
Bounds
constraint on the population attribute identified bypop_key
.

class
gerrychain.constraints.
Bounds
(func, bounds)[source]¶ Wrapper for numericvalidators to enforce upper and lower limits.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within set limits, andFalse
otherwise.Parameters:  func – Numeric validator function. Should return an iterable of values.
 bounds – Tuple of (lower, upper) numeric bounds.

class
gerrychain.constraints.
Validator
(constraints)[source] A single callable for checking that a partition passes a collection of constraints. Intended to be passed as the
is_valid
parameter when instantiatingMarkovChain
.This class is meant to be called as a function after instantiation; its return is
True
if all validators pass, andFalse
if any one fails.Example usage:
is_valid = Validator([constraint1, constraint2, constraint3]) chain = MarkovChain(proposal, is_valid, accept, initial_state, total_steps)
Parameters: constraints – List of validator functions that will check partitions.

class
gerrychain.constraints.
UpperBound
(func, bound)[source] Wrapper for numericvalidators to enforce upper limits.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set upper limit, andFalse
otherwise.Parameters:  func – Numeric validator function. Should return a comparable value.
 bounds – Comparable upper bound.

class
gerrychain.constraints.
LowerBound
(func, bound)[source] Wrapper for numericvalidators to enforce lower limits.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set lower limit, andFalse
otherwise.Parameters:  func – Numeric validator function. Should return a comparable value.
 bounds – Comparable lower bound.

class
gerrychain.constraints.
SelfConfiguringLowerBound
(func, epsilon=0.05)[source] Wrapper for numericvalidators to enforce automatic lower limits.
When instantiated, the initial lower bound is set as the initial value of the numericvalidator minus some configurable ε.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set lower limit, andFalse
otherwise.Parameters:  func – Numeric validator function.
 epsilon – Initial “wiggle room” that the validator allows.

class
gerrychain.constraints.
SelfConfiguringUpperBound
(func)[source] Wrapper for numericvalidators to enforce automatic upper limits.
When instantiated, the initial upper bound is set as the initial value of the numericvalidator.
This class is meant to be called as a function after instantiation; its return is
True
if the numeric validator is within a set upper limit, andFalse
otherwise.Parameters: func – Numeric validator function.
Updaters¶

gerrychain.updaters.
county_splits
(partition_name, county_field_name)[source]¶ Track county splits.
Parameters:  partition_name – Name that the
Partition
instance will store.  county_field_name – Name of county ID field on the graph.
Returns: The tracked data is a dictionary keyed on the county ID. The stored values are tuples of the form (split, nodes, seen). split is a
CountySplit
enum, nodes is a list of node IDs, and seen is a list of assignment IDs that are contained in the county. partition_name – Name that the

class
gerrychain.updaters.
Tally
(fields, alias=None, dtype=<class 'int'>)[source]¶ An updater for keeping a tally of one or more node attributes.
Parameters:  fields – the list of node attributes that you want to tally. Or a just a single attribute name as a string.
 alias – the aliased name of this Tally (meaning, the key corresponding to this Tally in the Partition’s updaters dictionary)
 dtype – the type (int, float, etc.) that you want the tally to have

class
gerrychain.updaters.
DataTally
(data, alias)[source]¶ An updater for tallying numerical data that is not necessarily stored as node attributes
Parameters:  data – a dict or Series indexed by the graph’s nodes, or the string key for a node attribute containing the Tally’s data.
 alias – the name of the tally in the Partition’s updaters dictionary

class
gerrychain.updaters.
Election
(name, parties_to_columns, alias=None)[source]¶ Represents the data of one election, with races conducted in each part of the partition.
As we vary the districting plan, we can use the same nodelevel vote totals to tabulate hypothetical elections. To do this manually with tallies, we would have to maintain tallies for each party, as well as the total number of votes, and then compute the electoral results and percentages from scratch every time. To make this simpler, this class provides an
ElectionUpdater
to manage these tallies. The updater returns anElectionResults
class giving a convenient view of the election results, with methods likewins()
orpercent()
for common queries the user might make on election results.Example usage:
# Assuming your nodes have attributes "2008_D", "2008_R" # with (for example) 2008 senate election vote totals election = Election( "2008 Senate", {"Democratic": "2008_D", "Republican": "2008_R"}, alias="2008_Sen" ) # Assuming you already have a graph and assignment: partition = Partition( graph, assignment, updaters={"2008_Sen": election} ) # The updater returns an ElectionResults instance, which # we can use (for example) to see how many seats a given # party would win in this partition using this election's # vote distribution: partition["2008_Sen"].wins("Republican")
Parameters:  name – The name of the election. (e.g. “2008 Presidential”)
 parties_to_columns – A dictionary matching party names to their data columns, either as actual columns (listlike, indexed by nodes) or as string keys for the node attributes that hold the party’s vote totals. Or, a list of strings which will serve as both the party names and the node attribute keys.
 alias – (optional) Alias that the election is registered under in the Partition’s dictionary of updaters.
Elections¶

class
gerrychain.updaters.election.
Election
(name, parties_to_columns, alias=None)[source]¶ Represents the data of one election, with races conducted in each part of the partition.
As we vary the districting plan, we can use the same nodelevel vote totals to tabulate hypothetical elections. To do this manually with tallies, we would have to maintain tallies for each party, as well as the total number of votes, and then compute the electoral results and percentages from scratch every time. To make this simpler, this class provides an
ElectionUpdater
to manage these tallies. The updater returns anElectionResults
class giving a convenient view of the election results, with methods likewins()
orpercent()
for common queries the user might make on election results.Example usage:
# Assuming your nodes have attributes "2008_D", "2008_R" # with (for example) 2008 senate election vote totals election = Election( "2008 Senate", {"Democratic": "2008_D", "Republican": "2008_R"}, alias="2008_Sen" ) # Assuming you already have a graph and assignment: partition = Partition( graph, assignment, updaters={"2008_Sen": election} ) # The updater returns an ElectionResults instance, which # we can use (for example) to see how many seats a given # party would win in this partition using this election's # vote distribution: partition["2008_Sen"].wins("Republican")
Parameters:  name – The name of the election. (e.g. “2008 Presidential”)
 parties_to_columns – A dictionary matching party names to their data columns, either as actual columns (listlike, indexed by nodes) or as string keys for the node attributes that hold the party’s vote totals. Or, a list of strings which will serve as both the party names and the node attribute keys.
 alias – (optional) Alias that the election is registered under in the Partition’s dictionary of updaters.

class
gerrychain.updaters.election.
ElectionResults
(election, counts, races)[source]¶ Represents the results of an election. Provides helpful methods to answer common questions you might have about an election (Who won? How many seats?, etc.).

count
(party, race=None)[source]¶ Returns the total number of votes that
party
received in a given race (part of the partition). Ifrace
is omitted, returns the overall vote total ofparty
.Parameters:  party – Party ID.
 race – ID of the part of the partition whose votes we want to tally.

counts
(party)[source]¶ Parameters: party – Party ID Returns: tuple of the total votes cast for party
in each part of the partition

percent
(party, race=None)[source]¶ Returns the percentage of the vote that
party
received in a given race (part of the partition). Ifrace
is omitted, returns the overall vote share ofparty
.Parameters:  party – Party ID.
 race – ID of the part of the partition whose votes we want to tally.


class
gerrychain.updaters.election.
ElectionUpdater
(election)[source]¶ The updater for computing the election results in each part of the partition after each step in the Markov chain. The actual results are returned to the user as an
ElectionResults
instance.
Grids¶
To make it easier to play around with GerryChain, we have provided a Grid
class representing a partition of a grid graph. This is especially useful if you want to start experimenting
but do not yet have a clean set of data and geometries to build your graph from.

class
gerrychain.grid.
Grid
(dimensions=None, with_diagonals=False, assignment=None, updaters=None, parent=None, flips=None)[source]¶ The
Grid
class represents a grid partitioned into districts. It is useful for running little experiments with GerryChain without needing to do any data processing or cleaning to get started.Example usage:
grid = Grid((10,10))
The nodes of
grid.graph
are labelled by tuples(i,j)
, for0 <= i <= 10
and0 <= j <= 10
. Each node has anarea
of 1 and each edge hasshared_perim
1.Parameters:  dimensions – tuple (m,n) of the desired dimensions of the grid.
 with_diagonals – (optional, defaults to False) whether to include diagonals as edges of the graph (i.e., whether to use ‘queen’ adjacency rather than ‘rook’ adjacency).
 assignment – (optional) dict matching nodes to their districts. If not provided, partitions the grid into 4 quarters of roughly equal size.
 updaters – (optional) dict matching names of attributes of the Partition to functions that compute their values. If not provided, the Grid configures the cut_edges updater for convenience.
Spanning tree methods¶
The recom()
proposal function operates on spanning trees of the
adjacency graph in order to generate new contiguous districting plans with balanced population.
The gerrychain.tree
submodule exposes some helpful functions for partitioning graphs
using spanning trees methods. These may be used to implement proposal functions or to generate
initial plans for running Markov chains, as described in MGGG’s 2018 Virginia House of Delegates
report.

class
gerrychain.tree.
Cut
(edge, subset)¶ Create new instance of Cut(edge, subset)

edge
¶ Alias for field number 0

subset
¶ Alias for field number 1


gerrychain.tree.
bipartition_tree
(graph, pop_col, pop_target, epsilon, node_repeats=1, spanning_tree=None, choice=<bound method Random.choice of <random.Random object>>)[source]¶ This function finds a balanced 2 partition of a graph by drawing a spanning tree and finding an edge to cut that leaves at most an epsilon imbalance between the populations of the parts. If a root fails, new roots are tried until node_repeats in which case a new tree is drawn.
Builds up a connected subgraph with a connected complement whose population is
epsilon * pop_target
away frompop_target
.Returns a subset of nodes of
graph
(whose induced subgraph is connected). The other part of the partition is the complement of this subset.Parameters:  graph – The graph to partition
 pop_col – The node attribute holding the population of each node
 pop_target – The target population for the returned subset of nodes
 epsilon – The allowable deviation from
pop_target
(as a percentage ofpop_target
) for the subgraph’s population  node_repeats – A parameter for the algorithm: how many different choices of root to use before drawing a new spanning tree.
 spanning_tree – The spanning tree for the algorithm to use (used when the algorithm chooses a new root and for testing)
 choice –
random.choice()
. Can be substituted for testing.

gerrychain.tree.
bipartition_tree_random
(graph, pop_col, pop_target, epsilon, node_repeats=1, spanning_tree=None, choice=<bound method Random.choice of <random.Random object>>)[source]¶ This is like
bipartition_tree()
except it chooses a random balanced cut, rather than the first cut it finds.This function finds a balanced 2 partition of a graph by drawing a spanning tree and finding an edge to cut that leaves at most an epsilon imbalance between the populations of the parts. If a root fails, new roots are tried until node_repeats in which case a new tree is drawn.
Builds up a connected subgraph with a connected complement whose population is
epsilon * pop_target
away frompop_target
.Returns a subset of nodes of
graph
(whose induced subgraph is connected). The other part of the partition is the complement of this subset.Parameters:  graph – The graph to partition
 pop_col – The node attribute holding the population of each node
 pop_target – The target population for the returned subset of nodes
 epsilon – The allowable deviation from
pop_target
(as a percentage ofpop_target
) for the subgraph’s population  node_repeats – A parameter for the algorithm: how many different choices of root to use before drawing a new spanning tree.
 spanning_tree – The spanning tree for the algorithm to use (used when the algorithm chooses a new root and for testing)
 choice –
random.choice()
. Can be substituted for testing.

gerrychain.tree.
recursive_tree_part
(graph, parts, pop_target, pop_col, epsilon, node_repeats=1, method=<function bipartition_tree>)[source]¶ Uses
bipartition_tree()
recursively to partition a tree intolen(parts)
parts of populationpop_target
(withinepsilon
). Can be used to generate initial seed plans or to implement ReComlike “merge walk” proposals.Parameters:  graph – The graph
 parts – Iterable of part labels (like
[0,1,2]
orrange(4)
 pop_target – Target population for each part of the partition
 pop_col – Node attribute key holding population data
 epsilon – How far (as a percentage of
pop_target
) frompop_target
the parts of the partition can be  node_repeats – Parameter for
bipartition_tree()
to use.
Returns: New assignments for the nodes of
graph
.Return type: dict
Metrics¶

gerrychain.metrics.
mean_median
(election_results)[source]¶ Computes the MeanMedian score for the given ElectionResults. A positive value indicates an advantage for the first party listed in the Election’s parties_to_columns dictionary.

gerrychain.metrics.
partisan_bias
(election_results)[source]¶ Computes the partisan bias for the given ElectionResults. The partisan bias is defined as the number of districts with abovemean vote share by the first party divided by the total number of districts, minus 1/2.

gerrychain.metrics.
partisan_gini
(election_results)[source]¶ Computes the partisan Gini score for the given ElectionResults. The partisan Gini score is defined as the area between the seatsvotes curve and its reflection about (.5, .5).

gerrychain.metrics.
efficiency_gap
(results)[source]¶ Computes the efficiency gap for the given ElectionResults. A positive value indicates an advantage for the first party listed in the Election’s parties_to_columns dictionary.