Statistics¶

cvr.base.CastVoteRecord objects and RCV variant objects all have a get_stats() function which returns a series of statistics that are computed for each election by default. Those stastistics are described below.

CastVoteRecord stastistics¶

Function¶

cvr.base.CastVoteRecord_stats.get_stats(self, keep_decimal_type: bool = False, add_split_stats: bool = False, add_id_info: bool = True) → List[DataFrame]

Obtain the default statistics calculated by the CastVoteRecord object. Statistics are returned in pandas dataframe object.

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 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]

Statistics¶

n_candidates - number of candidates excluding WRITEIN marks

rank_limit - number of rankings allowed on the CVR.

restrictive_rank_limit - True if number of candidates - number of ranks is greater than 1.

(All stats below are also able to be calcualted by group (e.g. by precinct))

first_round_overvote - number of ballots in which the first non-skipped mark is an overvote.

ranked_single - number of ballot which only contained 1 valid rankings.

ranked_multiple - number of ballot which only contained more than 1 valid rankings.

ranked_3_or_more - number of ballot which only contained more than 2 valid rankings.

total_fully_ranked - number of ballots that have EITHER validly used all rankings on the ballot OR validly ranked every non-writein candidate.

includes_overvote_ranking - number of ballots with an overvote ranking.

includes_duplicate_ranking - number of ballots with a duplicate ranking.

includes_skipped_ranking - number of ballots with a skipped ranking (that is then followed by at least 1 non-skipped ranking).

total_irregular - total number of ballots with EITHER a duplicate ranking OR skipped ranking OR overvote.

total_ballots - total number of ballots

total_undervote - total number of ballots that contain all skipped rankings.

mean_rankings_used - mean number of non-undervote rankings used.

RCV stastistics¶

Function¶

rcv.base.RCV.get_stats(self, 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]

Statistics¶

number_of_winners - number of winners in the contest.

number_of_rounds - number of rounds in the tabulation.

winner - tabulation winners.

first_round_winner_vote - If more than 1 winner in tabulation, then None. Else, the vote total for the tabulation winner in the first round.

first_round_winner_percent - If more than 1 winner in tabulation, then None. Else, the vote percent for the tabulation winner in the first round.

first_round_winner_place - If more than 1 winner in tabulation, then None. Else, the place the tabulation winner finished in the the first round.

final_round_winner_vote - If more than 1 winner in tabulation, then None. Else, the vote total for the tabulation winner in the final round.

final_round_winner_percent - If more than 1 winner in tabulation, then None. Else, the vote percent for the tabulation winner in the final round.

final_round_winner_votes_over_first_round_active - If more than 1 winner in tabulation, then None. Else, the vote total for the tabulation winner in the final round divided by the number of active ballots in the first round.

condorcet - If more than 1 winner in tabulation, then None. Else, True if the winner is the condorcet winner, else False.

come_from_behind - If more than 1 winner in tabulation, then None. Else, True if the winner was not in first place in the first round, else False.

ranked_winner - If more than 1 winner in tabulation, then None. Else, the number of ballots that ranked the winner.

win_threshold - If less than 2 winner in tabulation, then None. Else, the static threshold needed to win.

ranked_winner - If more than 1 winner in tabulation, then None. Else, the number of ballots that ranked the winner.

winners_consensus_value - The number of ballots that rank any winner in their top 3 (after rules applied).

first_round_active_votes - The number of votes active in the first round.

final_round_active_votes - The number of votes active in the final round.

(All stats below are also able to calcualted by group (e.g. by precinct))

total_pretally_exhausted - The number of ballots that were not undervotes, yet were not active in the first round.

total_posttally_exhausted - The number of ballots that exhausted after the first round.

total_posttally_exhausted_by_overvote - The number of ballots that exhausted due to an overvote after the first round.

total_posttally_exhausted_by_skipped_rankings - The number of ballots that exhausted due to repeated skipped rankings after the first round.

total_posttally_exhausted_by_duplicate_rankings - The number of ballots that exhausted due to duplicate candidate rankings after the first round.

total_posttally_exhausted_by_rank_limit - The number of ballots that exhausted after the first round. Only applied to contest with a restrictive rank limit. The count towards this category ballots must either use all ranks OR at least use the last ranking.

total_posttally_exhausted_by_rank_limit_fully_ranked - Subset of total_posttally_exhausted_by_rank_limit which ranked all candidates or used all rankings validly.

total_posttally_exhausted_by_rank_limit_partially_ranked - Subset of total_posttally_exhausted_by_rank_limit which used the final ranking on a rank restricted ballot.

total_posttally_exhausted_by_abstention - The number of ballots that exhausted after the first round which do not fall into the categories above.