Iterative Rules

General Class

class embedded_voting.MultiwinnerRuleIter(k=None, quota='classic', take_min=False)

A class for multi-winner rules that are adaptations of STV to the embeddings ratings model.

Parameters:

• k (int) – The size of the committee.
• quota (str) – The quota used for the re-weighing step. Either 'droop' quota (n/(k+1) +1) or 'classic' quota (n/k).
• take_min (bool) – If True, when the total satisfaction is less than the quota, we replace the quota by the total satisfaction. By default, it is set to False.

quota

The quota used for the re-weighing step. Either 'droop' quota (n/(k+1) +1) or 'classic' quota (n/k).

Type:str

take_min

If True, when the total satisfaction is less than the quota, we replace the quota by the total satisfaction. By default, it is set to False.

Type:bool

weights

Current weight of every voter

Type:np.ndarray

features_vectors

This function return the features vectors associated to the candidates in the winning committee.

Returns:The list of the features vectors of each candidate. Each vector is of length n_dim. Return type:list

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

This function plot the evolution of the voters’ weights after each step of the rule.

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.
• verbose (bool) – If True, print the total weight divided by the number of remaining candidates at the end of each step.
• show (bool) – If True, displays the figure at the end of the function.

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

This function plot the winners 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.
• show (bool) – If True, displays the figure at the end of the function.

set_quota(quota)

A function to update the quota of the rule.

Parameters:quota (str) – The new quota, should be either 'droop' or 'classic'. Returns:The object itself. Return type:MultiwinnerRule

winners_

This function return the winning committee.

Returns:The winning committee. Return type:int list

IterRule + SVD

class embedded_voting.MultiwinnerRuleIterSVD(k=None, aggregation_rule=<function amax>, square_root=True, quota='classic', take_min=False)

Iterative multiwinner rule based on a SVD aggregation rule.

Parameters:

• k (int) – The size of the committee.
• aggregation_rule (callable) – The aggregation rule for the singular values. By default, it is the maximum.
• square_root (bool) – If True, we take the square root of the scores instead of the scores for the scored_embeddings().
• quota (str) – The quota used for the re-weighing step. Either 'droop' quota (n/(k+1) +1) or 'classic' quota (n/k).
• take_min (bool) – If True, when the total satisfaction is less than the quota, we replace the quota by the total satisfaction. By default, it is set to False.

Examples

>>> np.random.seed(42)
>>> ratings_dim_candidate = np.array([[1, 0.8, 0.5, 0, 0, 0], [0, 0, 0, 0.5, 0.8, 1]])
>>> probability = [3/4, 1/4]
>>> embeddings = EmbeddingsGeneratorPolarized(100, 2, probability)(1)
>>> ratings = RatingsFromEmbeddingsCorrelated(coherence=1, ratings_dim_candidate=ratings_dim_candidate)(embeddings)
>>> election = MultiwinnerRuleIterSVD(3)(ratings, embeddings)
>>> election.winners_
[0, 1, 5]
>>> _ = election.set_k(4)
>>> election.winners_
[0, 1, 5, 2]
>>> election.plot_weights(dim=[0, 0, 0], show=False)
Weight / remaining candidate :  [25.0, 24.99999999999999, 24.999999999999996, 30.999999999999993]
>>> election.features_vectors
Embeddings([[1., 0.],
            [1., 0.],
            [0., 1.],
            [1., 0.]])

IterRule + Features

class embedded_voting.MultiwinnerRuleIterFeatures(k=None, quota='classic', take_min=False)

Iterative multiwinner rule based on the RuleFeatures aggregation rule.

Parameters:

• k (int) – The size of the committee.
• quota (str) – The quota used for the re-weighing step. Either 'droop' quota (n/(k+1) +1) or 'classic' quota (n/k).
• take_min (bool) – If True, when the total satisfaction is less than the quota, we replace the quota by the total satisfaction. By default, it is set to False.

Examples

>>> np.random.seed(42)
>>> ratings_dim_candidate = np.array([[1, 0.8, 0.5, 0, 0, 0], [0, 0, 0, 0.5, 0.8, 1]])
>>> probability = [3/4, 1/4]
>>> embeddings = EmbeddingsGeneratorPolarized(100, 2, probability)(1)
>>> ratings = RatingsFromEmbeddingsCorrelated(coherence=1, ratings_dim_candidate=ratings_dim_candidate)(embeddings)
>>> election = MultiwinnerRuleIterFeatures(3)(ratings, embeddings)
>>> election.winners_
[0, 5, 1]
>>> _ = election.set_k(4)
>>> election.winners_
[0, 5, 1, 2]
>>> election.plot_weights(dim=[0, 0, 0], show=False)
Weight / remaining candidate :  [25.0, 24.999999999999986, 27.999999999999993, 30.999999999999986]
>>> election.features_vectors
Embeddings([[1., 0.],
            [0., 1.],
            [1., 0.],
            [1., 0.]])

static compute_features(embeddings, scores)

A function to compute features for some embeddings and scores.

Parameters:

• embeddings (np.ndarray) – The embeddings of the voters. Should be of shape n_voters, n_dim.
• scores (np.ndarray) – The scores given by the voters to the candidates. Should be of shape n_voters, n_candidates.

Returns:

The features of every candidates. Of shape n_candidates, n_dim.

Return type:

np.ndarray