BaseGraph

How do we "load" a map into GerryChain? We start by initializing a BaseGraph object from either a .json or .shp file.

Properties

Once you initialize a BaseGraph, you can access the following properties from it:

BaseGraph Properties	Description
`num_nodes` (Int)	Number of nodes in the BaseGraph
`num_edges` (Int)	Number of edges in the BaseGraph
`total_pop` (Int)	Total Population in the BaseGraph
`populations` Array{Int, 1}	An array of populations at the node level, where the i'th index of the array is the population of the i'th node
`adj_matrix` SparseMatrixCSC{Int, Int}	A sparse adjacency matrix of the graph, where an edge exists between nodes `i` and `j` if `adj_matrix[i,j] != 0`. The value at `adj_matrix[i,j]` is the edge id of the edge that connects nodes `i` and `j`.
`edge_src` Array{Int, 1}	An array of length(numedges) where `edgesrc[i]`is the source of the edge`i`.
`edge_dst` Array{Int, 1}	An array of length(numedges) where `edgedst[i]`is the destination of the edge`i`.
`neighbors` Array{Array{Int64,1},1}	An array of arrays, where `neighbors[i]` holds a list of all the neighbors of node `i`
`simple_graph` SimpleGraph	A SimpleGraph object from the LightGraphs library
`attributes` Array{Dict{String, Any}}	An array of dictionaries where `attributes[i]` holds the attributes of node `i`

BaseGraph

GerryChain.BaseGraph
GerryChain.get_attributes
GerryChain.get_subgraph_population
GerryChain.induced_subgraph_edges
GerryChain.weighted_kruskal_mst

Initializing a BaseGraph

A BaseGraph can be initialized in the following way:

GerryChain.BaseGraph — Type

BaseGraph(filepath::AbstractString,
          pop_col::AbstractString;
          adjacency::String="rook")::BaseGraph

Builds the BaseGraph object. This is the underlying network of our districts, and its properties are immutable i.e they will not change from step to step in our Markov Chains.

Arguments:

filepath: A path to a .json or .shp file which contains the information needed to construct the graph.
pop_col: the node attribute key whose accompanying value is the population of that node
adjacency: (Only used if the user specifies a filepath to a .shp file.) Should be either "queen" or "rook"; "rook" by default.

source

If you initialize a BaseGraph from a .shp file, make sure that there is another file of the same name with a .dbf extension in the same folder! This is because the .shp file provides the geometry of the regions of interest, while the .dbf provides information about each region's attributes - e.g., the total number of votes cast or the percentage of Black voters.

If you initialize a BaseGraph from a .json file, GerryChain expects the .json file to be generated by the Graph.to_json() function of the Python implementation of GerryChain. We assume that the JSON file has the structure of a dictionary where

(1) the key "nodes" yields an array of dictionaries of node attributes,

(2) the key "adjacency" yields an array of edges (represented as dictionaries), and

(3) the key "id" within the edge dictionary indicates the destination node of the edge.

API

GerryChain.get_attributes — Method

get_attributes(nodes::Array{Any, 1})

Returns an array of dicts attributes of length length(nodes) where the attributes of the nodes[i] is at attributes[i] as a dictionary.

source

GerryChain.get_subgraph_population — Method

get_subgraph_population(graph::BaseGraph,
                        nodes::BitSet)::Int

Arguments:

graph: Underlying graph object
nodes: A Set of Ints

Returns the population of the subgraph induced by nodes.

source

GerryChain.induced_subgraph_edges — Method

induced_subgraph_edges(graph::BaseGraph,
                       vlist::Array{Int, 1})::Array{Int, 1}

Returns a list of edges of the subgraph induced by vlist, which is an array of vertices.

source

GerryChain.weighted_kruskal_mst — Function

weighted_kruskal_mst(graph::BaseGraph,
                     edges::Array{Int, 1},
                     nodes::Array{Int, 1},
                     weights::Array{Float64, 1},
                     rng=MersenneTwister(1234))::BitSet

Generates and returns a minimum spanning tree from the subgraph induced by edges and nodes, using Kruskal's MST algorithm.

Note:

The graph represents the entire graph of the plan, where as edges and nodes represent only the sub-graph on which we want to draw the MST.

Arguments:

graph: Underlying Graph object
edges: Array of edges of the sub-graph
nodes: Set of nodes of the sub-graph
weights: Array of weights of length(edges) where weights[i] is the weight of edges[i]

Returns a BitSet of edges that form a mst.

source