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

property candidates: Returns all candidates present in this graph

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

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

get_candidates_for_names(listOfNames): Given a list of all names, returns the corresponding Candidate for each name

get_migrated_raw_data(): As of implementation, only used for pie chart visualization.

property numRounds: Returns the number of rounds

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

set_elimination_order(orderedCandidates): Given a list of Candidates, 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_migrated_raw_data(migratedRawData): As of implementation, only used for pie chart visualization.

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(candidate, 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

property candidates: Returns all candidates present in this graph

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

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

get_candidates_for_names(listOfNames): Given a list of all names, returns the corresponding Candidate for each name

get_migrated_raw_data(): As of implementation, only used for pie chart visualization.

property numRounds: Returns the number of rounds

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

set_elimination_order(orderedCandidates): Given a list of Candidates, 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_migrated_raw_data(migratedRawData): As of implementation, only used for pie chart visualization.

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(candidate, 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

percent_denominator(roundNum, forceFirstRoundDeterminesPercentages): By default, percentDenominator is either the current round total in IRV, and the first round total in STV. forceFirstRoundDeterminesPercentages can override this.

rounds: list

winnerNames: list

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

Bases: object

Summarizes a single round, with functions to build the round

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

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

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

find_ties(graph)

Detects ties in this round for both eliminated and winning candidates. Populates eliminatedTiedWith and winnerTiedWith lists.

A tie occurs when a candidate in the action list (eliminated/winner) has the same vote count as another candidate not in that list.

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

RCV Result

Helper methods to generate a Graph

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

Bases: object

A single Candidate.

class visualizer.graph.rcvResult.Elimination(candidate, transfersByCandidate)

Bases: Transfer

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

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(candidate, transfersByCandidate)

Bases: object

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

class visualizer.graph.rcvResult.WinTransfer(candidate, transfersByCandidate)

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.candidates is a list of Candidate objects

candidates: list

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

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

rounds: list

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

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