General Class

class embedded_voting.Rule(score_components=1, embeddings_from_ratings=None)

The general class of functions for scoring rules. These rules aggregate the scores of every voter to create a ranking of the candidates and select a winner.

Parameters:

• score_components (int) – The number of components in the aggregated score of every candidate. If > 1, we perform a lexical sort to obtain the ranking.
• embeddings_from_ratings (EmbeddingsFromRatings) – If no embeddings are specified in the call, this EmbeddingsFromRatings object is use to generate the embeddings from the ratings. Default: EmbeddingsFromRatingsIdentity().

ratings_

The ratings of voters on which we run the election.

Type:Ratings

embeddings_

The embeddings of the voters on which we run the election.

Type:Embeddings

plot_ranking(plot_kind='3D', dim=None, row_size=5, show=True)

Plot the matrix associated to each candidate, in the same order than the ranking of the election.

Parameters:

• plot_kind (str) – The kind of plot we want to show. Can be '3D' or 'ternary'.
• dim (list) – The 3 dimensions we are using for our plot. By default, it is set to [0, 1, 2].
• row_size (int) – Number of subplots by row. By default, it is set to 5 by rows.
• show (bool) – If True, displays the figure at the end of the function.

plot_winner(plot_kind='3D', dim=None, fig=None, plot_position=None, show=True)

Plot the matrix associated to the winner of the election.

Cf. Embeddings.plot_candidate().

Parameters:

• plot_kind (str) – The kind of plot we want to show. Can be '3D' or 'ternary'.
• dim (list) – The 3 dimensions we are using for our plot. By default, it is set to [0, 1, 2].
• fig (matplotlib figure) – The figure on which we add the plot.
• plot_position (list) – The position of the plot on the figure. Should be of the form [n_rows, n_columns, position].
• show (bool) – If True, displays the figure at the end of the function.

Returns:

The ax with the plot.

Return type:

matplotlib ax

ranking_

Return the ranking of the candidates based on their aggregated scores.

Returns:The ranking of the candidates. In case of tie, candidates with lower indices are favored. Return type:list of int

score_(candidate)

Return the aggregated score of a given candidate.

Parameters:candidate (int) – Index of the candidate for whom we want the score. Returns:if score_components = 1, return a float, otherwise a tuple of length score_components. Return type:float or tuple

scores_

Return the aggregated scores of all candidates.

Returns:The scores of all candidates. The score of each candidate is a float if score_components = 1 and a tuple of length score_components otherwise. Return type:list

scores_focus_on_last_

Return the last score component of each candidate, but only if the other score components are maximal.

If score_components is 1, return scores_. Otherwise, for each candidate:

• Return the last score component if all other components are maximal.
• Return 0 otherwise.

Note that if the last score component is defined as non-negative, and if it is always positive for the winner, then scores_focus_on_last_ is enough to determine which candidate has the best score by lexicographical order.

Returns:The scores of every candidates. Return type:float list

Examples

Cf. RuleMaxParallelepiped.

welfare_

Return the welfare of all candidates, where the welfare is defined as (score - score_min)/(score_max - score_min).

If scores are tuple, then scores_focus_on_last_ is used.

If score_max = score_min, then by convention, all candidates have a welfare of 1.

Returns:Welfare of all candidates. Return type:list of float

winner_

Return the winner of the election.

Returns:The index of the winner of the election. In case of tie, candidates with lower indices are favored. Return type:int