SVD Rules

General SVD

class embedded_voting.RuleSVD(aggregation_rule=<function prod>, square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is based on singular values of his embedding matrix (cf times_ratings_candidate()).

Implicitly, ratings are assumed to be nonnegative.

Parameters:

• aggregation_rule (callable) – The aggregation rule for the singular values. Input : float list. Output : float. By default, it is the product of the singular values.
• square_root (boolean) – If True, use the square root of ratings in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVD()(ratings, embeddings)
>>> election.scores_  # DOCTEST: +ELLIPSIS
[0.6041522986797..., 0.547722557505..., 0.5567764362830...]
>>> election.ranking_
[0, 2, 1]
>>> election.winner_
0
>>> election.welfare_  # DOCTEST: +ELLIPSIS
[1.0, 0.0, 0.16044515869439...]

Special cases

class embedded_voting.RuleSVDSum(square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is the sum of the singular values of his embedding matrix (cf times_ratings_candidate()).

Parameters:

• square_root (boolean) – If True, use the square root of score in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDSum()(ratings, embeddings)
>>> election.scores_  # DOCTEST: +ELLIPSIS
[1.6150246429573..., 1.6417810801109..., 1.5535613514007...]
>>> election.ranking_
[1, 0, 2]
>>> election.winner_
1
>>> election.welfare_  # DOCTEST: +ELLIPSIS
[0.6967068756070..., 1.0, 0.0]

class embedded_voting.RuleSVDNash(square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is the product of the singular values of his embedding matrix (cf times_ratings_candidate()).

Parameters:

• square_root (boolean) – If True, use the square root of score in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDNash()(ratings, embeddings)
>>> election.scores_   # DOCTEST: +ELLIPSIS
[0.6041522986797..., 0.547722557505..., 0.5567764362830...]
>>> election.ranking_
[0, 2, 1]
>>> election.winner_
0
>>> election.welfare_  # DOCTEST: +ELLIPSIS
[1.0, 0.0, 0.16044515869439...]

class embedded_voting.RuleSVDMin(square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is the minimum singular value of his embedding matrix (cf times_ratings_candidate()).

Parameters:

• square_root (boolean) – If True, use the square root of score in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDMin()(ratings, embeddings)
>>> election.scores_
[0.5885971537535042, 0.4657304054015261, 0.5608830567730065]
>>> election.ranking_
[0, 2, 1]
>>> election.winner_
0
>>> election.welfare_
[1.0, 0.0, 0.7744377762720253]

class embedded_voting.RuleSVDMax(square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is the maximum singular value of his embedding matrix (cf times_ratings_candidate()).

Parameters:

• square_root (boolean) – If True, use the square root of score in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDMax()(ratings, embeddings)
>>> election.scores_  # DOCTEST: +ELLIPSIS
[1.0264274892038..., 1.1760506747094..., 0.9926782946277...]
>>> election.ranking_
[1, 0, 2]
>>> election.winner_
1
>>> election.welfare_  # DOCTEST: +ELLIPSIS
[0.184047317055..., 1.0, 0.0]

features_

A function to get the feature vectors of all the candidates. The feature vector is defined as the singular vector associated to the maximal singular value.

Returns:The feature vectors of all the candidates, of shape n_candidates, n_dim. Return type:np.ndarray

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDMax()(ratings, embeddings)
>>> election.features_
array([[0.94829535, 0.39279679],
       [0.31392742, 1.13337759],
       [0.22807074, 0.96612315]])

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

This function plot the features vector of every candidates in the given dimensions.

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.

class embedded_voting.RuleSVDLog(const=1, square_root=True, use_rank=False, embedded_from_ratings=None)

Voting rule in which the aggregated score of a candidate is the sum of log(1 + sigma/const) where sigma are the singular values of his embedding matrix and const is a constant.

Parameters:

• const (float) – The constant by which we divide the singular values in the log.
• square_root (boolean) – If True, use the square root of score in the matrix. By default, it is True.
• use_rank (boolean) – If True, consider the rank of the matrix when doing the ranking. By default, it is False.
• embedded_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().

Examples

>>> ratings = Ratings(np.array([[.5, .6, .3], [.7, 0, .2], [.2, 1, .8]]))
>>> embeddings = Embeddings(np.array([[1, 1], [1, 0], [0, 1]]), norm=True)
>>> election = RuleSVDLog()(ratings, embeddings)
>>> election.scores_
[1.169125718695728, 1.1598653051965206, 1.1347313336962574]
>>> election.ranking_
[0, 1, 2]
>>> election.winner_
0
>>> election.welfare_
[1.0, 0.7307579856610341, 0.0]