Graph Loading & Creation

Colors

Graph

Data that holds the entire Graph, as well as utilities for parsers to interactively build the graph. You probably don’t want to use this directly, but instead, want to use the GraphSummary which is more user-friendly. To get the summary, use graph.summarize().

class visualizer.graph.graph.Graph(title)

Bases: object

Data about the entire graph, including nodes and links between thhem

create_graph_from_rounds(rounds): Generates a graph with nodes and edges, where the nodes are a single Item at a specific Round, and the edges are Transfers

create_node(item, count, round_i): Creates a node with the given count. Only meaningful while graph creation is in progress.

get_items_for_names(listOfNames): Given a list of all names, returns the corresponding Item for each naem

property items: Returns all items present in this graph

property numRounds: Returns the number of rounds

set_date(date): Sets the date of this election

set_elimination_order(orderedItems): Given a list of Items, sets the elimination erder. Does no validation that the given order is complete, but will likely throw several errors here or elsewhere if you pass bad data.

set_threshold(threshold): Sets the threshold for this election

summarize(): Returns the graph summary - or creates it if it hasn’t been requested yet

class visualizer.graph.graph.LinkData(source, target, value)

Bases: object

Data about a single “link”: a transfer from the source to target

class visualizer.graph.graph.NodeData(item, label, count, roundNum)

Bases: object

Data about a single “node”: a candidate in a single round

mark_eliminated(): Marks the given node as the node in which this candidate was eliminated

mark_winner(): Marks the given node as the node in which this candidate won

GraphCreator

Data that holds the entire Graph, as well as utilities for parsers to interactively build the graph. You probably don’t want to use this directly, but instead, want to use the GraphSummary which is more user-friendly. To get the summary, use graph.summarize().

class visualizer.graph.graph.Graph(title)

Bases: object

Data about the entire graph, including nodes and links between thhem

create_graph_from_rounds(rounds): Generates a graph with nodes and edges, where the nodes are a single Item at a specific Round, and the edges are Transfers

create_node(item, count, round_i): Creates a node with the given count. Only meaningful while graph creation is in progress.

get_items_for_names(listOfNames): Given a list of all names, returns the corresponding Item for each naem

property items: Returns all items present in this graph

property numRounds: Returns the number of rounds

set_date(date): Sets the date of this election

set_elimination_order(orderedItems): Given a list of Items, sets the elimination erder. Does no validation that the given order is complete, but will likely throw several errors here or elsewhere if you pass bad data.

set_threshold(threshold): Sets the threshold for this election

summarize(): Returns the graph summary - or creates it if it hasn’t been requested yet

class visualizer.graph.graph.LinkData(source, target, value)

Bases: object

Data about a single “link”: a transfer from the source to target

class visualizer.graph.graph.NodeData(item, label, count, roundNum)

Bases: object

Data about a single “node”: a candidate in a single round

mark_eliminated(): Marks the given node as the node in which this candidate was eliminated

mark_winner(): Marks the given node as the node in which this candidate won

GraphSummary

Summarize the graph to provide helper functions to different visualizers

class visualizer.graph.graphSummary.CandidateInfo(name)

Bases: object

Summarizes a single candidate over each round

add_votes(amount): Adds the given votes to the current round

class visualizer.graph.graphSummary.GraphSummary(graph)

Bases: object

A class which organizes a Graph into data that makes it easier to visualize

candidates: dict

linksByTargetNode: dict

numEliminated: int

numWinners: int

rounds: list

winners: list

class visualizer.graph.graphSummary.RoundInfo(round_i)

Bases: object

Summarizes a single round, with functions to build the round

add_eliminated(item): Adds the name to the list of names eliminated this round

add_votes(candidateItem, numVotes): Notes that the given Candidate received numVotes votes - unless they’re not an “active” candidate.

add_winner(item): Adds the name to the list of names elected this round

key(): Returns the “key” for this round (just the round number)

RCV Result

Helper methods to generate a Graph

class visualizer.graph.rcvResult.Elimination(item, transfersByItem)

Bases: Transfer

Syntactic sugar for an Elimination, which is kind of like a transfer

class visualizer.graph.rcvResult.Item(name)

Bases: object

A single Item, also known as a Candidate elsewhere in the Code.

class visualizer.graph.rcvResult.Round

Bases: object

A single Round, with data about who won and where votes were transferred

class visualizer.graph.rcvResult.Transfer(item, transfersByItem)

Bases: object

Transfers is a mapping from Item objects to a number of transferred votes.

class visualizer.graph.rcvResult.WinTransfer(item, transfersByItem)

Bases: Transfer

Syntactic sugar for a Win, which is kind of like a transfer

Read RCVRC JSON

Class which reads an RCVRC-formatted JSON file

class visualizer.graph.readRCVRCJSON.FixIgnoreResidualSurplus(jsonData)

Bases: JSONMigrateTask

Creates a “residual surplus” candidate in the first round if we find it in other rounds, since we look to the first round for all candidates (or places votes can be transferred)

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixNoTransfersTask(jsonData)

Bases: JSONMigrateTask

The JSON prefers no key named “transfers” instead of an empty list. We do not.

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixRankitCombinedTallyResults(jsonData)

Bases: JSONMigrateTask

Rankit includes eliminations and elected on the same tallyResult

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixRankitMissingTransfers(jsonData)

Bases: JSONMigrateTask

Rankit often forgets to eliminate candidates, they just drop them

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixRankitMissingWinners(jsonData)

Bases: JSONMigrateTask

Rankit stops including Winner in tally after they win

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixRankitNoElimOnLastRound(jsonData)

Bases: JSONMigrateTask

Rankit incorrectly eliminates on the last round

do(): Run the migration

class visualizer.graph.readRCVRCJSON.FixUndeclaredUWITask(jsonData)

Bases: JSONMigrateTask

Undeclared votes are sometimes marked as ‘UWI’ instead of ‘Undeclared’

do(): Run the migration

class visualizer.graph.readRCVRCJSON.HideDecimalsTask(jsonData)

Bases: JSONMigrateTask

If the config desired it - remove all decimal places

do(): Run the migration

class visualizer.graph.readRCVRCJSON.JSONMigrateTask(jsonData)

Bases: object

An abstract base class to “fix” JSONs. Each migration “task” should override this.

abstract do(): Run the migration. Put your subclass’ logic here.

is_rankit_data(): Is the jsonData from RankIt?

rename(fromStr, toStr): A helper function to rename a candidate s/fromStr/toStr throughout the JSON Returns false if toStr already existed in the results – will refuse to overwrite

class visualizer.graph.readRCVRCJSON.JSONReader(data)

Bases: object

The class which reads the JSON and performs migrations

self.graph is a Graph object which is partially initialized (TODO how partially?) self.rounds is a list of Round objects self.items is a list of Item objects

eliminationOrder: list

get_elimination_order(): Returns the elimination order: a list of names in the order in which they were eliminated

get_graph(): Returns the Graph object

get_rounds(): Returns the list of rounds

graph: object

items: list

parse_data(data): Parses the JSON data, or raises an exception on failure

rounds: list

set_elimination_order(rounds, items): Sets the elimination order given each round and a list of Items

class visualizer.graph.readRCVRCJSON.MakeExhaustedAndSurplusACandidate(jsonData)

Bases: JSONMigrateTask

If there are “exhausted” ballots, make them a first-class citizen candidate

do(): Run the migration, ensuring they are not already marked as candidates

class visualizer.graph.readRCVRCJSON.MakeTalliesANumber(jsonData)

Bases: JSONMigrateTask

Converts tally strings to numbers

do(): Run the migration

exception visualizer.graph.readRCVRCJSON.MigrationError

Bases: Exception

An error triggered during migration, with a message to be passed on to the user

class visualizer.graph.readRCVRCJSON.NormalizeSpecialNames(jsonData)

Bases: JSONMigrateTask

normalize names to their canonical, indexable names

do(): Run the migration