Edit on GitHub

Election

Unsurprisingly, a key use of GerryChain is to analyze the electoral outcomes under different districting plans. If you wanted to, you could write a bunch of AbstractScores to measure election outcomes - or you could use the API we've already made for you!

Once initialized, the properties you can access in the Election struct are:

Properties

FieldDescription
name (String)name of the Election
parties (Array{String, 1})array of names of different parties
vote_counts (Array{Int64, 2})matrix of vote counts (row = district, column = party)
vote_shares (Array{Float64, 2})matrix of vote shares (row = district, column = party)

The way to initialize the Election object would be

GerryChain.Election — Type
Election(name::String,
         parties::Array{String, 1},
         num_districts::Int)

Initializes an Election for a given number of parties and districts, initializing the vote counts & shares to zero.

source

ElectionTracker

The ElectionTracker method returns a CompositeScore that first updates the vote count / share for changed districts and then proceeds to calculate other partisan metrics, as desired by the user. Re-calculating vote counts only for changed districts means that the CompositeScore does not perform redundant computations for all of the partisan metrics.

GerryChain.ElectionTracker — Function
ElectionTracker(election::Election,
                scores::Array{S, 1}=AbstractScore[])::CompositeScore where {S <: AbstractScore}

The ElectionTracker method returns a CompositeScore that first updates the vote count / share for changed districts and then proceeds to run other scores (such as vote count for a particular party, partisan metrics, etc.), as desired by the user. Re-calculating vote counts only for changed districts means that the CompositeScore does not perform redundant computations for all of the partisan metrics. Furthermore, packaging all election-related scores within the CompositeScore ensures that the vote update occurs first, followed by the partisan metrics scoring functions.

source
GerryChain.efficiency_gap — Method
efficiency_gap(name::String,
               election::Election,
               party::String)::PlanScore

Returns a PlanScore with a custom scoring function specific to election that calculates the efficiency gap of a particular plan for a particular party.

source
GerryChain.mean_median — Method
mean_median(name::String,
            election::Election,
            party::String)::PlanScore

Returns a PlanScore with a custom scoring function specific to election that calculates the mean-median score of a particular plan for a particular party.

source
GerryChain.seats_won — Method
seats_won(name::String,
          election::Election,
          party::String)::PlanScore

Returns a PlanScore with a custom scoring function specific to election that returns the number of seats won by a particular party across all districts in a given plan.

source
GerryChain.vote_count — Method
vote_count(name::String,
           election::Election,
           party::String)::DistrictScore

Returns a DistrictScore that will return the number of votes won by the specified party.

source
GerryChain.vote_share — Method
vote_share(name::String,
           election::Election,
           party::String)::DistrictScore

Returns a DistrictScore that will return the percentage of votes won by the specified party.

source
GerryChain.wasted_votes — Method
wasted_votes(party₁_votes::Int,
             party₂_votes::Int)

Computes the number of votes "wasted" by each party. Wasted votes are votes that are either more than necessary than the party needed to win a seat or votes in a race that party lost. In a tie, all votes are considered to have been wasted.

source

Usage

election = Election("SEN10", ["SEN10D", "SEN10R"], partition.num_dists)
election_metrics = [   # optional
    vote_count("count_d", election, "SEN10D"),
    vote_share("share_d", election, "SEN10D"),
    efficiency_gap("efficiency_gap", election, "SEN10D"),
    seats_won("seats_won", election, "SEN10D"),
]
...
scores = [
    ...
    ElectionTracker(election, election_metrics)
    ...
]
...
chain_data = recom_chain(graph, partition, population_constraint, num_steps, scores)