API Reference 

votekit.ballot_generator.ic_profile_generator(candidates: Sequence[str], number_of_ballots: int, max_ballot_length: int | None = None, allow_short_ballots: bool = False) → RankProfile

Impartial Culture model where each ballot is equally likely. Equivalent to the ballot simplex with an alpha value of infinity.

Parameters:

candidates (Sequence[str]) – The list of candidates in the election.
number_of_ballots (int) – The number of ballots to generate for the profile.
max_ballot_length (Optional[int]) – Maximum length of each ballot. If None, defaults to the number of candidates.
allow_short_ballots (bool, optional) – Whether to allow short ballots. Defaults to False.

Returns:

The generated preference profile

Return type:

votekit.ballot_generator.name_bt_profile_generator(config: BlocSlateConfig, *, group_ballots=True) → RankProfile

Generate a preference profile using the name-BradleyTerry model.

The probability of sampling the ranking \(X>Y>Z\) is proportional to \(P(X>Y)*P(X>Z)*P(Y>Z)\). These individual probabilities are based on the preference interval: :math: P(X>Y) = x/(x+y).

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profile.

Return type:

votekit.ballot_generator.name_bt_profile_generator_using_mcmc(config: BlocSlateConfig, *, group_ballots=True, verbose: bool = False, burn_in_time: int = 0, chain_length: int | None = None) → RankProfile

Generate a preference profile using MCMC sampling from the name-BradleyTerry model.

Parameters:: config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.

Kwargs:

group_ballots (bool): If True, group identical ballots in the returned profile and: set the weight accordingly. Defaults to True.

verbose (bool): If True, print the acceptance ratio of the chain. Defaults to False. burn_in_time (int): the number of ballots discarded in the beginning of the chain.

Defaults to 0.

chain_length (Optional[int]): the length of the Markov Chain. Ballots are subsampled every: chain_length//n_ballots steps from the chain until the desired number of ballots is reached. Defaults to None which sets the chain_length to the number of ballots in the config.

Returns:: Generated preference profile.
Return type:: RankProfile

votekit.ballot_generator.name_bt_profiles_by_bloc_generator(config: BlocSlateConfig, *, group_ballots=True) → dict[str, RankProfile]

Generate preference profiles by bloc using the name-BradleyTerry model.

The probability of sampling the ranking \(X>Y>Z\) is proportional to \(P(X>Y)*P(X>Z)*P(Y>Z)\). These individual probabilities are based on the preference interval: :math: P(X>Y) = x/(x+y).

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profiles by bloc.

Return type:

dict[str, RankProfile]

votekit.ballot_generator.name_bt_profiles_by_bloc_generator_using_mcmc(config: BlocSlateConfig, *, group_ballots=True, verbose: bool = False, burn_in_time: int = 0, chain_length: int | None = None) → dict[str, RankProfile]

Generate a preference profile dictionary by bloc using MCMC sampling from the name-BradleyTerry model.

Parameters:: config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.

Kwargs:

group_ballots (bool): If True, group identical ballots in the returned profile and: set the weight accordingly. Defaults to True.

verbose (bool): If True, print the acceptance ratio of the chain. Defaults to False. burn_in_time (int): the number of ballots discarded in the beginning of the chain.

Defaults to 0.

chain_length (Optional[int]): the length of the Markov Chain. Ballots are subsampled every: chain_length//n_ballots steps from the chain until the desired number of ballots is reached. Defaults to None which sets the chain_length to the number of ballots in the config.

Returns:: Generated preference profiles by bloc.
Return type:: dict[str, RankProfile]

votekit.ballot_generator.name_cumulative_ballot_generator_by_bloc(config: BlocSlateConfig, *, total_points: int | None = None, group_ballots: bool = True) → dict[str, ScoreProfile]

Generates a dictionary mapping bloc names to ScoreProfiles using the name-Cumulative model.

This model samples with replacement from a combined preference interval and counts candidates with multiplicity.

Parameters:: config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.

Kwargs:

total_points (Optional[int]): The total number of points to distribute among candidates.: If None, defaults to the number of candidates in the configuration. Defaults to None.
group_ballots (bool): If True, groups identical ballots in the resulting profile.: Defaults to True.

Returns:

A dictionary whose keys are bloc strings and values are: ScoreProfile objects representing the generated ballots for each bloc.

Return type:

dict[str, ScoreProfile]

votekit.ballot_generator.name_cumulative_profile_generator(config: BlocSlateConfig, *, total_points: int | None = None, group_ballots: bool = True) → ScoreProfile

Generates a ScoreProfile using the name-Cumulative.

This model samples with replacement from a combined preference interval and counts candidates with multiplicity.

Parameters:: config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.

Kwargs:

total_points (Optional[int]): The total number of points to distribute among candidates.: If None, defaults to the number of candidates in the configuration. Defaults to None.
group_ballots (bool): If True, groups identical ballots in the resulting profile.: Defaults to True.

Returns:: A ScoreProfile object representing the generated ballots.
Return type:: ScoreProfile

votekit.ballot_generator.name_pl_profile_generator(config: BlocSlateConfig, *, group_ballots: bool = True) → RankProfile

Generates a merged preference profile using the name-Plackett-Luce model.

The Plackett-Luce model samples without replacement from each preference interval for each bloc of voters. These profiles are then merged into a single profile.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Merged RankProfile object generated by the model.

Return type:

votekit.ballot_generator.name_pl_profiles_by_bloc_generator(config: BlocSlateConfig, *, group_ballots: bool = True) → dict[str, RankProfile]

Generates a dictionary mapping bloc names to preference profiles by bloc using the name-Plackett-Luce model.

The Plackett-Luce model samples without replacement from each preference interval for each bloc of voters.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Dictionary whose keys are bloc strings and values are: RankProfile objects generated by the model for each bloc.

Return type:

dict[str, RankProfile]

votekit.ballot_generator.onedim_spacial_profile_generator(candidates: Sequence[str], number_of_ballots: int) → RankProfile

Generate a 1D spatial rank profile.

Voters and candidates are sampled from normal distributions on a line. Each ballot ranks candidates by absolute distance from the voter.

Parameters:

candidates (Sequence[str]) – Candidate names used in each generated ballot.
number_of_ballots (int) – The number of ballots to generate.

Returns:

A ranked preference profile object.

Return type:

votekit.ballot_generator.slate_bt_profile_generator(config: BlocSlateConfig, *, group_ballots=True) → RankProfile

Generate a preference profile using the name-BradleyTerry model.

This model first samples a ballot type (e.g. AABABB) according the the Bradley-Terry model using the cohesion parameters for each slate and the candidate counts of those slates (so the utilities of each of the candidates in a slate are assumed to be uniform in this stage).

Once the ballot type is sampled, the candidate names for each of the positions is filled out by sampling without replacement within each slate according to the preference interval of that slate in the given bloc (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profile.

Return type:

votekit.ballot_generator.slate_bt_profile_generator_using_mcmc(config: BlocSlateConfig, *, group_ballots=True) → RankProfile

Generate a ranked preference profile using the slate-BradleyTerry model.

This model is mainly useful when then number of possible ballot types is too large to compute the full probability distribution on the present hardware (e.g. more than 12! possible ballot types).

The MCMC version of this model uses a Markov Chain Monte Carlo method to sample ballot types according to the slate-BradleyTerry model. After selecting a seed ballot, the model proposes swaps of adjacent slates in the ballot type and accepts or rejects the swap according to the ratio of the cohesion parameters of the two slates being swapped within a given block.

Once the ballot type is sampled, the candidate names for each of the positions is filled out by sampling without replacement within each slate according to the preference interval of that slate in the given bloc (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profile.

Return type:

votekit.ballot_generator.slate_bt_profiles_by_bloc_generator(config: BlocSlateConfig, *, group_ballots=True) → dict[str, RankProfile]

Generate a dictionary mapping bloc names to ranked preference profiles using the slate-BradleyTerry model.

This model first samples a ballot type (e.g. AABABB) according the the Bradley-Terry model using the cohesion parameters for each slate and the candidate counts of those slates (so the utilities of each of the candidates in a slate are assumed to be uniform in this stage).

Once the ballot type is sampled, the candidate names for each of the positions is filled out by sampling without replacement within each slate according to the preference interval of that slate in the given bloc (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profiles by bloc.

Return type:

dict[str, RankProfile]

votekit.ballot_generator.slate_bt_profiles_by_bloc_generator_using_mcmc(config: BlocSlateConfig, *, group_ballots=True) → dict[str, RankProfile]

Generate a dictionary mapping bloc names to ranked preference profiles using the slate-BradleyTerry model.

This model is mainly useful when then number of possible ballot types is too large to compute the full probability distribution on the present hardware (e.g. more than 12! possible ballot types).

The MCMC version of this model uses a Markov Chain Monte Carlo method to sample ballot types according to the slate-BradleyTerry model. After selecting a seed ballot, the model proposes swaps of adjacent slates in the ballot type and accepts or rejects the swap according to the ratio of the cohesion parameters of the two slates being swapped within a given block.

Once the ballot type is sampled, the candidate names for each of the positions is filled out by sampling without replacement within each slate according to the preference interval of that slate in the given bloc (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Generated preference profiles by bloc.

Return type:

dict[str, RankProfile]

votekit.ballot_generator.slate_pl_profile_generator(config: BlocSlateConfig, *, group_ballots: bool = True) → RankProfile

Generates a merged preference profile using the slate-Plackett-Luce model.

This model first samples a ballot type by flipping a cohesion parameter weighted coin. It then fills out the ballot type via sampling without replacement from the preference interval (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Merged RankProfile object generated by the model.

Return type:

votekit.ballot_generator.slate_pl_profiles_by_bloc_generator(config: BlocSlateConfig, *, group_ballots: bool = True) → dict[str, RankProfile]

Generates a dictionary mapping bloc names to preference profiles using the slate-Plackett-Luce model.

This model first samples a ballot type by flipping a cohesion parameter weighted coin. It then fills out the ballot type via sampling without replacement from the preference interval (i.e. according to the name-Plackett-Luce model).

Slates with zero cohesion for the given bloc are randomly permuted at the end of the ballot. Candidates with zero support are randomly permuted at the end of the candidate ordering.

Parameters:

config (BlocSlateConfig) – Configuration object containing all necessary parameters for working with a bloc-slate ballot generator.
group_ballots (bool) – If True, group identical ballots in the returned profile and set the weight accordingly. Defaults to True.

Returns:

Dictionary whose keys are bloc strings and values are: RankProfile objects generated by the model for each bloc.

Return type:

dict[str, RankProfile]

votekit.ballot_generator.spacial_profile_and_positions_generator(number_of_ballots: int, candidates: list[str], voter_dist: ~typing.Callable[[...], ~numpy.ndarray] = <bound method RandomState.uniform of RandomState(MT19937)>, voter_dist_kwargs: ~typing.Dict[str, ~typing.Any] | None = None, candidate_dist: ~typing.Callable[[...], ~numpy.ndarray] = <bound method RandomState.uniform of RandomState(MT19937)>, candidate_dist_kwargs: ~typing.Dict[str, ~typing.Any] | None = None, distance: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function euclidean_dist>) → Tuple[RankProfile, dict[str, ndarray], ndarray]

Generate a spatial rank profile and sampled positions.

Samples voter and candidate positions in a metric space, then ranks each ballot by candidate distance from the sampled voter position.

Example

profile, cand_pos, voter_pos = spacial_profile_and_positions_generator(: number_of_ballots=100, candidates=[“A”, “B”, “C”], voter_dist=np.random.normal, voter_dist_kwargs={“loc”: 0.0, “scale”: 1.0, “size”: 2}, candidate_dist=np.random.uniform, candidate_dist_kwargs={“low”: -1.0, “high”: 1.0, “size”: 2},

)

Parameters:

number_of_ballots (int) – The number of ballots to generate.
candidates (list[str]) – Candidate names used when building rankings.
voter_dist (Callable[..., np.ndarray], optional) – Distribution sampler used to draw each voter position. Defaults to np.random.uniform.
voter_dist_kwargs (Optional[Dict[str, Any]], optional) – Keyword arguments passed to voter_dist for each sample. If None, uses {"low": 0.0, "high": 1.0, "size": 2.0} for np.random.uniform and {} for other distributions.
candidate_dist (Callable[..., np.ndarray], optional) – Distribution sampler used to draw each candidate position. Defaults to np.random.uniform.
candidate_dist_kwargs (Optional[Dict[str, Any]], optional) – Keyword arguments passed to candidate_dist for each sample. If None, uses {"low": 0.0, "high": 1.0, "size": 2.0} for np.random.uniform and {} for other distributions.
distance (Callable[[np.ndarray, np.ndarray], float], optional) – Distance function used to compare voter and candidate positions. Defaults to euclidean_dist.

Returns:

A tuple containing the preference profile object, a dictionary with each candidate’s position in the metric space, and a matrix where each row is a single voter’s position in the metric space.

Return type:

Tuple[RankProfile, dict[str, numpy.ndarray], numpy.ndarray]

Cleaning 

votekit.cleaning.clean_rank_profile(profile: RankProfile, clean_ranking_func: Callable[[tuple], tuple], remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = True) → CleanedRankProfile

Allows user-defined cleaning rules for RankProfile. Input function that applies modification to ranking portion of the df, not weight or voterset.

Parameters:

profile (RankProfile) – A RankProfile to clean.
clean_ranking_func (Callable[[tuple], tuple]) – Function that takes the ranking portion of a row of the profile df and returns an altered ranking.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking and no scores as a result of the cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of the cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the original profile in the new profile. If False, uses only candidates who receive votes. Defaults to True.

Returns:

A cleaned RankProfile.

Return type:

Raises:

ProfileError – Profile must only contain ranked ballots.

votekit.cleaning.clean_score_profile(profile: ScoreProfile, clean_score_func: Callable[[tuple], tuple], remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = True) → CleanedScoreProfile

Allows user-defined cleaning rules for ScoreProfile. Cleaning function can only be applied to the score section of the dataframe, not the weight or voter set.

Parameters:

profile (ScoreProfile) – A ScoreProfile to clean.
clean_score_func (Callable[[tuple], tuple]) – Function that takes the score portion of a row of the profile df and returns an altered score.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no no scores as a result of the cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of the cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the original profile in the new profile. If False, uses only candidates who receive votes. Defaults to True.

Returns:

A cleaned ScoreProfile.

Return type:

CleanedScoreProfile

Raises:

ProfileError – Profile must only contain ranked ballots.

votekit.cleaning.condense_rank_ballot(ballot: RankBallot) → RankBallot

Given a ballot, removes any empty ranking positions and moves up any lower ranked candidates.

Parameters:: ballot (RankBallot) – Ballot to condense.
Returns:: Condensed ballot.
Return type:: RankBallot

votekit.cleaning.condense_rank_profile(profile: RankProfile, remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = True) → CleanedRankProfile

Given a ranked profile, removes any empty frozensets from the rankings and condenses the resulting ranking. If a ranking only has trailing empty positions, the condensed ranking is considered equivalent. For example, (A,B,{},{}) is mapped to (A,B) but considered unaltered since the ranking did not change.

Wrapper for clean_rank_profile that does some extra processing to ensure condensed ranking equivalence is handled correctly.

Parameters:

profile (RankProfile) – Profile to remove repeated candidates from.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking or scores as a result of cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the original profile in the new profile. If False, uses only candidates who receive votes. Defaults to True.

Returns:

A cleaned RankProfile.

Return type:

votekit.cleaning.remove_and_condense_rank_profile(removed: str | list, profile: RankProfile, remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = False) → CleanedRankProfile

Given a ranked profile, remove the given candidate(s) and condense the resulting rankings. If a ranking only has trailing empty positions, the condensed ranking is considered equivalent. For example, (A,B,{},{}) is mapped to (A,B) but considered unaltered since the ranking did not change.

This function is intended to save computational time in election methods, where removing and condensing happen frequently. Researches interested in the difference between removing and condensing should use remove_cand and condense_profile in series.

Wrapper for clean_rank_profile that does some extra processing to ensure the candidate list is handled correctly, and that ballot equivalence is checked.

Parameters:

removed (Union[str, list]) – Candidate or list of candidates to be removed.
profile (RankProfile) – Profile to remove repeated candidates from.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking or scores as a result of cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the orginal profile in the new profile. If False, takes the original candidate list and removes the candidate(s) given in removed, but preserves all others. Defaults to False.

Returns:

A cleaned RankProfile.

Return type:

votekit.cleaning.remove_cand_rank_ballot(removed: str | list, ballot: RankBallot) → RankBallot

Removes specified candidate(s) from ballot. Does not condense the resulting ballot.

Parameters:

removed (Union[str, list]) – Candidate or list of candidates to be removed.
ballot (RankBallot) – Ballot to remove candidates from.

Returns:

Ballot with candidate(s) removed.

Return type:

RankBallot

votekit.cleaning.remove_cand_rank_profile(removed: str | list, profile: RankProfile, remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = False) → CleanedRankProfile

Given a ranked profile, remove the given candidate(s) from the ballots. Does not condense the resulting ballots.

Wrapper for clean_rank_profile that does some extra processing to ensure the candidate list is handled correctly.

Parameters:

removed (Union[str, list]) – Candidate or list of candidates to be removed.
profile (RankProfile) – Profile to remove candidates from.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking or scores as a result of cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the orginal profile in the new profile. If False, takes the original candidate list and removes the candidate(s) given in removed, but preserves all others. Defaults to False.

Returns:

A cleaned RankProfile.

Return type:

Raises:

ProfileError – Profile must only contain ranked ballots.

votekit.cleaning.remove_cand_score_ballot(removed: str | list, ballot: ScoreBallot) → ScoreBallot

Removes specified candidate(s) from ballot.

Parameters:

removed (Union[str, list]) – Candidate or list of candidates to be removed.
ballot (ScoreBallot) – Ballot to remove candidates from.

Returns:

Ballot with candidate(s) removed.

Return type:

ScoreBallot

votekit.cleaning.remove_cand_score_profile(removed: str | list, profile: ScoreProfile, remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = False) → CleanedScoreProfile

Given a score profile, remove the given candidate(s) from the ballots.

Wrapper for clean_score_profile that does some extra processing to ensure the candidate list is handled correctly.

Not as fast as removing the candidate columns directly, but tracks more information about which ballots were adjusted.

Parameters:

removed (Union[str, list]) – Candidate or list of candidates to be removed.
profile (ScoreProfile) – Profile to remove candidates from.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking or scores as a result of cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the orginal profile in the new profile. If False, takes the original candidate list and removes the candidate(s) given in removed, but preserves all others. Defaults to False.

Returns:

A cleaned ScoreProfile.

Return type:

CleanedScoreProfile

Raises:

ProfileError – Profile must only contain score ballots.

votekit.cleaning.remove_repeat_cands_rank_ballot(ballot: RankBallot) → RankBallot

Given a ballot, if a candidate appears multiple times on a ballot, keep the first instance, and remove any further instances. Does not condense the ballot. Only works on ranking ballots, not score ballots.

Parameters:

ballot (RankBallot) – Ballot to remove repeated candidates from.

Returns:

Ballot with duplicate candidate(s) removed.

Return type:

RankBallot

Raises:

TypeError – Ballot must only have rankings, not scores.
TypeError – Ballot must have rankings.

votekit.cleaning.remove_repeat_cands_rank_profile(profile: RankProfile, remove_empty_ballots: bool = True, remove_zero_weight_ballots: bool = True, retain_original_candidate_list: bool = True) → CleanedRankProfile

Given a profile, if a candidate appears multiple times on a ballot, keep the first instance and remove any further instances. Does not condense any empty rankings as as result. Only works on ranking ballots, not score ballots.

Wrapper for clean_rank_profile.

Parameters:

profile (RankProfile) – Profile to remove repeated candidates from.
remove_empty_ballots (bool, optional) – Whether or not to remove ballots that have no ranking or scores as a result of cleaning. Defaults to True.
remove_zero_weight_ballots (bool, optional) – Whether or not to remove ballots that have no weight as a result of cleaning. Defaults to True.
retain_original_candidate_list (bool, optional) – Whether or not to use the candidate list from the original profile in the new profile. If False, uses only candidates who receive votes. Defaults to True.

Returns:

A cleaned RankProfile.

Return type:

Raises:

ProfileError – Profile must only contain ranked ballots.

Elections 

class votekit.elections.ElectionState(round_number: int = 0, remaining: tuple[frozenset[str], ...] = (frozenset({}),), elected: tuple[frozenset[str], ...] = (frozenset({}),), eliminated: tuple[frozenset[str], ...] = (frozenset({}),), tiebreaks: dict[frozenset[str], tuple[frozenset[str], ...]] = <factory>, scores: dict[str, float] = <factory>)

Class for storing information about a round of an election. Round 0 should be the initial state of the election. To save memory, the PreferenceProfile is not carried by the ElectionState class.

round_number

Round number, defaults to 0.

Type:: int, optional

remaining

Remaining candidates, ordered to indicate ranking, frozensets to indicate ties. Defaults to tuple with one empty set.

Type:: tuple[frozenset[str],…], optional

elected

Elected candidates, ordered to indicate ranking, frozensets to indicate ties. Defaults to tuple with one empty set.

Type:: tuple[frozenset[str],…], optional

eliminated

Eliminated candidates, ordered to indicate ranking, frozensets to indicate ties. Defaults to tuple with one empty set.

Type:: tuple[frozenset[str],…], optional

tiebreaks

Stores tiebreak resolutions. Keys are frozensets of tied candidates and values are resolutions of tiebreak. Defaults to empty dictionary.

Type:: dict[frozenset[str], tuple[frozenset[str],…]], optional

scores

Stores score information. Keys are candidates, values are scores. Only remaining candidates should be stored.

Type:: dict[str, float], optional

to_dict() → dict[str, Any][source]: Convert the ElectionState to a dictionary representation.

class votekit.elections.Election(profile: P, score_function: Callable[[P], dict[str, float]] | None = None, sort_high_low: bool = True)

Abstract base class for election types.

Parameters:

profile (PreferenceProfile) – The initial profile of ballots.
score_function (Callable[[PreferenceProfile], dict[str, float]], optional) – A function that converts profiles to a score dictionary mapping candidates to their current score. Used in creating ElectionState objects and sorting candidates in Round 0. If None, no score dictionary is saved and all candidates are tied in Round 0. Defaults to None.
sort_high_low (bool, optional) – How to sort candidates based on score_function. True sorts from high to low. Defaults to True.

election_states

A list of election states, one for each round of the election. The list is 0 indexed, so the initial state is stored at index 0, round 1 at 1, etc.

Type:: list[ElectionState]

score_function

A function that converts profiles to a score dictionary mapping candidates to their current score. Used in creating ElectionState objects. Defaults to None.

Type:: Callable[[PreferenceProfile], dict[str, float]], optional

length

The number of rounds of the election.

Type:: int

get_elected(round_number: int = -1) → tuple[frozenset[str], ...][source]

Fetch the elected candidates up to the given round number.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: List of winning candidates in order of election. Candidates in the same set were elected simultaneously, i.e. in the final ranking they are tied.
Return type:: tuple[frozenset[str],…]

get_eliminated(round_number: int = -1) → tuple[frozenset[str], ...][source]

Fetch the eliminated candidates up to the given round number.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: Tuple of eliminated candidates in reverse order of elimination. Candidates in the same set were eliminated simultaneously, i.e. in the final ranking they are tied.
Return type:: tuple[frozenset[str],…]

get_profile(round_number: int = -1) → P[source]

Fetch the PreferenceProfile of the given round number.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: PreferenceProfile

get_ranking(round_number: int = -1) → tuple[frozenset[str], ...][source]

Fetch the ranking of candidates after a given round.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: Ranking of candidates.
Return type:: tuple[frozenset[str],…]

get_remaining(round_number: int = -1) → tuple[frozenset[str], ...][source]

Fetch the remaining candidates after the given round.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: Tuple of sets of remaining candidates. Ordering of tuple denotes ranking of remaining candidates, sets denote ties.
Return type:: tuple[frozenset[str],…]

get_status_df(round_number: int = -1) → DataFrame[source]

Yield the status (elected, eliminated, remaining) of the candidates in the given round. DataFrame is sorted by current ranking.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: Data frame displaying candidate, status (elected, eliminated, remaining), and the round their status updated.
Return type:: pd.DataFrame

get_step(round_number: int = -1) → tuple[P, ElectionState][source]

Fetches the profile and ElectionState of the given round number.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: tuple[PreferenceProfile, ElectionState]

Approval-based 

class votekit.elections.Approval(profile: ScoreProfile, n_seats: int | None = None, tiebreak: str | None = None, **kwargs)

Bases: GeneralRating

Approval election. Standard approval voting lets voters choose any subset of candidates to approve. Winners are the \(n_ ext{seats}\) candidates who received the most approval votes.

Parameters:

profile (ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.

class votekit.elections.BlockPlurality(profile: RankProfile | ScoreProfile, n_seats: int | None = None, budget: int | None = None, tiebreak: str | None = None, scoring_tie_convention: Literal['high', 'average', 'low'] = 'low', **kwargs)

Bases: Election

Block plurality election. Supports both ranked and score profiles.

When given a RankProfile, the top budget ranked candidates each receive 1 point and all others receive 0. When given a ScoreProfile, voters may give at most 1 point to each of budget candidates.

Parameters:

profile (RankProfile | ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
budget (int, optional) – Number of positions or approvals that count. Defaults to None, which results in n_seats.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.
scoring_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied rankings. Only used when profile is a RankProfile. Defaults to “low”.

Raises:

TypeError – If profile is not a RankProfile or ScoreProfile.

Ranking-based 

class votekit.elections.RankingElection(profile: RankProfile, n_seats: int = 1, score_function: Callable[[RankProfile], dict[str, float]] | None = None, sort_high_low: bool = True)

Bases: Election[RankProfile]

Abstract class for ranking election types. Validates that profile contains ranked ballots.

Parameters:

profile (RankProfile) – The initial profile of ballots.
score_function (Callable[[RankProfile], dict[str, float]], optional) – A function that converts profiles to a score dictionary mapping candidates to their current score. Used in creating ElectionState objects and sorting candidates in Round 0. If None, no score dictionary is saved and all candidates are tied in Round 0. Defaults to None.
sort_high_low (bool, optional) – How to sort candidates based on score_function. True sorts from high to low. Defaults to True.

election_states

a list of election states, one for each round of the election. The list is 0 indexed, so the initial state is stored at index 0, round 1 at 1, etc.

Type:: list[ElectionState]

score_function

A function that converts profiles to a score dictionary mapping candidates to their current score. Used in creating ElectionState objects. Defaults to None.

Type:: Callable[[RankProfile], dict[str, float]], optional

length

the number of rounds of the election.

Type:: int

class votekit.elections.Alaska(profile: ~votekit.RankProfile, m_1: int = 2, m_2: int = 1, transfer: ~typing.Callable[[str, float, tuple[~votekit.RankBallot] | list[~votekit.RankBallot], int], tuple[~votekit.RankBallot, ...]] = <function fractional_transfer>, quota: ~typing.Literal['droop', 'hare'] | None = 'droop', simultaneous: bool = True, tiebreak: ~typing.Literal['borda', 'random', 'first_place'] | None = None, fpv_tie_convention: ~typing.Literal['high', 'low', 'average'] = 'average')

Alaska election. Election method that first runs a Plurality election to choose a user-specified number of final-round candidates, then runs STV to choose \(m\) winners.

Parameters:

profile (RankProfile) – Profile to conduct election on.
m_1 (int, optional) – Number of final round candidates, i.e. number of winners of Plurality round. Defaults to 2.
m_2 (int, optional) – Number of seats to elect in STV round, i.e. number of overall winners. Defaults to 1.
(Callable[[str (transfer) – tuple[Ballot,…]], optional): Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.
float] – tuple[Ballot,…]], optional): Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.
Union[tuple[Ballot] – tuple[Ballot,…]], optional): Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.
list[Ballot]] – tuple[Ballot,…]], optional): Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.
int] – tuple[Ballot,…]], optional): Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.

:paramtuple[Ballot,…]], optional):: Transfer method. Defaults to fractional transfer. Function signature is elected candidate, their number of first-place votes, the list of ballots with them ranked first, and the threshold value. Returns the list of ballots after transfer.

Parameters:

quota (str, optional) – Formula to calculate quota. Accepts “droop” or “hare”. Defaults to “droop”.
simultaneous (bool, optional) – True if all candidates who cross threshold in a round are elected simultaneously, False if only the candidate with highest first-place votes who crosses the threshold is elected in a round. Defaults to True.
tiebreak (TiebreakType | None, optional) – Tiebreak method to use. Options are None, ‘random’, and ‘borda’. Defaults to None, in which case a tie raises a ValueError.
fpv_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied first place votes. Defaults to “average”, where if n candidates are tied for first, each receives 1/n points. “high” would award them each one point, and “low” 0. Only used by score_function parameter.

get_profile(round_number: int = -1) → RankProfile[source]

Fetch the RankProfile of the given round number.

Parameters:: round_number (int, optional) – The round number. Supports negative indexing. Defaults to -1, which accesses the final profile.
Returns:: RankProfile

class votekit.elections.Borda(profile: RankProfile, n_seats: int | None = None, score_vector: Sequence[float] | None = None, tiebreak: str | None = None, scoring_tie_convention: Literal['high', 'average', 'low'] = 'low', **kwargs)

Borda election. Positional voting system that assigns a decreasing number of points to candidates based on their ordering. The conventional score vector is \((n, n-1, \dots, 1)\) where \(n\) is the max_ranking_length of the profile. Candidates with the highest scores are elected. This class uses the utils.score_dict_from_score_vector() to handle ballots with ties.

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
score_vector (Sequence[float], optional) – Score vector. Should be non-increasing and non-negative. Vector should be as long as the number of candidates. If it is shorter, we add 0s. Defaults to None, which is the conventional Borda vector.
tiebreak (str, optional) – Tiebreak method to use. Options are None, ‘random’, and ‘first_place’. Defaults to None, in which case a tie raises a ValueError.
scoring_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied rankings. Defaults to “low”, where any candidates tied receive the lowest possible points for their position, eg three people tied for 3rd would each receive the points for 5th. “high” awards the highest possible points, so in the previous example, they would each receive the points for 3rd. “average” averages the points, so they would each receive the points for 4th place.

class votekit.elections.BoostedRandomDictator(profile: RankProfile, n_seats: int | None = None, fpv_tie_convention: Literal['high', 'average', 'low'] = 'average', **kwargs)

Modified random dictator where with probability (1 - 1/(n_candidates - 1)) choose a winner randomly from the distribution of first place votes. With probability 1/(n_candidates - 1), choose a winner via a proportional to squares rule.

For multi-winner elections repeat this process for every winner, removing that candidate from every voter’s ballot once they have been elected.

Parameters:

profile (RankProfile) – RankProfile to run election on.
n_seats (int) – Number of seats to elect.
fpv_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied first place votes. Defaults to “average”, where if n candidates are tied for first, each receives 1/n points. “high” would award them each one point, and “low” 0.

class votekit.elections.CondoBorda(profile: RankProfile, n_seats: int | None = None, **kwargs)

Just like DominatingSets (Smith method), but user gets to choose the number of winners, \(n_ ext{seats}\). Ties are broken with Borda scores.

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.

class votekit.elections.DominatingSets(profile: RankProfile)

A “dominating set” is any set S of candidates such that everyone in S beats everyone outside of S head-to-head. The top tier (which is well defined) is often called the “Smith set,” and if it is just one person, they are called the “Condorcet candidate.” The Smith method of election declares the Smith set to be the winners, which means that users do not get to specify the number of winners.

Parameters:: profile (RankProfile) – Profile to conduct election on.

class votekit.elections.Plurality(profile: RankProfile, n_seats: int | None = None, tiebreak: str | None = None, fpv_tie_convention: Literal['high', 'low', 'average'] = 'average', **kwargs)

Plurality election. Winners are the n_seats candidates with the most first-place votes.

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None, ‘random’, and ‘borda’. Defaults to None, in which case a tie raises a ValueError.
fpv_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied first place votes. Defaults to “average”, where if n candidates are tied for first, each receives 1/n points. “high” would award them each one point, and “low” 0. Only used by score_function parameter.

class votekit.elections.SNTV(profile: RankProfile, n_seats: int | None = None, tiebreak: str | None = None, **kwargs)

Bases: Plurality

Wrapper for Plurality election. Winners are the n_seats candidates with the most first-place votes.

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None, ‘random’, and ‘borda’. Defaults to None, in which case a tie raises a ValueError.

class votekit.elections.PluralityVeto(profile: RankProfile, n_seats: int | None = None, tiebreak: Literal['first_place', 'borda', 'random', 'lex'] = 'first_place', scoring_tie_convention: Literal['high', 'low', 'average'] = 'average', **kwargs)

Bases: _IterativeVetoBase

PluralityVeto election.

Scores each candidate by their number of first place (plurality) votes, then in a randomized order it lets each voter decrement the score of their least favorite remaining candidate. Candidates are eliminated immediately when their score reaches zero. The last m candidates remaining are the winners.

Partial ballots are handled by assuming that unranked candidates tie for last place.

Parameters:

profile (RankProfile) – RankProfile to run election on. All ballots must have integer weights.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method. Can be ‘first_place’, ‘random’, or ‘borda’. Used to determine veto when multiple candidates are tied for last place on a ballot. Defaults to ‘first_place’. If tiebreak is not ‘random’, tiebreak order is calculated in advance, using the initial profile. Thus, for ‘borda’ tiebreak, Borda scores are not recalculated as candidates are eliminated.
scoring_tie_convention (str, optional) – How to award points for tied first-place votes. Defaults to ‘average’: if n candidates are tied for first, each receives 1/n points. ‘high’ would award them each one point, and ‘low’ 0. Used by score_function parameter. Also used to define tiebreak_order if tiebreak is ‘first_place’ or ‘borda’.

n_seats

The number of seats to be filled in the election.

Type:: int

candidates

The set of candidates in the election.

Type:: frozenset[str]

tiebreak_order

The candidate ordering used to break last-place ties when processing vetoes. None if tiebreak = ‘random’.

Type:: Optional[tuple[frozenset[str]]]

Raises:: ValueError – If any of the following: - n_seats is less than or equal to 0 - n_seats exceeds the number of candidates in the profile who received votes, - a ballot has no ranking, - a ballot has non-integer weight.

class votekit.elections.SerialVeto(profile: RankProfile, n_seats: int | None = None, tiebreak: Literal['first_place', 'borda', 'random', 'lex'] = 'first_place', scoring_tie_convention: Literal['high', 'low', 'average'] = 'average', **kwargs)

Bases: _IterativeVetoBase

SerialVeto election.

Scores each candidate by their number of first place (plurality) votes, then in a randomized order it lets each voter decrement the score of their least favorite remaining candidate. Candidates with zero score are only eliminated when a voter attempts to veto them, which does not use up that voter’s veto. The last n_seats candidates remaining are the winners.

Partial ballots are handled by assuming that unranked candidates tie for last place.

Parameters:

profile (RankProfile) – RankProfile to run election on. All ballots must have integer weights.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method. Can be ‘first_place’, ‘random’, or ‘borda’.
ballot. (Used to determine veto when multiple candidates are tied for last place on a) – Defaults to ‘first_place’. If tiebreak is not ‘random’, tiebreak order is calculated in advance, using the initial profile. Thus, for ‘borda’ tiebreak, Borda scores are not recalculated as candidates are eliminated.
scoring_tie_convention (str, optional) – How to award points for tied first-place votes. Defaults to ‘average’: if n candidates are tied for first, each receives 1/n points. ‘high’ would award them each one point, and ‘low’ 0. Used by score_function parameter. Also used to define tiebreak_order if tiebreak is ‘first_place’ or ‘borda’.

n_seats

The number of seats to be filled in the election.

Type:: int

candidates

The set of candidates in the election.

Type:: frozenset[str]

tiebreak_order

The candidate ordering used to break last-place ties when processing vetoes. None if tiebreak = ‘random’.

Type:: Optional[tuple[frozenset[str]]]

Raises:: ValueError – If any of the following: - n_seats is less than or equal to 0, - n_seats exceeds the number of candidates in the profile who received votes, - a ballot has no ranking, or - a ballot has non-integer weight.

class votekit.elections.SimultaneousVeto(profile: RankProfile, n_seats: int | None = None, candidate_weights: Literal['first_place', 'uniform', 'borda', 'harmonic'] | dict[str, float] | int = 'first_place', tiebreak: Literal['first_place', 'random', 'borda', 'remaining_score', 'veto_pressure', 'lex'] = 'first_place', scoring_tie_convention: Literal['high', 'average', 'low'] = 'average', return_all_tied_winners: bool = False, **kwargs)

An anonymous version of PluralityVeto.

Each candidate begins with a score, then, all at the same time, voters remove score from their least favorite candidates at a constant rate. As candidates’ scores reach zero, they are eliminated, and voters that were vetoing them transfer to their next least-favorite candidate. With plurality scores (first-place votes), this voting rule achieves optimal metric distortion. See Kizilkaya & Kempe’s 2023 paper: “Generalized Veto Core and a Practical Voting Rule with Optimal Metric Distortion” (https://arxiv.org/pdf/2305.19632).

Partial ballots are treated by assuming that all unranked candidates tie for last place. Voters with ties in their ranking will spread their veto evenly across the tied candidates.

Parameters:

profile (RankProfile) – Profile to run election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
(Literal['first_place' (tiebreak) –

int, optional): Initial candidate scores. ‘first_place’ means candidates begin with

their first-place vote count. ‘uniform’ means all candidates begin with the same score. ‘borda’ means candidates begin with their Borda scores. If a dictionary, keys are candidates and values are initial scores; a score must be provided for every candidate. If an integer k, candidates begin with their top-k vote count. Defaults to “first_place”.
'uniform' –

int, optional): Initial candidate scores. ‘first_place’ means candidates begin with

their first-place vote count. ‘uniform’ means all candidates begin with the same score. ‘borda’ means candidates begin with their Borda scores. If a dictionary, keys are candidates and values are initial scores; a score must be provided for every candidate. If an integer k, candidates begin with their top-k vote count. Defaults to “first_place”.
'borda' –

int, optional): Initial candidate scores. ‘first_place’ means candidates begin with

their first-place vote count. ‘uniform’ means all candidates begin with the same score. ‘borda’ means candidates begin with their Borda scores. If a dictionary, keys are candidates and values are initial scores; a score must be provided for every candidate. If an integer k, candidates begin with their top-k vote count. Defaults to “first_place”.
dict[str ('harmonic'] |) –

int, optional): Initial candidate scores. ‘first_place’ means candidates begin with

their first-place vote count. ‘uniform’ means all candidates begin with the same score. ‘borda’ means candidates begin with their Borda scores. If a dictionary, keys are candidates and values are initial scores; a score must be provided for every candidate. If an integer k, candidates begin with their top-k vote count. Defaults to “first_place”.
float] –

int, optional): Initial candidate scores. ‘first_place’ means candidates begin with

their first-place vote count. ‘uniform’ means all candidates begin with the same score. ‘borda’ means candidates begin with their Borda scores. If a dictionary, keys are candidates and values are initial scores; a score must be provided for every candidate. If an integer k, candidates begin with their top-k vote count. Defaults to “first_place”.
(Literal['first_place' – ‘lex’], optional): Method for breaking ties when multiple candidates are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.
'random' – ‘lex’], optional): Method for breaking ties when multiple candidates are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.
'borda' – ‘lex’], optional): Method for breaking ties when multiple candidates are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.
'remaining_score' – ‘lex’], optional): Method for breaking ties when multiple candidates are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.
'veto_pressure' – ‘lex’], optional): Method for breaking ties when multiple candidates are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.

:param‘lex’], optional): Method for breaking ties when multiple candidates: are eliminated simultaneously. Defaults to “first_place”. Backup tiebreak is lexicographic/alphabetical.

Parameters:

scoring_tie_convention (Literal['high', 'average', 'low'], optional) – How to award points for ties in rankings when candidate_weights is ‘first_place’ or ‘borda’. Defaults to “average”.
return_all_tied_winners (bool) – If True, election returns a winner set of all tied winners, even if it is larger than n_seats. Defaults to False.

candidates

Candidates in the initial profile.

Type:: frozenset[str]

initial_scores

Initial scores of each candidate before veto process.

Type:: dict[str, float]

Raises:

ValueError – If any of the following: - n_seats is not positive or exceeds the number of candidates. - any ballot lacks a ranking. - candidate_weights is a dict missing candidates as keys. - candidate_weights is an unrecognized string. - candidate_weights is an int not in [1, number of candidates]
TypeError – If candidate_weights is not a string, dict, or int.

class votekit.elections.RandomDictator(profile: RankProfile, n_seats: int | None = None, fpv_tie_convention: Literal['high', 'average', 'low'] = 'average', **kwargs)

Choose a winner randomly from the distribution of first place votes. For multi-winner elections repeat this process for every winner, removing that candidate from every voter’s ballot once they have been elected.

Parameters:

profile (RankProfile) – RankProfile to run election on.
n_seats (int) – Number of seats to elect.
fpv_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied first place votes. Defaults to “average”, where if n candidates are tied for first, each receives 1/n points. “high” would award them each one point, and “low” 0.

class votekit.elections.RankedPairs(profile: RankProfile, tiebreak: str = 'lexicographic', n_seats: int | None = None, **kwargs)

See Ranked Pairs for more details. Any ambiguity is resolved lexicographically, so that the candidate with the first name alphabetically is preferred in the case of a tie.

The idea of the Ranked Pairs election is to take the head-to-head results of the candidates and then sort them by the margin of victory. We then lock this order in and construct a directed graph from the head-to-head results by traversing the locked order and skipping any edges that would create a cycle in the directed graph. The final ranking of the election is then determined by the dominating tiers of the directed graph with ties broken lexicographically.

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.

class votekit.elections.Schulze(profile: RankProfile, tiebreak: str = 'lexicographic', n_seats: int | None = None, **kwargs)

See <https://link.springer.com/article/10.1007/s00355-010-0475-4> and <https://arxiv.org/pdf/1804.02973>

The Schulze method uses the widest path algorithm to determine winners. For each pair of candidates, it computes the strength of the strongest path (where the strength of a path is the strength of its weakest link). For example, if Alice beats Bob by 2 votes, Bob beats Charlie by 4 votes, then the beatpath strength from Alice to Bob is 2. Candidate A is preferred to candidate B if the strongest path from A to B is stronger than the strongest path from B to A.

The Schulze method computes the strongest paths between all pairs of candidates: 1. Initialize p[i,j] = d[i,j] - d[j,i] (margin of victory) 2. For each intermediate candidate k, update p[i,j] = max(p[i,j], min(p[i,k], p[k,j])) 3. Candidate i beats j if p[i,j] > p[j,i]

Parameters:

profile (RankProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Method for breaking ties. Defaults to “lexicographic”.

class votekit.elections.STV(profile: ~votekit.RankProfile, n_seats: int | None = None, transfer: ~typing.Callable[[str, float, tuple[~votekit.RankBallot] | list[~votekit.RankBallot], int], tuple[~votekit.RankBallot, ...]] = <function fractional_transfer>, quota: ~typing.Literal['droop', 'hare'] | None = 'droop', simultaneous: bool = True, tiebreak: ~typing.Literal['borda', 'random', 'first_place'] | None = None, **kwargs)

STV elections. All ballots must have no ties.

get_threshold(total_ballot_wt: float) → int[source]

Calculates threshold required for election.

Parameters:: total_ballot_wt (float) – Total weight of ballots to compute threshold.
Returns:: Value of the threshold.
Return type:: int

class votekit.elections.FastSTV(profile: RankProfile, n_seats: int | None = None, transfer: Literal['fractional', 'fractional_random', 'cambridge_random', 'random'] = 'fractional', quota: Literal['droop', 'hare'] | None = 'droop', simultaneous: bool = True, tiebreak: Literal['borda', 'random', 'first_place'] | None = None, **kwargs)

Bases: NumpyInnerSTV

STV elections. Must be given a RankProfile.

Initialize a fast STV election.

Parameters:

profile (RankProfile) – RankProfile to run election on.
n_seats (int, optional) – Number of seats to be elected. Defaults to 1.
transfer (TransferType, optional) – Transfer method to be used. Accepts “fractional”, “random”, “fractional_random”, and “cambridge_random”. Defaults to “fractional”.
quota (QuotaType, optional) – Formula to calculate quota. Accepts “droop” or “hare”. Defaults to “droop”.
simultaneous (bool, optional) – True if all candidates who cross threshold in a round are elected simultaneously. False if only the candidate with highest first-place votes who crosses the threshold is elected in a round. Defaults to True.
tiebreak (TiebreakType | None, optional) – Method to be used if a tiebreak is needed. Accepts “borda”, “random”, and “cambridge_random”. Defaults to None, in which case a ValueError is raised if a tiebreak is needed.

class votekit.elections.IRV(profile: RankProfile, quota: Literal['droop', 'hare'] | None = 'droop', tiebreak: Literal['borda', 'random', 'first_place'] | None = None)

Bases: STV

Elect exactly 1 seat using IRV (Instant-runoff voting).

All ballots must have no ties. Equivalent to STV for n_seats = 1.

Initialize an IRV election.

Parameters:

profile (RankProfile) – RankProfile to run election on.
quota (QuotaType, optional) – Formula to calculate quota. Accepts “droop” or “hare”. Defaults to “droop”.
tiebreak (TiebreakType | None, optional) – Method to be used if a tiebreak is needed. Accepts “borda” and “random”. Defaults to None, in which case a ValueError is raised if a tiebreak is needed.

class votekit.elections.SequentialRCV(profile: RankProfile, n_seats: int | None = None, quota: Literal['droop', 'hare'] | None = 'droop', simultaneous: bool = True, tiebreak: Literal['borda', 'random', 'first_place'] | None = None, **kwargs)

Bases: STV

STV election in which votes are not transferred from elected candidates.

This system just runs a series of IRV elections until the desired number of candidates are elected.

Notes

Used in parts of Utah.

Initialize a sequential RCV election.

Parameters:

profile (RankProfile) – RankProfile to run election on.
n_seats (int, optional) – Number of seats to be elected. Defaults to 1.
quota (QuotaType, optional) – Formula to calculate quota. Accepts “droop” or “hare”. Defaults to “droop”.
simultaneous (bool, optional) – True if all candidates who cross threshold in a round are elected simultaneously. False if only the candidate with highest first-place votes who crosses the threshold is elected in a round. Defaults to True.
tiebreak (TiebreakType | None, optional) – Method to be used if a tiebreak is needed. Accepts “borda” and “random”. Defaults to None, in which case a ValueError is raised if a tiebreak is needed.

class votekit.elections.TopTwo(profile: RankProfile, tiebreak: str | None = None, fpv_tie_convention: Literal['high', 'low', 'average'] = 'average')

Eliminates all but the top two plurality vote-getters, and then conducts a runoff between them, reallocating other ballots.

Parameters:

profile (RankProfile) – Profile to conduct election on.
tiebreak (str, optional) – Tiebreak method to use. Options are None, ‘random’, and ‘borda’. Defaults to None, in which case a tie raises a ValueError.
fpv_tie_convention (Literal["high", "average", "low"], optional) – How to award points for tied first place votes. Defaults to “average”, where if n candidates are tied for first, each receives 1/n points. “high” would award them each one point, and “low” 0. Only used by score_function parameter.

Score-based 

class votekit.elections.GeneralRating(profile: ScoreProfile, n_seats: int | None = None, per_candidate_limit: float | None = None, budget: float | None = None, tiebreak: str | None = None, **kwargs)

Bases: Election[ScoreProfile]

General rating election. To fill \(n_ ext{seats}\) seats, voters score each candidate from \(0\) to per_candidate_limit. There is also a total budget of budget points per voter. The \(n_ ext{seats}\) winners are those with the highest total score.

Parameters:

profile (ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
per_candidate_limit (float, optional) – Rating per candidate limit. Defaults to 1.
budget (float, optional) – Budget per ballot limit. Defaults to None, in which case voters can score each candidate independently.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.

class votekit.elections.Rating(profile: ScoreProfile, n_seats: int | None = None, per_candidate_limit: float | None = None, tiebreak: str | None = None, **kwargs)

Bases: GeneralRating

Rating election. To fill \(n_ ext{seats}\) seats, voters score each candidate independently from \(0\) to per_candidate_limit. The \(n_ ext{seats}\) winners are those with the highest total score.

Parameters:

profile (ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
per_candidate_limit (float, optional) – Rating per candidate limit. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.

class votekit.elections.Cumulative(profile: ScoreProfile, n_seats: int | None = None, tiebreak: str | None = None, **kwargs)

Bases: Limited

Scoring election where voters distribute up to n_seats points total.

Voters can score each candidate, but have a total budget of \(n_ ext{seats}\) points. Winners are those with the highest total score.

Parameters:

profile (ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.

class votekit.elections.Limited(profile: ScoreProfile, n_seats: int | None = None, budget: float | None = None, tiebreak: str | None = None, **kwargs)

Bases: GeneralRating

A scoring election with a per-voter budget constraint.

Voters can score each candidate, but have a total budget of \(\text{budget} \le n_\text{seats}\) points. Winners are those with the highest total score.

Parameters:

profile (ScoreProfile) – Profile to conduct election on.
n_seats (int, optional) – Number of seats to elect. Defaults to 1.
budget (float, optional) – Total points allowed per voter. Defaults to 1.
tiebreak (str, optional) – Tiebreak method to use. Options are None and ‘random’. Defaults to None, in which case a tie raises a ValueError.

Raises:

ValueError – If budget exceeds n_seats.

Graphs and Viz.

class votekit.graphs.BallotGraph(source: RankProfile | int | list, allow_partial: bool | None = True, fix_short: bool | None = True)

Class to build ballot graphs.

Parameters:

source (Union[RankProfile, int, list]) – data to create graph from, either RankProfile object, number of candidates, or list of candidates.
allow_partial (bool, optional) – If True, builds graph using all possible ballots, If False, only uses total linear ordered ballots. Defaults to True.
fix_short (bool, optional) – If True, auto completes ballots of length \(n-1\) to \(n\). Ballots of length less than \(n-1\) are preserved. Defaults to True.

profile

Profile used to create graph, None if not provided.

Type:: RankProfile

candidates

Tuple of candidates, None if not provided.

Type:: tuple[str]

num_cands

Number of candidates.

Type:: int

num_voters

Sum of weights of profile if provided.

Type:: float

allow_partial

If True, builds graph using all possible ballots, If False, only uses total linear ordered ballots.

Type:: bool, optional

graph

underlying networkx graph.

Type:: networkx.Graph

build_graph(n: int) → Graph[source]

Builds graph of all possible ballots given a number of candiates.

Parameters:: n (int) – Number of candidates in an election.
Returns:: A networkx graph.
Return type:: networkx.Graph

draw(to_display: ~typing.Callable = <function all_nodes>, neighborhoods: list[tuple] | None = [], show_cast: bool | None = False, labels: bool | None = False, scale: float = 1.0)[source]

Visualize the graph.

Parameters:

to_display (Callable, optional) – A boolean function that takes the graph and a node as input, returns True if you want that node displayed. Defaults to showing all nodes.
neighborhoods (list[tuple], optional) – A list of neighborhoods to display, given as tuple (node, radius). eg. (n,1) gives all nodes within one step of n. Defaults to empty list which shows all nodes.
show_cast (bool, optional) – If True, show only nodes with “cast” attribute = True. If False, show all nodes. Defaults to False.
labels (bool, optional) – If True, labels nodes with candidate names and vote totals. Defaults to False.
scale (float, optional) – How much to scale the base graph by. Defaults to 1.0.

fix_short_ballot(ballot: list, candidates: list) → list[source]

Adds missing candidates to a short ballot.

Parameters:

ballot (list) – A list of candidates on the ballot.
candidates (list) – A list of all candidates.

Returns:

A new list with the missing candidates added to the end of the ballot.

Return type:

list

from_profile(profile: RankProfile, fix_short: bool | None = True) → Graph[source]

Updates existing graph based on cast ballots from a RankProfile, or creates graph based on RankProfile.

Parameters:

profile (RankProfile) – RankProfile assigned to graph.
fix_short (bool, optional) – If True, complete short ballots. Defaults to True.

Returns:

Graph based on RankProfile, ‘cast’ node attribute indicates ballots cast in RankProfile.

Return type:

networkx.Graph

label_cands(candidates, to_display: ~typing.Callable = <function all_nodes>)[source]

Assigns candidate labels to ballot graph for plotting.

Parameters:

candidates (list) – A list of candidates.
to_display (Callable, optional) – A Boolean callable that takes in a graph and node, returns True if node should be displayed. Defaults to showing all nodes.

label_weights(to_display: ~typing.Callable = <function all_nodes>)[source]

Assigns weight labels to ballot graph for plotting. Only shows weight if non-zero.

Parameters:: to_display (Callable, optional) – A Boolean callable that takes in a graph and node, returns True if node should be displayed. Defaults to showing all nodes.

class votekit.graphs.PairwiseComparisonGraph(*args, backend=None, **kwargs)

Bases: DiGraph

Class to construct the pairwise comparison graph where nodes are candidates and edges are pairwise preferences.

Parameters:

profile (RankProfile) – RankProfile to construct graph from.
sort_candidate_pairs (bool) – If True, candidate pairs in the pairwise comparison dictionary will be sorted lexicographically. Defaults to True.

profile

RankProfile to construct graph from.

Type:: RankProfile

candidates

List of candidates.

Type:: list

pairwise_dict

Dictionary constructed from pairwise_dict. The pairwise dictionary is a dictionary whose keys are candidate pairs (A,B) and whose values are lists [a,b] where ‘a’ denotes the number of times A beats B head to head, and ‘b’ is the number of times B beats A head to head.

Type:: dict[tuple[str, str], tuple[float, float]]

pairwise_graph

Underlying graph.

Type:: networkx.DiGraph

draw(ax: matplotlib.axes.Axes | None = None, candidate_list: list[str] | None = None) → matplotlib.axes.Axes[source]

Draws pairwise comparison graph.

Parameters:

ax (Axes, optional) – Matplotlib axes to plot on. Defaults to None, in which case an axes is generated.
candidate_list (list[str], optional) – List of candidates to plot. Defaults to None, in which case all candidates are used.

Returns:

Matplotlib axes of pairwise comparison graph.

Return type:

Axes

get_condorcet_cycles(strict: bool = False) → list[set[str]][source]

Returns a list of condorcet cycles in the graph.

A cycle is defined as any cycle of length greater than 2.

Parameters:: strict (bool, optional) – If True, only considers strict wins (weight > 0). If False, includes ties (weak condorcet cycles). Defaults to False.
Returns:: List of condorcet cycles sorted by length.
Return type:: list[set[str]]

get_condorcet_winner() → str[source]

Returns the condorcet winner. Raises a ValueError if no condorcet winner.

Returns:: The condorcet winner.
Return type:: str
Raises:: ValueError – There is no condorcet winner.

get_dominating_tiers() → list[set[str]][source]

Compute the dominating tiers of the pairwise comparison graph. Candidates in a tier beat all other candidates in lower tiers in head to head comparisons.

Returns:: Dominating tiers, where the first entry of the list is the highest tier.
Return type:: list[set[str]]

has_condorcet_cycles() → bool[source]

Checks if graph has any condorcet cycles, which we define as any cycle of length greater than 2 in the graph.

Returns:: True if condorcet cycles exists, False otherwise.
Return type:: bool

has_condorcet_winner() → bool[source]

Checks if graph has a condorcet winner.

Returns:: True if condorcet winner exists, False otherwise.
Return type:: bool

ties_or_beats(candidate: str) → set[str][source]

Returns the predecessors of x, which are all of the nodes m that have a directed path from m to x. In the pairwise comparison graph, these are the candidates that tie or beat the given candidate.

Parameters:: candidate (str) – Candidate.
Returns:: Candidates that beat or tie given candidate head to head.
Return type:: set[str]

votekit.graphs.pairwise_dict(profile: RankProfile, *, sort_candidate_pairs: bool = True) → dict[tuple[str, str], tuple[float, float]]

Computes a dictionary whose keys are candidate pairs (A,B) and whose values are lists [a,b] where ‘a’ denotes the number of times A beats B head to head, and ‘b’ is the reverse.

Parameters:

profile (RankProfile) – Profile to compute dict on.
sort_candidate_pairs (bool) – If True, candidate pairs in the pairwise comparison dictionary will be sorted lexicographically. Defaults to True.

Returns:

Pairwise comparison dictionary.

Return type:

dict[tuple[str, str], tuple[float, float]]

votekit.graphs.restrict_pairwise_dict_to_subset(cand_subset: list[str] | tuple[str] | set[str], pairwise_dict: dict[tuple[str, str], tuple[float, float]]) → dict[tuple[str, str], tuple[float, float]]

Restricts the full pairwise dictionary to a subset of candidates. The pairwise dictionary is a dictionary whose keys are candidate pairs (A,B) and whose values are lists [a,b] where ‘a’ denotes the number of times A beats B head to head, and ‘b’ is the reverse.

Parameters:

cands (list[str] | tuple[str] | set[str]) – Candidate subset to restrict to.
pairwise_dict (dict[tuple[str, str], tuple[float, float]) – Full pairwise comparison dictionary.

Returns:

Pairwise dict restricted to the provided: candidates.

Return type:

dict[tuple[str, str], tuple[float, float]]

Raises:

ValueError – cand_subset must be at least length 2.
ValueError – cand_subset must be a subset of the candidates in the dictionary.

votekit.plots.compute_MDS(data: Dict[str, list[PreferenceProfile]], distance: Callable[[...], int], random_seed: int = 47, *args, **kwargs)

Computes the coordinates of an MDS plot. This is time intensive, so it is decoupled from plot_mds to allow users to flexibly use the coordinates.

Parameters:

data (Dict[str, list[PreferenceProfile]]) – Dictionary with key being a string label and value being list of PreferenceProfiles. eg. {'PL with alpha = 4': list[PreferenceProfile]}
distance (Callable[..., int]) – Distance function. See distance.py.
random_seed (int, optional) – An integer seed to allow for reproducible MDS plots. Defaults to 47.
*args – args to be passed to distance_matrix.
**kwargs – kwargs to be passed to distance_matrix.

Returns:

a dictionary whose keys match data and whose values are tuples of: numpy arrays (x_list, y_list) of coordinates for the MDS plot.

Return type:

coord_dict (dict)

votekit.plots.plot_MDS(coord_dict: dict, ax: matplotlib.axes.Axes | None = None, plot_kwarg_dict: dict | None = None, legend: bool = True, title: bool = True)

Creates an MDS plot from the output of compute_MDS with legend labels matching the keys of coord_dict.

Parameters:

coord_dict (dict) – Dictionary with key being a string label and value being tuple (x_list, y_list), coordinates for the MDS plot. Should be piped in from compute_MDS.
ax (axes, optional) – A matplolib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes.
plot_kwarg_dict (dict, optional) – Dictionary with keys matching coord_dict and values are kwarg dictionaries that will be passed to matplotlib scatter.
legend (bool, optional) – boolean for plotting the legend. Defaults to True.
title (bool, optional) – boolean for plotting the title. Defaults to True.

Returns:

a matplotlib Axes.

Return type:

Axes

votekit.plots.bar_plot(data: Mapping[str, float], *, data_set_label: str = 'Data set', normalize: bool = False, data_set_color: str = '#0099cd', bar_width: float | None = None, category_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_data_set_legend: bool = False, categories_legend: Mapping[str, str | int] | None = None, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plots bar plot of a single categorical data set. Wrapper for multi_bar_plot.

Parameters:

data (dict[str, float]) – Categorical data set to be plotted. Keys are categories, and values are the height of the bars.
data_set_label (str, optional) – Label for data set. Defaults to “Data set”.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
data_set_color (str, optional) – Color of data set. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
category_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from data dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_data_set_legend (bool, optional) – Whether or not to plot the data set legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
categories_legend (dict[str, str], optional) – Dictionary mapping data categories to description. Defaults to None. If provided, generates a second legend for data categories.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

Plots bar plot of categorical data.

Parameters:

data (dict[str, dict[str, float]]) – Categorical data to be plotted. Top level keys are data set labels. Inner keys are categories, and inner values are the height of the bars.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
data_set_colors (dict[str, str], optional) – Dictionary mapping data set labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the data sets.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
category_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from data dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_data_set_legend (bool, optional) – Whether or not to plot the data set legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
categories_legend (dict[str, str], optional) – Dictionary mapping data categories to relabeling. Defaults to None. If provided, generates a second legend for data categories and relabels the x-axis accordingly. Can be a subset of the data keys.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.profile_bar_plot(profile: ProfileT, stat_function: Callable[[ProfileT], dict[str, float]], *, profile_label: str = 'Profile', normalize: bool = False, profile_color: str = '#0099cd', bar_width: float | None = None, category_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, categories_legend: Mapping[str, str | int] | None = None, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plots bar plot of a single profile.

Parameters:

profile (RankProfile) – Profile to plot statistics for.
stat_function (Callable[[RankProfile], dict[str, float]]) – Which stat to use for the bar plot. Must be a callable that takes a profile and returns a dict with str keys and float values.
profile_label (str, optional) – Label for profile. Defaults to “Profile”.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_color (str, optional) – Color to plot. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
category_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from data dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
categories_legend (dict[str, str], optional) – Dictionary mapping data categories to description. Defaults to None. If provided, generates a second legend for data categories.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.profile_borda_plot(profile: RankProfile, *, profile_label: str = 'Profile', borda_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_color: str = '#0099cd', bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plots borda points of candidates in profile. Wrapper for profile_bar_plot.

Parameters:

profile (RankProfile) – Profile to plot statistics for.
profile_label (str, optional) – Label for profile. Defaults to “Profile”.
borda_kwds (dict[str, Any], optional) – Keyword arguments to pass to borda_scores. Defaults to None, in which case default values for borda_scores are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_color (str, optional) – Color to plot. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to decreasing order of Borda scores.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to alternate label. Defaults to None. If provided, generates a second legend.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

Plots ballot lengths in profile. Wrapper for profile_bar_plot.

Parameters:

profile (RankProfile) – Profile to plot statistics for.
profile_label (str, optional) – Label for profile. Defaults to “Profile”.
ballot_lengths_kwds (dict[str, Any], optional) – Keyword arguments to pass to ballot_lengths. Defaults to None, in which case default values for ballot_lengths are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_color (str, optional) – Color to plot. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
lengths_ordering (list[str], optional) – Ordering of x-labels. Defaults to increasing order of lengths.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
lengths_legend (dict[str, str], optional) – Dictionary mapping lengths to alternate label. Defaults to None. If provided, generates a second legend.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], optional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.profile_fpv_plot(profile: RankProfile, *, profile_label: str = 'Profile', fpv_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_color: str = '#0099cd', bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plots first place votes of candidates in profile. Wrapper for profile_bar_plot.

Parameters:

profile (RankProfile) – Profile to plot statistics for.
profile_label (str, optional) – Label for profile. Defaults to “Profile”.
fpv_kwds (dict[str, Any], optional) – Keyword arguments to pass to first_place_votes. Defaults to None, in which case default values for first_place_votes are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_color (str, optional) – Color to plot. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to decreasing order of first place votes.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to alternate label. Defaults to None. If provided, generates a second legend.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.profile_mentions_plot(profile: RankProfile, *, profile_label: str = 'Profile', mentions_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_color: str = '#0099cd', bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plots mentions of candidates in profile. Wrapper for profile_bar_plot.

Parameters:

profile (RankProfile) – Profile to plot statistics for.
profile_label (str, optional) – Label for profile. Defaults to “Profile”.
mentions_kwds (dict[str, Any], optional) – Keyword arguments to pass to mentions. Defaults to None, in which case default values for mentions are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_color (str, optional) – Color to plot. Defaults to the first color from COLOR_LIST from utils module.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to decreasing order of mentions.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to alternate label. Defaults to None. If provided, generates a second legend.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.multi_profile_bar_plot(profile_dict: Mapping[str, ProfileT], stat_function: Callable[[ProfileT], dict[str, float]], normalize: bool = False, profile_colors: Mapping[str, str] | None = None, bar_width: float | None = None, category_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, categories_legend: Mapping[str, str | int] | None = None, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plot a multi bar plot over a set of preference profiles and some statistic about the profile, like ballot length, first place votes for candidate, etc.

Parameters:

profile_dict (dict[str, RankProfile | ScoreProfile]) – Keys are profile labels and values are profiles to plot statistics for.
stat_function (Callable[[RankProfile | ScoreProfile], dict[str, float]]) – Which stat to use for the bar plot. Must be a callable that takes a profile and returns a dict with str keys and float values.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_colors (dict[str, str], optional) – Dictionary mapping profile labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the profiles.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
category_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from data dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
categories_legend (dict[str, str], optional) – Dictionary mapping data categories to description. Defaults to None. If provided, generates a second legend for data categories.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

Plot the ballot lengths for a collection of profiles. Wrapper for multi_profile_bar_plot.

Parameters:

profile_dict (dict[str, RankProfile]) – Keys are profile labels and values are profiles to plot statistics for.
ballot_lengths_kwds (dict[str, Any], optional) – Keyword arguments to pass to ballot_lengths. Defaults to None, in which case default values for ballot_lengths are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_colors (dict[str, str], optional) – Dictionary mapping profile labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the profiles.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
lengths_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from score dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
lengths_legend (dict[str, str], optional) – Dictionary mapping lengths to relableing. Defaults to None. If provided, generates a second legend for data categories.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.multi_profile_borda_plot(profile_dict: Mapping[str, RankProfile], borda_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_colors: Mapping[str, str] | None = None, bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plot the borda scores for a collection of profiles. Wrapper for multi_profile_bar_plot.

Parameters:

profile_dict (dict[str, RankProfile]) – Keys are profile labels and values are profiles to plot statistics for.
borda_kwds (dict[str, Any], optional) – Keyword arguments to pass to borda_scores. Defaults to None, in which case default values for borda_scores are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_colors (dict[str, str], optional) – Dictionary mapping profile labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the profiles.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to decreasing borda scores from the first profile.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to relableing. Defaults to None. If provided, generates a second legend for data categories.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.multi_profile_fpv_plot(profile_dict: Mapping[str, RankProfile], fpv_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_colors: Mapping[str, str] | None = None, bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plot the first place votes for a collection of profiles. Wrapper for multi_profile_bar_plot.

Parameters:

profile_dict (dict[str, RankProfile]) – Keys are profile labels and values are profiles to plot statistics for.
fpv_kwds (dict[str, Any], optional) – Keyword arguments to pass to first_place_votes. Defaults to None, in which case default values for first_place_votes are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_colors (dict[str, str], optional) – Dictionary mapping profile labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the profiles.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from score dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to relableing. Defaults to None. If provided, generates a second legend for data categories.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

votekit.plots.multi_profile_mentions_plot(profile_dict: Mapping[str, RankProfile], mentions_kwds: dict[str, Any] | None = None, normalize: bool = False, profile_colors: Mapping[str, str] | None = None, bar_width: float | None = None, candidate_ordering: list[str] | None = None, x_axis_name: str | None = None, y_axis_name: str | None = None, title: str | None = None, show_profile_legend: bool = False, candidate_legend: Mapping[str, str | int] | None = None, relabel_candidates_with_int: bool = False, threshold_values: list[float] | float | None = None, threshold_kwds: list[dict] | dict | None = None, legend_font_size: float | None = None, ax: matplotlib.axes.Axes | None = None) → matplotlib.axes.Axes

Plot the mentions for a collection of profiles. Wrapper for multi_profile_bar_plot.

Parameters:

profile_dict (dict[str, RankProfile]) – Keys are profile labels and values are profiles to plot statistics for.
mentions_kwds (dict[str, Any], optional) – Keyword arguments to pass to mentions. Defaults to None, in which case default values for mentions are used.
normalize (bool, optional) – Whether or not to normalize data. Defaults to False.
profile_colors (dict[str, str], optional) – Dictionary mapping profile labels to colors. Defaults to None, in which case we use a subset of COLOR_LIST from utils module. Dictionary keys can be a subset of the profiles.
bar_width (float, optional) – Width of bars. Defaults to None which computes the bar width as 0.7 divided by the number of data sets. Must be in the interval \((0,1]\).
candidate_ordering (list[str], optional) – Ordering of x-labels. Defaults to order retrieved from score dictionary.
x_axis_name (str, optional) – Name of x-axis. Defaults to None, which does not plot a name.
y_axis_name (str, optional) – Name of y-axis. Defaults to None, which does not plot a name.
title (str, optional) – Title for the figure. Defaults to None, which does not plot a title.
show_profile_legend (bool, optional) – Whether or not to plot the profile legend. Defaults to False. Is automatically shown if any threshold lines have the keyword “label” passed through threshold_kwds.
candidate_legend (dict[str, str], optional) – Dictionary mapping candidates to relableing. Defaults to None. If provided, generates a second legend for data categories.
relabel_candidates_with_int (bool, optional) – Relabel the candidates with integer labels. Defaults to False. If candidate_legend is passed, those labels supercede.
threshold_values (Union[list[float], float], optional) – List of values to plot horizontal lines at. Can be provided as a list or a single float.
threshold_kwds (Union[list[dict], dict], optional) – List of plotting keywords for the horizontal lines. Can be a list or single dictionary. These will be passed to plt.axhline(). Common keywords include “linestyle”, “linewidth”, and “label”. If “label” is passed, automatically plots the data set legend with the labels.
legend_font_size (float, optional) – The font size to use for the legend. Defaults to 10.0 + the number of categories.
legend_loc (str, optional) – The location parameter to pass to Axes.legend(loc=). Defaults to “center left”.
legend_bbox_to_anchor (Tuple[float, float], otptional) – The bounding box to anchor the legend to. Defaults to (1, 0.5).
ax (Axes, optional) – A matplotlib axes object to plot the figure on. Defaults to None, in which case the function creates and returns a new axes. The figure height is 6 inches and the figure width is 3 inches times the number of categories.

Returns:

A matplotlib axes with a bar plot of the given data.

Return type:

Axes

Cast Vote Records 

votekit.cvr_loaders.load_csv(path_or_url: str, rank_cols: list[int], *, weight_col: int | None = None, id_col: int | None = None, candidates: list[str] | None = None, delimiter: str = ',', header_row: int | None = None, print_profile: bool = True) → RankProfile

Given a file path or url, loads ranked cast vote record (cvr) with ranks as columns and voters as rows.

Parameters:

path_or_url (str) – Path or url to cvr file.
rank_cols (list[int]) – List of column indices that contain rankings. Column indexing starts from 0, in order from top to bottom rank.
weight_col (Optional[int]) – The column position for ballot weights. Defaults to None, which implies each row has weight 1. Cannot be provided if id_col is also provided.
id_col (Optional[int]) – Index for the column with voter ids. Defaults to None. Cannot be provided if weight_col is also provided.
candidates (Optional[list[str]]) – List of candidate names. Defaults to None, in which case names are inferred from the CVR.
delimiter (Optional[str]) – The character that separates entries. Defaults to a comma.
header_row (Optional[int]) – The row containing the column names, below which the data begins. Defaults to None, in which case row 0 is considered to be the first ballot.
print_profile (bool) – Whether or not to print the loaded profile. Defaults to True. Useful for debugging.

Raises:

FileNotFoundError – CSV cannot be found. Raised by pandas.read_csv.
URLError – Invalid url. Raised by pandas.read_csv.
HTTPError – URL is valid but other failure occurs. Raised by pandas.read_csv.
ParserError – Pandas fails to read the csv. Raised by pandas.read_csv.
UnicodeDecodeError – Bad encoding. Raised by pandas.read_csv.
ValueError – Candidates provided but they do not exist in the CSV.
ValueError – Candidates provided but extra candidates are found in the CSV.
ValueError – Only one of weight_col or id_col can be provided.
ValueError – weight_col or id_col are not distinct from rank_cols.
ValueError – weight_col, id_col, and each entry of rank_cols must be non-negative and within the number of columns of the csv.
ValueError – If weight_col is provided, weights must be non-empty and convertible to float.
ValueError – Header must be non-negative.

Returns:

A RankProfile that represents all the ballots in the csv.

Return type:

votekit.cvr_loaders.load_ranking_csv(path_or_url: str | PathLike | Path, rank_cols: list[int], *, weight_col: int | None = None, id_col: int | None = None, candidates: list[str] | None = None, delimiter: str = ',', header_row: int | None = None, print_profile: bool = True) → RankProfile

Given a file path or url, loads ranked cast vote record (cvr) with ranks as columns and voters as rows.

Parameters:

path_or_url (Union[str, os.PathLike, pathlib.Path]) – Path or url to cvr file.
rank_cols (list[int]) – List of column indices that contain rankings. Column indexing starts from 0, in order from top to bottom rank.
weight_col (Optional[int]) – The column position for ballot weights. Defaults to None, which implies each row has weight 1. Cannot be provided if id_col is also provided.
id_col (Optional[int]) – Index for the column with voter ids. Defaults to None. Cannot be provided if weight_col is also provided.
candidates (Optional[list[str]]) – List of candidate names. Defaults to None, in which case names are inferred from the CVR.
delimiter (Optional[str]) – The character that separates entries. Defaults to a comma.
header_row (Optional[int]) – The row containing the column names, below which the data begins. Defaults to None, in which case row 0 is considered to be the first ballot.
print_profile (bool) – Whether or not to print the loaded profile. Defaults to True. Useful for debugging.

Raises:

FileNotFoundError – CSV cannot be found. Raised by pandas.read_csv.
URLError – Invalid url. Raised by pandas.read_csv.
HTTPError – URL is valid but other failure occurs. Raised by pandas.read_csv.
ParserError – Pandas fails to read the csv. Raised by pandas.read_csv.
UnicodeDecodeError – Bad encoding. Raised by pandas.read_csv.
ValueError – Candidates provided but they do not exist in the CSV.
ValueError – Candidates provided but extra candidates are found in the CSV.
ValueError – Only one of weight_col or id_col can be provided.
ValueError – weight_col or id_col are not distinct from rank_cols.
ValueError – weight_col, id_col, and each entry of rank_cols must be non-negative and within the number of columns of the csv.
ValueError – If weight_col is provided, weights must be non-empty and convertible to float.
ValueError – Header must be non-negative.

Returns:

A RankProfile that represents all the ballots in the csv.

Return type: