Embeddings¶

class embedded_voting.Embeddings[source]¶

Embeddings of the voters.

Parameters:	positions (np.ndarray or list or Embeddings) – The embeddings of the voters. Its dimensions are `n_voters`, `n_dim`. norm (bool) – If True, normalize the embeddings.

n_voters¶

The number of voters in the ratings.

Type:	int

n_dim¶

The number of dimensions of the voters’ embeddings.

Type:	int

Examples

>>> embeddings = Embeddings([[1, 0], [0, 1], [0.5, 0.5]], norm=True)
>>> embeddings.n_voters
3
>>> embeddings.n_dim
2
>>> embeddings.voter_embeddings(0)
array([1., 0.])

copy(order='C')[source]¶

Return a copy of the array.

Parameters: order ({'C', 'F', 'A', 'K'}, optional) – Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and numpy.copy() are very similar but have different default values for their order= arguments, and this function always passes sub-classes through.)

See also

numpy.copy(): Similar function with different default behavior

numpy.copyto()

Notes

This function is the preferred method for creating an array copy. The function numpy.copy() is similar, but it defaults to using order ‘K’, and will not pass sub-classes through by default.

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

dilated(approx=True)[source]¶

Dilate the embeddings of the voters so that they take more space.

The center is computed with get_center(). The angular dilatation factor is such that after transformation, the maximum angle between the center and an embedding vector will be pi / 4.

Parameters:	approx (bool) – Passed to `get_center()` in order to compute the center of the voters’ embeddings.
Returns:	A new Embeddings object with the dilated embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings(np.array([[.5,.4,.4],[.4,.4,.5],[.4,.5,.4]]), norm=True)
>>> embeddings
Embeddings([[0.66226618, 0.52981294, 0.52981294],
            [0.52981294, 0.52981294, 0.66226618],
            [0.52981294, 0.66226618, 0.52981294]])
>>> embeddings.dilated()
Embeddings([[0.98559856, 0.11957316, 0.11957316],
            [0.11957316, 0.11957316, 0.98559856],
            [0.11957316, 0.98559856, 0.11957316]])

Note that the resulting embedding may not be in the positive orthant, even if the original embedding is:

>>> embeddings = Embeddings([[1, 0], [.7, .7]], norm=True)
>>> embeddings.dilated()
Embeddings([[ 0.92387953, -0.38268343],
            [ 0.38268343,  0.92387953]])

>>> Embeddings([[1, 0]], norm=True).dilated()
Embeddings([[1., 0.]])

dilated_aux(center, k)[source]¶

Dilate the embeddings of the voters.

For each vector of the embedding, we apply a “spherical dilatation” that moves vector by multiplying the angle between center and vector by a given dilatation factor.

More formally, for each vector of the embedding, there exists a unit vector unit_orthogonal and an angle theta in [0, pi/2] such that vector = norm(vector) * (cos(theta) * center + sin(theta) * unit_orthogonal). Then the image of vector is norm(vector) * (cos(k * theta) * center + sin(k * theta) * unit_orthogonal).

Parameters:	center (np.ndarray) – Unit vector: center of the dilatation. k (float) – Angular dilatation factor.
Returns:	A new Embeddings object with the dilated embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings([[1, 0], [1, 1]], norm=True)
>>> dilated_embeddings = embeddings.dilated_aux(center=np.array([1, 0]), k=2)
>>> np.round(dilated_embeddings, 4)
array([[1., 0.],
       [0., 1.]])

>>> embeddings = Embeddings([[1, 0], [1, 1]], norm=False)
>>> dilated_embeddings = embeddings.dilated_aux(center=np.array([1, 0]), k=2)
>>> np.abs(np.round(dilated_embeddings, 4)) # Abs for rounding errors
array([[1.    , 0.    ],
       [0.    , 1.4142]])

dilated_new(approx=True)[source]¶

Dilate the embeddings of the voters so that they take more space in the positive orthant.

The center is computed with get_center(). The angular dilatation factor the largest possible so that all vectors stay in the positive orthant. Cf. max_angular_dilatation_factor().

Parameters:	approx (bool) – Passed to `get_center()` in order to compute the center of the voters’ embeddings.
Returns:	A new Embeddings object with the dilated embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings(np.array([[.5,.4,.4],[.4,.4,.5],[.4,.5,.4]]), norm=True)
>>> embeddings
Embeddings([[0.66226618, 0.52981294, 0.52981294],
            [0.52981294, 0.52981294, 0.66226618],
            [0.52981294, 0.66226618, 0.52981294]])
>>> dilated_embeddings = embeddings.dilated_new()
>>> np.abs(np.round(dilated_embeddings, 4))
array([[1., 0., 0.],
       [0., 0., 1.],
       [0., 1., 0.]])

>>> embeddings = Embeddings([[1, 0], [.7, .7]], norm=True)
>>> dilated_embeddings = embeddings.dilated_new()
>>> np.abs(np.round(dilated_embeddings, 4))
array([[1.    , 0.    ],
       [0.7071, 0.7071]])

>>> embeddings = Embeddings([[2, 1], [100, 200]], norm=False)
>>> dilated_embeddings = embeddings.dilated_new()
>>> np.round(dilated_embeddings, 4)
array([[  2.2361,   0.    ],
       [  0.    , 223.6068]])

get_center(approx=True)[source]¶

Return the center direction of the embeddings.

For this method, we work on the normalized embeddings. Cf. normalized().

With approx set to False, we use an exponential algorithm in n_dim. If r is the rank of the embedding matrix, we first find the r voters with maximal determinant (in absolute value), i.e. whose associated parallelepiped has the maximal volume (e.g. in two dimensions, it means finding the two vectors with maximal angle). Then the result is the mean of the embeddings of these voters, normalized in the sense of the Euclidean norm.

With approx set to True, we use a polynomial algorithm: we simply take the mean of the embeddings of all the voters, normalized in the sense of the Euclidean norm.

Parameters:	approx (bool) – Whether the computation is approximate.
Returns:	The normalized position of the center vector. Size: `n_dim`.
Return type:	np.ndarray

Examples

>>> embeddings = Embeddings([[1, 0], [0, 1], [.5, .5], [.7, .3]], norm=True)
>>> embeddings.get_center(approx=False)
array([0.70710678, 0.70710678])

>>> embeddings = Embeddings([[1, 0], [0, 1], [.5, .5], [.7, .3]], norm=False)
>>> embeddings.get_center(approx=False)
array([0.70710678, 0.70710678])

>>> embeddings = Embeddings([[1, 0], [0, 1], [.5, .5], [.7, .3]], norm=True)
>>> embeddings.get_center(approx=True)
array([0.78086524, 0.62469951])

mixed_with(other, intensity)[source]¶

Mix this embedding with another one.

Parameters:	other (Embeddings) – Another embedding with the name number of voters and same number of dimensions. intensity (float) – Must be in [0, 1].
Returns:	A new Embeddings object with the mixed embeddings.
Return type:	Embeddings

Examples

For a given voter, the direction of the final embedding is an “angular barycenter” between the original direction and the direction in other, with mixing parameter intensity:

>>> embeddings = Embeddings([[1, 0]], norm=True)
>>> other_embeddings = Embeddings([[0, 1]], norm=True)
>>> embeddings.mixed_with(other_embeddings, intensity=1/3)
Embeddings([[0.8660254, 0.5      ]])

For a given voter, the norm of the final embedding is a barycenter between the original norm and the norm in other, with mixing parameter intensity:

>>> embeddings = Embeddings([[1, 0]], norm=False)
>>> other_embeddings = Embeddings([[5, 0]], norm=False)
>>> embeddings.mixed_with(other_embeddings, intensity=1/4)
Embeddings([[2., 0.]])

normalized()[source]¶

Normalize the embeddings of the voters so the Euclidean norm of every embedding is 1.

Returns:	A new Embeddings object with the normalized embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings(-np.array([[.5,.9,.4],[.4,.7,.5],[.4,.2,.4]]), norm=False)
>>> embeddings
Embeddings([[-0.5, -0.9, -0.4],
            [-0.4, -0.7, -0.5],
            [-0.4, -0.2, -0.4]])
>>> embeddings.normalized()
Embeddings([[-0.45267873, -0.81482171, -0.36214298],
            [-0.42163702, -0.73786479, -0.52704628],
            [-0.66666667, -0.33333333, -0.66666667]])

plot(plot_kind='3D', dim: list = None, fig=None, plot_position=None, show=True)[source]¶

Plot the embeddings of the voters, either on a 3D plot, or on a ternary plot. Only three dimensions can be represented.

Parameters:	plot_kind (str) – The kind of plot we want to show. Can be `'3D'` or `'ternary'`. dim (list) – A list of length 3 containing the three dimensions of the embeddings we want to plot. All elements of this list should be lower than `n_dim`. By default, it is set to `[0, 1, 2]`. fig (matplotlib figure) – The figure on which we add the plot. The default figure is a 8 x 8 matplotlib figure. plot_position (list) – List of length 3 containing the matplotlib position `[n_rows, n_columns, position]`. By default, it is set to `[1, 1, 1]`. show (bool) – If True, display the figure at the end of the function.
Returns:	The matplotlib ax with the figure, if you want to add something to it.
Return type:	matplotlib ax

plot_candidate(ratings, candidate, plot_kind='3D', dim: list = None, fig=None, plot_position=None, show=True)[source]¶

Plot the matrix associated to a candidate.

The embedding of each voter is multiplied by the rating she assigned to the candidate.

Parameters:	ratings (np.ndarray) – Matrix of ratings given by voters to the candidates. candidate (int) – The candidate for which we want to show the ratings. Should be lower than `n_candidates` of ratings. plot_kind (str) – The kind of plot we want to show. Can be `'3D'` or `'ternary'`. 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]`. dim (list) – The 3 dimensions we are using for our plot. By default, it is set to `[0, 1, 2]`. show (bool) – If True, display the figure at the end of the function.
Returns:	The matplotlib ax with the figure, if you want to add something to it.
Return type:	matplotlib ax

plot_candidates(ratings, plot_kind='3D', dim: list = None, list_candidates=None, list_titles=None, row_size=5, show=True)[source]¶

Plot the matrix associated to a candidate for every candidate in a list of candidates.

Parameters:

ratings (Ratings) – Ratings given by voters to candidates.
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].
list_candidates (int list) – The list of candidates we want to plot. Should contains integer lower than n_candidates. By default, we plot every candidates.
list_titles (str list) – Contains the title of the plots. Should be the same length than list_candidates.
row_size (int) – Number of subplots by row. By default, it is set to 5 plots by rows.
show (bool) – If True, display the figure at the end of the function.

plot_ratings_candidate(ratings_candidate, title='', plot_kind='3D', dim: list = None, fig=None, plot_position=None, show=True)[source]¶

Plot the matrix associated to a candidate.

The embedding of each voter is multiplied by the rating she assigned to the candidate.

Parameters:	ratings_candidate (np.ndarray) – The rating each voters assigned to the given candidate. Should be of length `n_voters`. title (str) – Title of the figure. plot_kind (str) – The kind of plot we want to show. Can be `'3D'` or `'ternary'`. 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]`. dim (list) – The 3 dimensions we are using for our plot. By default, it is set to `[0, 1, 2]`. show (bool) – If True, display the figure at the end of the function.
Returns:	The matplotlib ax with the figure, if you want to add something to it.
Return type:	matplotlib ax

recentered(approx=True)[source]¶

Recenter the embeddings so that their new center is [1, …, 1].

Parameters:	approx (bool) – Passed to `get_center()` in order to compute the center of the voters’ embeddings.
Returns:	A new Embeddings object with the recentered embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings(-np.array([[.5,.9,.4],[.4,.7,.5],[.4,.2,.4]]), norm=True)
>>> embeddings
Embeddings([[-0.45267873, -0.81482171, -0.36214298],
            [-0.42163702, -0.73786479, -0.52704628],
            [-0.66666667, -0.33333333, -0.66666667]])
>>> embeddings.recentered()
Embeddings([[0.40215359, 0.75125134, 0.52334875],
            [0.56352875, 0.6747875 , 0.47654713],
            [0.70288844, 0.24253193, 0.66867489]])

>>> embeddings = Embeddings([[1, 0], [np.sqrt(3)/2, 1/2], [1/2, np.sqrt(3)/2]], norm=True)
>>> embeddings
Embeddings([[1.       , 0.       ],
            [0.8660254, 0.5      ],
            [0.5      , 0.8660254]])
>>> embeddings.recentered(approx=False)
Embeddings([[0.96592583, 0.25881905],
            [0.70710678, 0.70710678],
            [0.25881905, 0.96592583]])

recentered_and_dilated(approx=True)[source]¶

Recenter and dilate.

This is just a shortcut for the (common) operation recentered(), then dilated_new().

Parameters:	approx (bool) – Passed to `get_center()` in order to compute the center of the voters’ embeddings.
Returns:	A new Embeddings object with the recentered and dilated embeddings.
Return type:	Embeddings

Examples

>>> embeddings = Embeddings([[1, 0], [np.sqrt(3)/2, 1/2], [1/2, np.sqrt(3)/2]], norm=True)
>>> embeddings
Embeddings([[1.       , 0.       ],
            [0.8660254, 0.5      ],
            [0.5      , 0.8660254]])
>>> new_embeddings = embeddings.recentered_and_dilated(approx=False)
>>> np.abs(np.round(new_embeddings, 4))
array([[1.    , 0.    ],
       [0.7071, 0.7071],
       [0.    , 1.    ]])

times_ratings_candidate(ratings_candidate)[source]¶

This method computes the embeddings multiplied by the ratings given by the voters to a given candidate. For each voter, its embeddings are multiplied by the given rating.

Parameters:	ratings_candidate (np.ndarray) – The vector of ratings given by the voters to a given candidate.
Returns:	A new Embeddings object, where the embedding of each voter is multiplied by the rating she assigned to the candidate.
Return type:	Embddings

Examples

>>> embeddings = Embeddings(np.array([[1, 0], [0, 1], [0.5, 0.5]]), norm=False)
>>> embeddings.times_ratings_candidate(np.array([.8, .5, .4]))
Embeddings([[0.8, 0. ],
            [0. , 0.5],
            [0.2, 0.2]])