Scores

Generally, the point of running the chain is comparing the properties of some existing plan to the properties of the ensemble of plans generated by the chain. Thus, we need a way to record information about the plans generated during the progression of the chain. This is the point of Scores: each score has a scoring function that is evaluated on the current districting plan at each step of the chain. The resulting values are saved in a dictionary, which is itself added to a growing ChainScoreData object at each step of the chain. The ChainScoreData returned by recom_chain() and flip_chain() is like a "history" of the scores at each step of the chain. (See get_scores_at_step() for information about how to retrieve the values of any subset of scores at a particular step in the chain.)

Score types

All Scores have the type AbstractScore. There are four categories of scores (note that DistrictAggregate is really a sub-category of DistrictScore):

So, when should you use which score? Here's a general breakdown:

DistrictAggregate

Use this score when you just want to sum an attribute over all nodes in a district.

DistrictAggregate(name::String,
                  key::String)

For example, if you wanted to count the number of Black people in each district at every step of the chain, you could use a DistrictAggregate score to do so. If the attribute in the nodes of the graph was called "BLACK" and you wanted to call your score "Black_Pop", you would initialize the score as

julia> DistrictAggregate("Black_Pop", "BLACK")
DistrictAggregate("Black_Pop", "BLACK")

If you wanted to name your score the same as the node attribute, you could also use

DistrictAggregate(key::String)

In this case, you would instantiate your score as

julia> DistrictAggregate("BLACK")
DistrictAggregate("BLACK", "BLACK")

DistrictScore

This score works best when you're interested in tracking a statistic for each district for all plans in the chain. For example, you might want to know the Polsby-Popper score for each district at every step of the chain.

DistrictScore(name::Union{String, Missing}
              score_fn::Function)

The example below illustrates a simple example of setting up a DistrictScore. Perhaps somehow you find yourself interested in computing the number of edges within a district.

julia> function num_edges_within_dist(graph::BaseGraph,
                                      district_nodes::BitSet,
                                      district::Int)
           """ Computes the number of edges within each district of the plan.
               Arguments:
                   graph:          The underlying BaseGraph
                   district_nodes: A Set of nodes in district `district`. Each node
                                   is represented as an Int.
                   district:       Int representing the district
           """
           all_edges = []
           for node in district_nodes, neighbor in graph.neighbors[node]
               if neighbor in district_nodes
                   edge = graph.adj_matrix[node, neighbor]
                   push!(all_edges, edge)
               end
           end
           return length(unique(all_edges))
       end
num_edges_within_dist (generic function with 1 method)

julia> # instantiate this score
       DistrictScore("edges_within_dist", num_edges_within_dist)
DistrictScore("edges_within_dist", Main.ex-env.num_edges_within_dist)

PlanScore

This type of score is suited to statistics that are evaluated on an entire plan. For example, the number of districts won by a party for a given plan would be a PlanScore.

PlanScore(name::Union{String, Missing},
          score_fn::Function)

Below we illustrate a few examples on how to construct a PlanScore:

julia> function num_max_blocks(graph::BaseGraph,
                               partition::Partition)
           """ Returns the maximum number of blocks in each district.
               This function assumes that the nodes in `graph` are blocks.
           """
           return maximum([length(nodes) for nodes in partition.dist_nodes])
       end
num_max_blocks (generic function with 1 method)

julia> function higher_num_cut_edges_than_parent(graph::BaseGraph,
                                                 partition::Partition)
           """ Returns True if `partition` has a higher number of cut edges than the
               previous plan, False otherwise.
           """
           if partition.parent isa Partition & partition.num_cut_edges > partition.parent.num_cut_edges
               return True
           end
           return False
       end
higher_num_cut_edges_than_parent (generic function with 1 method)

julia> # how to formulate these scores
       PlanScore("num_max_blocks", num_max_blocks)
PlanScore("num_max_blocks", Main.ex-env.num_max_blocks)

julia> PlanScore("higher_num_cut_edges_than_parent", higher_num_cut_edges_than_parent)
PlanScore("higher_num_cut_edges_than_parent", Main.ex-env.higher_num_cut_edges_than_parent)

CompositeScore

This might be the most difficult type of score to wrap one's mind around. CompositeScores are best when you have a series of scores with some shared state or rely on the same computation. They allow you to "group" scores together. For example, we use CompositeScores for Elections, since almost all election-related scores rely on vote counts and vote shares.

CompositeScore(name::String,
               scores::Array{S,1}) where {S<:AbstractScore} # should be other AbstractScores

Built-In Score Functions

Currently only one score function comes built-in with GerryChain, and it is the number of cut-edges in the plan.

num_cut_edges(name::String)::PlanScore

A little more detail on score functions

Why do we differentiate between the different types of scores? The answer boils down to efficiency. Recall that each plan in the chain (whether it is uses ReCom proposals or Flip proposals) only differs from the previous plan by 2 districts. This means we can save space / eliminate redundant computation by only re-calculating district-level scores on the districts that were changed. However, for plan-level scores, we always have to re-run the score function on the entire partition.

Other Score Functions

coerce_aggregated_attributes!(graph::BaseGraph,
                              scores::Array{S, 1}) where {S<:AbstractScore}

eval_score_on_district(graph::BaseGraph,
                       partition::Partition,
                       score::DistrictAggregate,
                       district::Int)::Number

eval_score_on_district(graph::BaseGraph,
                       partition::Partition,
                       score::DistrictScore,
                       district::Int)

eval_score_on_partition(graph::BaseGraph,
                        partition::Partition,
                        composite::CompositeScore)

{
    # District-level scores
    d\_score₁.name :     [a₁, a₂, ..., aᵢ]
        ...
    d\_scoreᵤ.name :     [b₁, b₂, ..., bᵢ]
    # Partition-level scores
    p\_score₁.name :     c,
        ...
    p\_scoreᵥ.name :     d,
}

eval_score_on_partition(graph::BaseGraph,
                        partition::Partition,
                        score::PlanScore)

score_initial_partition(graph::BaseGraph,
                        partition::Partition,
                        scores::Array{S, 1}) where {S<:AbstractScore}

{
    # District-level scores
    d\_score₁.name :     [a₁, a₂, ..., aᵤ]
        ...
    d\_scoreᵤ.name :     [b₁, b₂, ..., bᵤ]
    # Partition-level scores
    p\_score₁.name :     c,
        ...
    p\_scoreᵥ.name :     d,
    # Composite scores
    c\_score₁.name :
        {
            c\_score₁.scores[1].name :     ...
                ...
        }
        ...
    c\_scoreᵢ.name :
        {
            ...
        }
}

score_partition_from_proposal(graph::BaseGraph,
                              partition::Partition,
                              proposal::AbstractProposal,
                              scores::Array{S, 1}) where {S<:AbstractScore}

    {
        "num_cut_edges" : partition.num\_cut\_edges,
        "dists"         : (5, 8),
        "White"         : [43, 22],
        "Sen2010_Dem"   : [62, 66],
    }