Overview

GerryTools exposes the same scoring ideas at three levels. Choose the smallest interface that fits the work you are doing.

	Use
Convenience functions	Evaluate one assignment
PlanEvaluator	Reuse resources across metrics or plans
Array formulas	Score arrays already aggregated by district

Assignment forms

Form	Interpretation
GeoDataFrame column name	District labels are read from that column
Mapping	Each graph node is mapped to a district label
Sequence	District labels follow graph-node order
GerryChain Partition	The partition assignment and graph are used together

Geometry metrics need a GeoDataFrame. Graph metrics can use a NetworkX graph or GerryChain partition. PlanEvaluator uses one graph as the common unit order for every registered metric.

Metric families

Every row below has both a lowercase convenience function and a corresponding capitalized metric unless noted otherwise.

Aggregation, population, and demographics

Function / metric	Result
tally() / Tally	Sums one or more columns by district
tally_by_region() / TallyByRegion	Sums columns by fixed region and district
population_deviations() / PopulationDeviations	Signed district deviations from ideal population
max_absolute_population_deviation() / MaxAbsolutePopulationDeviation	Largest absolute district deviation
max_population_deviation() / MaxPopulationDeviation	Top-to-bottom district population range
demographic_shares() / DemographicShares	District subgroup shares
districts_above_threshold() / DistrictsAboveThreshold	Count of districts above a subgroup threshold

Elections and partisan scores

Function / metric	Result
district_vote_shares() / DistrictVoteShares	Two-party district vote shares
district_wins() / DistrictWins	District win indicators
seats() / Seats	Seats won
overall_vote_share() / OverallVoteShare	Aggregate two-party vote share
disproportionality() / Disproportionality	Signed seat share minus aggregate vote share
efficiency_gap() / EfficiencyGap	Wasted-vote efficiency gap
simplified_efficiency_gap() / SimplifiedEfficiencyGap	Equal-turnout seat-vote formula
mean_median() / MeanMedian	Median minus mean district vote share
partisan_bias() / PartisanBias	Partisan bias at 50 percent under uniform swing
partisan_gini() / PartisanGini	Unsigned partisan Gini under uniform swing

Scores across elections

These metrics accept one party/opposition column pair per election.

Function / metric	Result
competitive_contests() / CompetitiveContests	Contests within a margin around 50 percent
party_wins_by_district() / PartyWinsByDistrict	Party wins by district across elections
swing_districts() / SwingDistricts	Districts not consistently won by either side
party_districts() / PartyDistricts	Districts won by the party in every election
opposition_party_districts() / OppositionPartyDistricts	Districts won by the opposition in every election
aggregate_seats() / AggregateSeats	Wins across every election and district
mean_signed_seat_vote_gap() / MeanSignedSeatVoteGap	Mean signed seat-share minus vote-share gap
mean_absolute_seat_vote_gap() / MeanAbsoluteSeatVoteGap	Mean absolute seat-share minus vote-share gap

Regions and compactness

Function / metric	Result
cut_edges() / CutEdges	Cut-edge count or summed edge weight
region_splits() / RegionSplits	Fixed regions assigned to multiple districts
region_pieces() / RegionPieces	Occupied region-district pairs
region_parts() / RegionParts	Connected region-district parts
polsby_popper() / PolsbyPopper	Polsby-Popper compactness
schwartzberg() / Schwartzberg	Schwartzberg compactness
reock() / Reock	Minimum-enclosing-circle compactness
convex_hull_ratio() / ConvexHullRatio	Convex-hull compactness
state_clipped_convex_hull_ratio() / StateClippedConvexHullRatio	State-clipped convex-hull compactness
population_polygon() / PopulationPolygon	Population captured by a district convex hull
eguia() / Eguia	Seat share against a population-weighted regional benchmark

Array formulas

The functions in gerrytools.scoring.formulas operate on NumPy-compatible arrays. The final axis is districts; cross-election functions use the preceding axis for elections.

import pandas as pd

import gerrytools.scoring as gs

democratic_votes = [60, 45, 70, 40]
republican_votes = [40, 55, 30, 60]
district_populations = [98, 101, 100, 101]

pd.Series(
    {
        "seats": gs.formulas.seats(democratic_votes, republican_votes),
        "efficiency gap": gs.formulas.efficiency_gap(democratic_votes, republican_votes),
        "maximum population deviation": gs.formulas.max_population_deviation(district_populations),
    }
)

/home/docs/checkouts/readthedocs.org/user_builds/gerrytools/envs/latest/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

seats                                2
efficiency gap                  -0.075
maximum population deviation       3.0
dtype: object

Continue with Convenience Functions for one-plan calls or PlanEvaluator when resources should be reused. The scoring API contains the full signatures and formula conventions.