rcv.variants.STVFractionalBallot¶

class rcv.variants.STVFractionalBallot(jurisdiction: str = '', state: str = '', year: str = '', date: str = '', office: str = '', notes: str = '', parser_func: Callable | None = None, parser_args: Dict | None = None, parsed_cvr: Dict | None = None, split_fields: List | None = None, exhaust_on_duplicate_candidate_marks: bool = False, exhaust_on_overvote_marks: bool = False, exhaust_on_N_repeated_skipped_marks: int = 0, treat_combined_writeins_as_exhaustable_duplicates: bool = True, combine_writein_marks: bool = True, exclude_writein_marks: bool = False, n_winners: int | None = None, multi_winner_rounds: bool = False, bottoms_up_threshold: float | None = None, truncate_to: int | None = 4, writeins_eliminated_first: bool = False)¶

Bases: STV

Multi-winner elections with fractional ballot transfer. - Win threshold is set as the (# first round votes)/(# of seats + 1). - Any winner is eliminated and has their surplus redistributed. Percent of each ballot redistributed is equal to (# of votes winner has – minus the threshold)/(# of votes winner has). - If no winners in round, candidate with least votes in a round is eliminated and has votes transferred.

__init__(jurisdiction: str = '', state: str = '', year: str = '', date: str = '', office: str = '', notes: str = '', parser_func: Callable | None = None, parser_args: Dict | None = None, parsed_cvr: Dict | None = None, split_fields: List | None = None, exhaust_on_duplicate_candidate_marks: bool = False, exhaust_on_overvote_marks: bool = False, exhaust_on_N_repeated_skipped_marks: int = 0, treat_combined_writeins_as_exhaustable_duplicates: bool = True, combine_writein_marks: bool = True, exclude_writein_marks: bool = False, n_winners: int | None = None, multi_winner_rounds: bool = False, bottoms_up_threshold: float | None = None, truncate_to: int | None = 4, writeins_eliminated_first: bool = False) → None¶

Constructor. Subclass of CastVoteRecord. Initializes CastVoteRecord superclass, applies contest rules to ballots, tabulates the election, and calculates default statistics.

First set of arguments are identical to CastVoteRecord constructor.

For ballot rule arguments, see BallotMarks.new_rule_set for a description of their meaning. In election tabulation, overvotes, skipped rankings, and duplicate candidate rankings are removed from ballots, unless they cause the ballot to become inactive due to other rule settings in which case the ballot is effectively truncated after those marks are reached.

Parameters:

n_winners (Optional[int], optional) – Number of winners in the election, if applicabale. Defaults to None
multi_winner_rounds (Optional[bool], optional) – If True, and multiple winner are possible in a single round, then they are all elected that round. If False, only the winner with the highest ballot total that round is elected. Defaults to False
bottoms_up_threshold (Optional[float], optional) – Float between 0 and 1 indicating the dynamic threshold to use in each round of a bottoms up election, defaults to None
truncate_to – int or None representing how many decimal places to truncate surplas ballot transfers, if None, does not truncacte, defaults to 4

Parma writeins_eliminated_first:

sets writeins as first loser (in _set_loser_round()) regardless of their number of votes. value should be True or False

Methods

`__init__`([jurisdiction, state, year, date, ...])	Constructor.
`add_rule_set`(set_name, set_dict)	Add a new rule set used to create a modified version of the CVR.
`calc_annotated_cvr_table`(cvr)	Static method wrapper around get_annotated_cvr_table object method.
`calc_candidate_details_tables`(rcv_obj)	Static wrapper for RCV.get_candidate_details_table that returns a list tables, one for each tabulation.
`calc_candidate_rank_usage_table`(rcv_obj)	Static wrapper for RCV.get_candidate_rank_usage_table.
`calc_condorcet_tables`(cvr)	Static method wrapper around get_condorcet_tables object method.
`calc_crossover_tables`(cvr)	Static method wrapper around get_crossover_tables object method.
`calc_cumulative_ranking_tables`(cvr)	Static method wrapper around get_cumulative_ranking_tables object method.
`calc_first_choice_to_finalist_table`(rcv_obj)	Static wrapper for RCV.get_first_choice_to_finalist_table.
`calc_first_second_tables`(cvr)	Static method wrapper around get_first_second_tables object method.
`calc_rank_usage_table`(cvr)	Static method wrapper around get_rank_usage_table object method.
`calc_round_by_round_table`(rcv_obj[, ...])	Static wrapper for RCV.get_round_by_round_table.
`calc_stats`(cvr[, keep_decimal_type, ...])	Static method wrapper around get_stats object method.
`calc_winner_final_pile_rank_distribution_table`(rcv_obj)	Static wrapper for RCV.get_winner_final_pile_rank_distribution_table.
`finalist_candidates`([tabulation_num])	Return list of candidates with any ballot weight allotted to them by the end of tabulation.
`get_annotated_cvr_table`()
`get_candidate_details_table`([tabulation_num])	Generate table of candidate round by round vote counts.
`get_candidate_outcomes`([tabulation_num])	Return a list of dictionaries containing candidate outcome information for a given tabulation.
`get_candidates`([rule_set_name])	Returns a BallotMarks object containing the unique candidate set.
`get_condorcet_tables`()	Returns a two condorcet tables as a pandas data frame with candidate names as row and column indices.
`get_crossover_tables`()	Table describing co-ranking patterns between candidates.
`get_cumulative_ranking_tables`()	Return cumulative ranking tables.
`get_cvr_dict`([rule_set_name, disaggregate])	Return CVR as dictionary of lists.
`get_cvr_table`([table_format, disaggregate])	Return the cvr as pandas dataframe.
`get_final_ranks`([tabulation_num, disaggregate])	Return a list of ballot ranks after tabulation.
`get_final_weight_distrib`([tabulation_num, ...])	Return a list of ballot weight distributions describing how much of each ballot was allocated to a winner, finalist, or exhausted.
`get_final_weights`([tabulation_num, disaggregate])	Return a list of ballot weights after tabulation.
`get_first_choice_to_finalist_table`([...])	Create a pandas dataframe describing the first choice candidate distribution and which finalist candidate those ballots ended the tabulation allocated to.
`get_first_second_tables`()	Return pandas dataframes containing first and second choice candidate distributions across ballots.
`get_initial_ranks`([tabulation_num, disaggregate])	Ballots prior to first round tabulation, after election rules applied.
`get_initial_weights`([tabulation_num, ...])	Return a list of ballot weights prior to specified tabulation.
`get_rank_usage_table`()	Table describing rank usage patterns.
`get_round_by_round_dict`([tabulation_num])	Create a dictionary containing election round by round information that matches the nesting structure of RCVIS upload format.
`get_round_by_round_table`([tabulation_num])	Create a table containing round by round details for the tabulation.
`get_round_tally_dict`(round_num[, ...])	Return a dictionary containing candidate names as keys and vote counts as values.
`get_round_tally_tuple`(round_num[, ...])	Return a list of (candidate name, candidate vote count) tuples for round in tabulation.
`get_round_transfer_dict`(round_num[, ...])	Return a dictionary describing vote transfers from round specified.
`get_stats`([keep_decimal_type, ...])	Obtain the default statistics calculated by the RCV object, these include statistics calculcated by CastVoteRecord object.
`get_variant_group`(rcv_obj)	Convenience function for batch script.
`get_variant_name`(rcv_obj)	Convenience function for batch script.
`get_win_threshold`([tabulation_num])	Win threshold for a given tabulation expressed as a number of votes.
`get_winner_final_pile_rank_distribution_table`([...])	Measure where winners ranked on ballots that ended up in their final pile.
`n_rounds`([tabulation_num])	Return the number of rounds used in tabulation, for a given tabulation in the election.
`n_tabulations`()	Returns number of tabulations in election
`write_annotated_cvr_table`(cvr[, save_dir])	Static method wrapper around get_annotated_cvr_table object method that writes the table out to save_dir.
`write_condorcet_tables`(cvr[, save_dir])	Static method wrapper around get_condorcet_tables object method that writes the table out to save_dir.
`write_crossover_tables`(cvr[, save_dir])	Static method wrapper around get_crossover_tables object method that writes the table out to save_dir.
`write_cumulative_ranking_tables`(cvr, save_dir)	Static method wrapper around get_cumulative_ranking_tables object method that writes tables out to save_dir.
`write_cvr_table`(cvr, save_dir[, table_format])	Static method wrapper around get_cvr_table object method that writes CVR table out to save_dir.
`write_first_choice_to_finalist_table`(rcv_obj)	Wrapper for RCV.get_first_choice_to_finalist_table that writes out the table for each tabulation to path '{save_dir}/first_choice_to_finalist/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv'
`write_first_second_tables`(cvr[, save_dir])	Static method wrapper around get_first_second_tables object method that writes tables out to save_dir.
`write_rank_usage_table`(cvr[, save_dir])	Static method wrapper around get_rank_usage_table object method that writes the table out to save_dir.
`write_round_by_round_json`(rcv_obj, save_dir)	Wrapper for RCV.get_round_by_round_dict that writes out the dictionary for each tabulation to path '{save_dir}/round_by_round_json/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv'
`write_round_by_round_table`(rcv_obj[, save_dir])	Wrapper for RCV.get_round_by_round_table that writes out the table for each tabulation to path '{save_dir}/round_by_round_table/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv'

add_rule_set(set_name: str, set_dict: Dict[str, bool | None]) → None¶

Add a new rule set used to create a modified version of the CVR.

Parameters:

set_name (str) – Unique name given to this rule set and modified CVR.
set_dict (Dict[str, Optional[bool]]) – Dictionary of boolean rule settings. Rule options are defined in BallotMarks.new_rule_set.

static calc_annotated_cvr_table(cvr: Type[CastVoteRecord]) → DataFrame¶

Static method wrapper around get_annotated_cvr_table object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: Pandas dataframes containing rank column cvr table with statistics attached
Return type:: pd.DataFrame

static calc_candidate_details_tables(rcv_obj: Type[RCV]) → List[DataFrame]¶

Static wrapper for RCV.get_candidate_details_table that returns a list tables, one for each tabulation.

Parameters:: rcv_obj (Type[RCV]) – RCV object or RCV subclass object
Return type:: List[pd.DataFrame]

static calc_candidate_rank_usage_table(rcv_obj: Type[CastVoteRecord]) → DataFrame¶

Static wrapper for RCV.get_candidate_rank_usage_table.

Parameters:: rcv_obj (Type[CastVoteRecord]) – RCV object or RCV subclass object
Return type:: pd.DataFrame

static calc_condorcet_tables(cvr: Type[CastVoteRecord]) → Tuple[DataFrame]¶

Static method wrapper around get_condorcet_tables object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: Tuples of pandas dataframes containing statistics on head to head candidate matchups. Tuple containing both count and percent formats.
Return type:: Tuple[pd.DataFrame]

static calc_crossover_tables(cvr: Type[CastVoteRecord]) → Tuple[DataFrame]¶

Static method wrapper around get_crossover_tables object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: Tuples of pandas dataframes containing statistics on candidate ranking patterns near the top of the ballot. Tuple containing both count and percent formats.
Return type:: Tuple[pd.DataFrame]

static calc_cumulative_ranking_tables(cvr: Type[CastVoteRecord]) → Tuple[DataFrame]¶

Static method wrapper around get_cumulative_ranking_tables object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: Cumulative ranking tables in pandas dataframe. Tuple containing both count and percent formats.
Return type:: Tuple[pd.DataFrame]

static calc_first_choice_to_finalist_table(rcv_obj: Type[RCV], tabulation_num: int = 1) → DataFrame¶

Static wrapper for RCV.get_first_choice_to_finalist_table.

Parameters:

rcv_obj (Type[RCV]) – RCV object or RCV subclass object
tabulation_num (int, optional) – The tabulation to produce the table for, defaults to 1

Return type:

pd.DataFrame

static calc_first_second_tables(cvr: Type[CastVoteRecord]) → Tuple[DataFrame]¶

Static method wrapper around get_first_second_tables object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: First and second choice tables in pandas dataframes. Tuple containing three tables: count table and two percentage tables, one with exhausted ballots included in percentage calculations and one without.
Return type:: Tuple[pd.DataFrame]

static calc_rank_usage_table(cvr: Type[CastVoteRecord]) → DataFrame¶

Static method wrapper around get_rank_usage_table object method.

Parameters:: cvr (Type[CastVoteRecord]) – CastVoteRecord object.
Returns:: Pandas dataframe containing rank usage statistics across all ballots and by candidate.
Return type:: pd.DataFrame

static calc_round_by_round_table(rcv_obj: Type[RCV], tabulation_num: int = 1) → DataFrame¶

Static wrapper for RCV.get_round_by_round_table.

Parameters:: rcv_obj (Type[CastVoteRecord]) – RCV object or RCV subclass object
Return type:: pd.DataFrame

static calc_stats(cvr: Type[CastVoteRecord], keep_decimal_type: bool = False, add_split_stats: bool = False, add_id_info: bool = True) → List[DataFrame]¶

Static method wrapper around get_stats object method.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
keep_decimal_type (bool, optional) – Return the decimal class objects used by internal calculations rather than converting them to floats, defaults to False
add_split_stats (bool, optional) – Add extra statistics calculated for each category contained in split_fields columns passed to constructor, defaults to False
add_id_info (bool, optional) – Include contest ID details to returned dataframe, defaults to True

Returns:

A list containing a single row dataframe with statistics organized in multiple columns. If split_fields are passed, then extra rows are added for each category in the split columns.

Return type:

List[pd.DataFrame]

static calc_winner_final_pile_rank_distribution_table(rcv_obj: Type[RCV], tabulation_num: int = 1) → DataFrame | None¶

Static wrapper for RCV.get_winner_final_pile_rank_distribution_table.

Parameters:

rcv_obj (Type[RCV]) – RCV object or RCV subclass object
tabulation_num (int, optional) – The tabulation to produce the table for, defaults to 1

Return type:

Optional[pd.DataFrame]

finalist_candidates(tabulation_num: int = 1) → List[str]¶

Return list of candidates with any ballot weight allotted to them by the end of tabulation. This includes winners and non-winner finalists.

Parameters:: tabulation_num (int, optional) – Tabulation from which to return finalists, defaults to 1
Returns:: List of candidates
Return type:: List[str]

get_candidate_details_table(tabulation_num: int = 1) → DataFrame | None¶

Generate table of candidate round by round vote counts.

Parameters:: tabulation_num (int, optional) – tabulation num, defaults to 1
Return type:: Optional[pd.DataFrame]

get_candidate_outcomes(tabulation_num: int = 1) → List[Dict]¶

Return a list of dictionaries containing candidate outcome information for a given tabulation. Keys are name, round_elected, and round_eliminated. Values for round_elected and round_eliminated are either integers indicating round numbers or None.

Parameters:: tabulation_num (int, optional) – Tabulation for which to return candidate outcomes, defaults to 1
Returns:: List of dictionaries containing candidate outcome information for a given tabulation
Return type:: List[Dict]

get_candidates(rule_set_name: str | None = None) → BallotMarks¶

Returns a BallotMarks object containing the unique candidate set. The only rules which affect the candidate set are ‘combine_writein_marks’ and ‘exclude_writein_marks’.

Parameters:: rule_set_name (Optional[str], optional) – Name of modified CVR to return candidates from, defaults to None. If None, return candidates from default CVR. Defaults to None
Returns:: BallotMarks object containing unique candidates.
Return type:: BallotMarks

get_condorcet_tables() → Tuple[DataFrame | str | None]¶

Returns a two condorcet tables as a pandas data frame with candidate names as row and column indices. One contains counts and the other contains percents. Also return the name of the condorcet winner, or None.

Each cell indicates the count/percentage of ballots that ranked the row-candidate over the column-candidate (including ballots that only ranked the row-candidate). When calculating percents, the denominator is each cell is the number of ballots that ranked the row-candidate OR the column-candidate.

Symmetric cells about the diagonal should sum to 100 (for the percent table).

Ballots used in condorcet calculation have election rules applied to them.

Returns:: Tuple containing count table, percent table, and name of condorcet winner.
Return type:: Tuple[Union[pd.DataFrame, Optional[str]]]

get_crossover_tables() → Tuple[DataFrame]¶

Table describing co-ranking patterns between candidates. For each subset of ballots organized by first choice candidate, one in each row of the table, the frequency with which all candidates appear in the top 3 ranks of ballots in that subset is calculated. For this table, ballots are used without any contest rules applied.

Returns:: Tuple of two pandas dataframes. The first contains counts, the second percentages.
Return type:: Tuple[pd.DataFrame]

get_cumulative_ranking_tables() → Tuple[DataFrame]¶

Return cumulative ranking tables. Rows are candidate names and columns are rank numbers. Reading across columns, the tables show the accumulating count/percentage of ballots that marked a candidate as more ranks are considered. The final column shows the count/percentage of ballots that never marked the candidate. Ballots used for calculation have election rules applied to them.

Returns:: Tuple containing count table and percentage table
Return type:: Tuple[pd.DataFrame]

get_cvr_dict(rule_set_name: str | None = None, disaggregate: bool = True) → Dict[str, List]¶

Return CVR as dictionary of lists.

Parameters:

rule_set_name (Optional[str], optional) – Name of modified CVR to return, defaults to None. If None, return default CVR.
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

CVR as dictionary of lists.

Return type:

Dict[str, List]

get_cvr_table(table_format: str = 'rank', disaggregate: bool = True) → DataFrame¶

Return the cvr as pandas dataframe. Two format options are available ‘rank’ or ‘candidate’.

Parameters:

table_format (str, optional) – Two choices for the format of CVR table, “rank” or “candidate”. One ballot per row. Rank format uses rank number labels as column headers with candidate names in row cells. Candidate format puts candidate names as column headers with rank position placed in row cells. Defaults to “rank”
disaggregate (bool, optional) – If True, the interally aggregated CVR is disaggregated back to contain the same number of ballots as when it was parsed, defaults to True.

Raises:

RuntimeError – raised if an invalid table_format is passed as an argument.

Returns:

Dataframe containing CVR.

Return type:

pd.DataFrame

get_final_ranks(tabulation_num: int = 1, disaggregate: bool = True) → List[List]¶

Return a list of ballot ranks after tabulation. Each set of ranks is a list. Ballots marks will be excluded if they violate election rules or if they are the mark of a candidate eliminated during tabulation.

Parameters:

tabulation_num (int, optional) – Tabulation number from which to get initial ranks, defaults to 1
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

List of lists of candidates/marks.

Return type:

List[List[str]]

get_final_weight_distrib(tabulation_num: int = 1, disaggregate: bool = True) → List[List[Tuple[str, Decimal]]]¶

Return a list of ballot weight distributions describing how much of each ballot was allocated to a winner, finalist, or exhausted. Each set of weight distributions is a ranking-weight tuple pair. Tuple pairs appear in order of weight allocation throughout the tabulation process. Ballots that exhausted have the string ‘exhaust’ in the ranking position of the tuple. Each weight distribution should sum to its original weight at the beginning of the tabulation.

Parameters:

tabulation_num (int, optional) – Tabulation number, defaults to 1
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

List of ballot weight distributions.

Return type:

List[List[Tuple[str, decimal.Decimal]]]

get_final_weights(tabulation_num: int = 1, disaggregate: bool = True) → List[Decimal]¶

Return a list of ballot weights after tabulation.

Parameters:

tabulation_num (int, optional) – Tabulation from which to return final weights, defaults to 1
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

List of weights

Return type:

List[decimal.Decimal]

get_first_choice_to_finalist_table(tabulation_num: int = 1) → DataFrame¶

Create a pandas dataframe describing the first choice candidate distribution and which finalist candidate those ballots ended the tabulation allocated to.

Parameters:: tabulation_num (int, optional) – tabulation number, defaults to 1
Returns:: table
Return type:: pd.DataFrame

get_first_second_tables() → Tuple[DataFrame]¶

Return pandas dataframes containing first and second choice candidate distributions across ballots. The first row of the table contains the first choice distribution. The following rows in each column indicate the second choice distribution for only the ballots in each first choice ballot pile. Percentages in the first row should sum to 100, and each column below the first row should sum to 100. Ballots used for calculation have election rules applied to them.

Three versions of the dataframe are returned: one containing ballot counts and two containing ballot percentages. Two percentage dataframes are included, one with an exhaustion category for second choices and one without.

Returns:: Tuple containing count table, percentage table, and percentage table without exhausted second choices
Return type:: Tuple[pd.DataFrame]

get_initial_ranks(tabulation_num: int = 1, disaggregate: bool = True) → List[List[str]]¶

Ballots prior to first round tabulation, after election rules applied.

Parameters:

tabulation_num (int, optional) – Tabulation number from which to get initial ranks, defaults to 1
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

List of lists of candidates/marks.

Return type:

List[List[str]]

get_initial_weights(tabulation_num: int = 1, disaggregate: bool = True) → List[Decimal]¶

Return a list of ballot weights prior to specified tabulation.

Parameters:

tabulation_num (int, optional) – Tabulation from which to return final weights, defaults to 1
disaggregate (bool, optional) – If True, the internally aggregated CVR is disaggregated before return. Defaults to True.

Returns:

List of weights at the beginning of tabulation.

Return type:

List[decimal.Decimal]

get_rank_usage_table() → DataFrame¶

Table describing rank usage patterns. Mean rankings used and distribution of valid rankings used is provided for all ballots (excluding undervotes and ballots starting with overvotes) as well as ballots separated by first choice candidate. Ballots starting with overvotes are excluded because of the inability to assign them to a first choice candidate category. For this table, ballots are used without any contest rules applied. Skipped ranks, overvotes, and duplicate rankings are not counted valid rankings.

Returns:: Rank usage dataframe
Return type:: pd.DataFrame

get_round_by_round_dict(tabulation_num: int = 1) → Dict¶

Create a dictionary containing election round by round information that matches the nesting structure of RCVIS upload format.

Parameters:: tabulation_num (int, optional) – tabulation number, defaults to 1
Returns:: Dictionary containing election round by round details
Return type:: Dict

get_round_by_round_table(tabulation_num: int = 1) → DataFrame¶

Create a table containing round by round details for the tabulation.

Parameters:: tabulation_num (int, optional) – tabulation number, defaults to 1
Returns:: round by round table
Return type:: pd.DataFrame

get_round_tally_dict(round_num: int, tabulation_num: int = 1, only_round_active_candidates: bool = False) → Dict[str, Decimal]¶

Return a dictionary containing candidate names as keys and vote counts as values.

Parameters:

round_num (int) – Round number for which to return vote counts for.
tabulation_num (int, optional) – Tabulation number from which to index round number, defaults to 1
only_round_active_candidates (bool, optional) – If True, only candidate totals for candidates active in the specified round are returned. Otherwise, all candidates are returned. Defaults to False

Returns:

Dictionary containing candidate names and vote totals.

Return type:

Dict[str, decimal.Decimal]

get_round_tally_tuple(round_num: int, tabulation_num: int = 1, only_round_active_candidates: bool = False) → List[Tuple[str, Decimal]]¶

Return a list of (candidate name, candidate vote count) tuples for round in tabulation. Tuples are sorted in descending order by vote count and then by ascending order by candidate name.

Parameters:

round_num (int) – Round number for which to return vote counts for.
tabulation_num (int, optional) – Tabulation number from which to index round number, defaults to 1
only_round_active_candidates (bool, optional) – If True, only candidate totals for candidates active in the specified round are returned. Otherwise, all candidates are returned. Defaults to False

Returns:

List of tuples containing candidate names and vote totals.

Return type:

List[Tuple[str, decimal.Decimal]]

get_round_transfer_dict(round_num: int, candidate_netted: bool = True, tabulation_num: int = 1) → Dict[str, Decimal] | Dict[str, Dict[str, Decimal]]¶

Return a dictionary describing vote transfers from round specified. Keys are candidate names. If candidate_netted is True, an extra key ‘exhaust’ is included and dictionary values are the net vote counts flowing to/from a candidate. Else, values are each another dictionary containing candidate names, plus ‘exhaust’, as keys and vote flows from the outer key candidate to the inner key candidate.

Parameters:

round_num (int) – Round number to get transfer info for
candidate_netted (bool, optional) – If True, dictionary values are net votes flows to/from a candidate. If False, dictionary values are also dictionaries containing flows broken down by candidate. Defaults to True
tabulation_num (int, optional) – Tabulation in which to index round number, defaults to 1

Returns:

Dictionary of transfer vote flows.

Return type:

Union[Dict[str, decimal.Decimal], Dict[str, Dict[str, decimal.Decimal]]]

get_stats(keep_decimal_type: bool = False, add_split_stats: bool = False, add_id_info: bool = True) → List[DataFrame]¶

Obtain the default statistics calculated by the RCV object, these include statistics calculcated by CastVoteRecord object. Statistics are returned in pandas dataframe objects. One dataframe is returned for each tabulation in the election.

Parameters:

keep_decimal_type (bool, optional) – Return the decimal class objects used by internal calculations rather than converting them to floats, defaults to False
add_split_stats (bool, optional) – Add extra statistics calculated for each category contained in split_fields columns passed to constructor, defaults to False
add_id_info (bool, optional) – Include contest ID details to returned dataframe, defaults to True

Returns:

A single row dataframe with statistics organized in multiple columns. If split_fields are passed, then extra rows are added for each category in the split columns. One dataframe is returned per tabulation.

Return type:

List[pd.DataFrame]

static get_variant_group(rcv_obj: Type[RCV]) → str¶

Convenience function for batch script. Categorizes an election as single winner or multi winner based on the number of winners.

Returns:: String describing the election as single winner or multi winner.
Return type:: str

static get_variant_name(rcv_obj: Type[RCV]) → str¶

Convenience function for batch script. Returns name of RCV class.

Returns:: Name of class of object passed
Return type:: str

get_win_threshold(tabulation_num: int = 1) → int | float | str | Decimal¶

Win threshold for a given tabulation expressed as a number of votes. If threshold is not static, string ‘dynamic’ should be returned.

Parameters:: tabulation_num (int, optional) – Tabulation number, defaults to 1
Returns:: Vote threshold a candidate needs to cross in order to win
Return type:: Union[int, float, decimal.Decimal, str]

get_winner_final_pile_rank_distribution_table(tabulation_num: int = 1) → DataFrame | None¶

Measure where winners ranked on ballots that ended up in their final pile. Only applicable for single winner elections.

Parameters:: tabulation_num (int, optional) – Tabulation number (only applies to Sequential), defaults to 1
Returns:: A single row dataframe with contest details and counts of winner final ballots across ranking positions.
Return type:: Optional[pd.DataFrame]

n_rounds(tabulation_num: int = 1) → int¶

Return the number of rounds used in tabulation, for a given tabulation in the election.

Parameters:: tabulation_num (int, optional) – Tabulation number, defaults to 1
Returns:: Number of rounds in the tabulation
Return type:: int

n_tabulations() → int¶

Returns number of tabulations in election

Returns:: Number of tabulations in election
Return type:: int

static write_annotated_cvr_table(cvr: Type[CastVoteRecord], save_dir: str | Path | None = None) → None¶

Static method wrapper around get_annotated_cvr_table object method that writes the table out to save_dir. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out table.

static write_condorcet_tables(cvr: Type[CastVoteRecord], save_dir: str | Path | None = None) → None¶

Static method wrapper around get_condorcet_tables object method that writes the table out to save_dir. Two tables are written out, one containing ballot counts and one with percentages. File names used follow the pattern “{save_dir}/condorcet/{jurisdiction}_{date OR year}_{office}_{‘count’ OR ‘percent’}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out tables.

static write_crossover_tables(cvr: Type[CastVoteRecord], save_dir: str | Path | None = None) → None¶

Static method wrapper around get_crossover_tables object method that writes the table out to save_dir. Two tables are written out, one containing ballot counts and one with percentages. File names used follow the pattern “{save_dir}/opponent_crossover/{jurisdiction}_{date OR year}_{office}_{‘count’ OR ‘percent’}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out tables.

static write_cumulative_ranking_tables(cvr: Type[CastVoteRecord], save_dir: str | Path) → None¶

Static method wrapper around get_cumulative_ranking_tables object method that writes tables out to save_dir. Two tables are written out, one containing ballot counts and one with percentages. File names used follow the pattern “{save_dir}/cumulative_ranking/{jurisdiction}_{date OR year}_{office}_{‘count’ OR ‘percent’}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out tables.

static write_cvr_table(cvr: Type[CastVoteRecord], save_dir: str | Path, table_format: str = 'rank') → None¶

Static method wrapper around get_cvr_table object method that writes CVR table out to save_dir. File name used follows the pattern “{save_dir}/{jurisdiction}_{date OR year}_{office}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out CVR table.
table_format (str, optional) – Format in which to write out CVR. Either “rank” or “candidate”. One row per ballot. “rank” format has rank numbers as column names with candidate names in row cells. “candidate” format has candidate names as column names with rank numbers filling in row cells. Defaults to “rank”.

static write_first_choice_to_finalist_table(rcv_obj: Type[RCV], save_dir: str | Path | None = None) → None¶

Wrapper for RCV.get_first_choice_to_finalist_table that writes out the table for each tabulation to path ‘{save_dir}/first_choice_to_finalist/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv’

Parameters:

rcv_obj (Type[RCV]) – RCV object or RCV subclass object
save_dir (Union[str, pathlib.Path], optional) – Directory path to write tables to, defaults to None

static write_first_second_tables(cvr: Type[CastVoteRecord], save_dir: str | Path | None = None) → None¶

Static method wrapper around get_first_second_tables object method that writes tables out to save_dir. Three tables are written out, one containing ballot counts, one with percentages, and another with percentages excluding exhausted ballots. File names used follow the pattern “{save_dir}/first_second_choices/{jurisdiction}_{date OR year}_{office}_{‘count’ OR ‘percent’ OR ‘percent_no_exhaust’}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out tables.

static write_rank_usage_table(cvr: Type[CastVoteRecord], save_dir: str | Path | None = None) → None¶

Static method wrapper around get_rank_usage_table object method that writes the table out to save_dir. File names used follow the pattern “{save_dir}/rank_usage/{jurisdiction}_{date OR year}_{office}.csv”. All non-alphanumeric characters, besides underscores, are removed from file name components. Contest date is in mm/dd/yyyy format.

Parameters:

cvr (Type[CastVoteRecord]) – CastVoteRecord object.
save_dir (Union[str, pathlib.Path]) – Directory in which to write out table.

static write_round_by_round_json(rcv_obj: Type[RCV], save_dir: Path | str) → None¶

Wrapper for RCV.get_round_by_round_dict that writes out the dictionary for each tabulation to path ‘{save_dir}/round_by_round_json/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv’

Parameters:

rcv_obj (Type[RCV]) – RCV object
save_dir (Union[pathlib.Path, str]) – Path to create “round_by_round_json” directory and write out json files.

static write_round_by_round_table(rcv_obj: Type[RCV], save_dir: str | Path | None = None) → None¶

Wrapper for RCV.get_round_by_round_table that writes out the table for each tabulation to path ‘{save_dir}/round_by_round_table/{jurisdiction}_{date OR year}_{office}_tab{tabulation_num}.csv’

Parameters:

rcv_obj (Type[RCV]) – RCV object or RCV subclass object
save_dir (Union[str, pathlib.Path], optional) – Directory path to write tables to, defaults to None