Metrics and Diversity¶

Metrics¶

gerrychain.metrics.efficiency_gap(election_results: ElectionResults) → float[source]¶

Computes the efficiency gap for the given ElectionResults.

A positive value indicates an advantage for the first party listed in the Election’s party_names_to_node_attribute_names dictionary.

Parameters:: election_results (ElectionResults) – An ElectionResults object
Returns:: The efficiency gap for the given ElectionResults
Return type:: float

gerrychain.metrics.mean_median(election_results: ElectionResults) → float[source]¶

Computes the Mean-Median score for the given ElectionResults.

A positive value indicates an advantage for the first party listed in the Election’s party_names_to_node_attribute_names dictionary.

Parameters:: election_results (ElectionResults) – An ElectionResults object
Returns:: The Mean-Median score for the given ElectionResults
Return type:: float

gerrychain.metrics.partisan_bias(election_results: ElectionResults) → float[source]¶

Computes the partisan bias for the given ElectionResults.

The partisan bias is defined as the number of districts with above-mean vote share by the first party divided by the total number of districts, minus 1/2.

Parameters:: election_results (ElectionResults) – An ElectionResults object
Returns:: The partisan bias for the given ElectionResults
Return type:: float

gerrychain.metrics.partisan_gini(election_results: ElectionResults) → float[source]¶

Computes the partisan Gini score for the given ElectionResults.

The partisan Gini score is defined as the area between the seats-votes curve and its reflection about (.5, .5).

For more information on the computation, see Definition 1 in: https://arxiv.org/pdf/2008.06930.pdf

Parameters:: election_results (ElectionResults) – An ElectionResults object
Returns:: The partisan Gini score for the given ElectionResults
Return type:: float

gerrychain.metrics.polsby_popper(partition: Partition) → dict[Hashable, float][source]¶

Computes Polsby-Popper compactness scores for each district in the partition.

This function computes Polsby-Popper compactness scores for each district in the partition. It returns a dictionary mapping each district ID to its Polsby-Popper score.

Parameters:: partition (Partition) – The partition to compute scores for
Returns:: A dictionary mapping each district ID to its Polsby-Popper score
Return type:: dict[Hashable, float]

gerrychain.metrics.wasted_votes(party1_votes: float, party2_votes: float) → tuple[float, float][source]¶

Computes the wasted votes for each party in the given race.

This function computes the wasted votes for each party in the given race. It returns a tuple of the wasted votes for each party.

Parameters:

party1_votes (float) – the number of votes party1 received in the race
party2_votes (float) – the number of votes party2 received in the race

Returns:

A tuple of the wasted votes for each party.

Return type:

tuple[float, float]

Diversity statistics¶

Simple tooling to collect diversity stats on chain runs

class gerrychain.meta.diversity.DiversityStats(unique_plans: int, unique_districts: int, steps_taken: int)[source]¶

Lightweight stats object that reports the diversity of a given chain.

unique_plans¶

The number of unique plans seen so far.

Type:: int

unique_districts¶

The number of unique districts seen so far.

Type:: int

steps_taken¶

The number of steps taken so far.

Type:: int

Example usage:

DiversityStats(unique_plans=44162, unique_districts=82992, steps_taken=100000)

gerrychain.meta.diversity.collect_diversity_stats(chain: Iterable[Partition]) → Iterator[tuple[Partition, DiversityStats]][source]¶

Report the diversity of the chain being run, live, as a drop-in wrapper.

Requires the cut_edges updater on each Partition object. Plans/districts are considered distinct if they are not isomorphic. That is, relabled plans and districts are considered non-unique and counted as duplicate.

Example usage::

for partition, stats in collect_diversity_stats( Replay( graph, “sample-run.chain” ) ):: print(stats) # normal chain stuff here

Parameters:: chain (Iterable[Partition]) – A chain object to collect stats on.
Returns:: Pairs of partitions and cumulative statistics.
Return type:: Iterator[tuple[Partition, DiversityStats]]