Ratings Generator Epistemic¶

class embedded_voting.RatingsGeneratorEpistemic(n_voters=None, truth_generator=None)[source]¶

A generator of ratings based on a ground truth (“true value”) for each candidate.

Parameters:	n_voters (int) – The number of voters in the generator. truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

plot_ratings(show=True)[source]¶

This function plots the true value of a candidate and the ratings given by each voter for a candidate with new random values and ratings.

Parameters:	show (bool) – If True, displays the plot at the end of the function.

Grouped Mean¶

class embedded_voting.RatingsGeneratorEpistemicGroupsMean(groups_sizes, group_noise=1, independent_noise=0, truth_generator=None)[source]¶

A generator of ratings such that voters are separated into different groups and the noise of an voter on a candidate is equal to the noise of his group plus his own independent noise.

This is a particular case of RatingsGeneratorEpistemicGroupsMix when groups_features is the identity matrix, i.e. each group has its own exclusive feature.

As a result, for each candidate i:

For each group, a sigma_group is drawn (absolute part of a normal variable, scaled by group_noise). Then a noise_group is drawn (normal variable scaled by sigma_group).
For each voter, noise_dependent is equal to the noise_group of her group.
For each voter, noise_independent is drawn (normal variable scaled by independent_noise).
For each voter of each group, the rating is computed as ground_truth[i] + noise_dependent + noise_independent.

Parameters:

groups_sizes (list or np.ndarray) – The number of voters in each groups. The sum is equal to n_voters.
group_noise (float) – The variance used to sample the noise of each group.
independent_noise (float) – The variance used to sample the independent noise of each voter.
truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

Examples

>>> np.random.seed(44)
>>> generator = RatingsGeneratorEpistemicGroupsMean([2, 2])
>>> generator()  # doctest: +ELLIPSIS
Ratings([[16.3490...],
         [16.3490...],
         [19.16928...],
         [19.16928...]])
>>> generator.ground_truth_  # doctest: +ELLIPSIS
array([17.739...])

Grouped Noise¶

class embedded_voting.RatingsGeneratorEpistemicGroupsNoise(groups_sizes, group_noise=1, truth_generator=None)[source]¶

A generator of ratings such that voters are separated into different groups and for each candidate the variance of each voter of the same group is the same.

For each candidate i:

For each group, a sigma_group is drawn (absolute part of a normal variable, scaled by group_noise).
For each voter, her sigma_voter is equal to the sigma_group of her group. Her noise_voter is drawn (normal variable scaled by sigma_voter).
For each voter, the rating is computed as ground_truth[i] + noise_voter.

Parameters:	groups_sizes (list or np.ndarray) – The number of voters in each groups. The sum is equal to `n_voters`. group_noise (float) – The variance used to sample the variances of each group. truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

Examples

>>> np.random.seed(42)
>>> generator = RatingsGeneratorEpistemicGroupsNoise([2, 2])
>>> generator()  # doctest: +ELLIPSIS
Ratings([[18.196...],
         [18.812...],
         [17.652...],
         [17.652...]])
>>> generator.ground_truth_  # doctest: +ELLIPSIS
array([17.739...])

Grouped Mix¶

class embedded_voting.RatingsGeneratorEpistemicGroupsMix(groups_sizes, groups_features, group_noise=1, independent_noise=0, truth_generator=None)[source]¶

A generator of ratings such that voters are separated into different groups and the noise of an voter on a candidate is equal to the noise of his group plus his own independent noise. The noise of different groups can be correlated due to the group features.

For each candidate i:

For each feature, a sigma_feature is drawn (absolute part of a normal variable, scaled by group_noise). Then a noise_feature is drawn (normal variable scaled by sigma_feature).
For each group, noise_group is the barycenter of the values of noise_feature, with the weights for each feature given by groups_features.
For each voter, noise_dependent is equal to the noise_group of her group.
For each voter, noise_independent is drawn (normal variable scaled by independent_noise).
For each voter of each group, the rating is computed as ground_truth[i] + noise_dependent + noise_independent.

Parameters:

groups_sizes (list or np.ndarray) – The number of voters in each groups. The sum is equal to n_voters.
groups_features (list or np.ndarray) – The features of each group of voters. Should be of the same length than group_sizes. Each row of this matrix correspond to the features of a group.
group_noise (float) – The variance used to sample the noise of each group.
independent_noise (float) – The variance used to sample the independent noise of each voter.
truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

Examples

>>> np.random.seed(42)
>>> features = [[1, 0], [0, 1], [1, 1]]
>>> generator = RatingsGeneratorEpistemicGroupsMix([2, 2, 2], features)
>>> generator()  # doctest: +ELLIPSIS
Ratings([[18.1960...],
         [18.1960...],
         [18.3058...],
         [18.3058...],
         [18.2509...],
         [18.2509...]])
>>> generator.ground_truth_  # doctest: +ELLIPSIS
array([17.7395...])

>>> np.random.seed(42)
>>> features = [[1, 0, 1, 1], [0, 1, 0, 1], [1, 1, 0, 0]]
>>> generator = RatingsGeneratorEpistemicGroupsMix([2, 2, 2], features)
>>> generator() # doctest: +ELLIPSIS
Ratings([[17.951...],
         [17.951...],
         [17.737...],
         [17.737...],
         [18.438...],
         [18.438...]])

Multivariate¶

class embedded_voting.RatingsGeneratorEpistemicMultivariate(covariance_matrix, independent_noise=0, truth_generator=None)[source]¶

A generator of ratings based on a covariance matrix.

Parameters:	covariance_matrix (np.ndarray) – The covariance matrix of the voters. Should be of shape `n_voters`, `n_voters`. independent_noise (float) – The variance of the independent noise. truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

Examples

>>> np.random.seed(42)
>>> generator = RatingsGeneratorEpistemicMultivariate(np.ones((5, 5)))
>>> generator()  # doctest: +ELLIPSIS
Ratings([[17.2428...],
         [17.2428...],
         [17.2428...],
         [17.2428...],
         [17.2428...]])
>>> generator.independent_noise = 0.5
>>> generator()  # doctest: +ELLIPSIS
Ratings([[14.5710...],
         [14.3457...],
         [15.0093...],
         [14.3981...],
         [14.1460...]])

Grouped Mix Free¶

class embedded_voting.RatingsGeneratorEpistemicGroupsMixFree(groups_sizes, groups_features, group_noise=1, independent_noise=0, truth_generator=None, group_noise_f=None, independent_noise_f=None)[source]¶

A generator of ratings such that voters are separated into different groups and the noise of an voter on a candidate is equal to the noise of his group plus his own independent noise. The noise of different groups can be correlated due to the group features.

For each candidate i:

For each feature, a sigma_feature is drawn (absolute part of a normal variable, scaled by group_noise). Then a noise_feature is drawn according to group_noise_f (scaled by group_noise).
For each group, noise_group is the barycenter of the values of noise_feature, with the weights for each feature given by groups_features.
For each voter, noise_dependent is equal to the noise_group of her group.
For each voter, noise_independent is drawn according to independent_noise_f (scaled by independent_noise).
For each voter of each group, the rating is computed as ground_truth[i] + noise_dependent + noise_independent.

Parameters:

groups_sizes (list or np.ndarray) – The number of voters in each groups. The sum is equal to n_voters.
groups_features (list or np.ndarray) – The features of each group of voters. Should be of the same length than group_sizes. Each row of this matrix correspond to the features of a group.
group_noise (float) – The variance used to sample the noise of each group.
independent_noise (float) – The variance used to sample the independent noise of each voter.
truth_generator (TruthGenerator) – The truth generator used to generate to true values of each candidate. Default: TruthGeneratorUniform(10, 20).
group_noise_f (function) – The function used to sample the noise of each group. Default: np.random.normal.
independent_noise_f (function) – The function used to sample the independent noise of each voter. Default: np.random.normal.

ground_truth_¶

The ground truth (“true value”) for each candidate, corresponding to the last ratings generated.

Type:	np.ndarray

Examples

>>> np.random.seed(42)
>>> features = [[1, 0], [0, 1], [1, 1]]
>>> generator = RatingsGeneratorEpistemicGroupsMixFree([2, 2, 2], features, group_noise_f=np.random.normal, independent_noise_f=np.random.normal)
>>> generator()  # doctest: +ELLIPSIS
Ratings([[18.23627...],
         [18.23627...],
         [17.60129...],
         [17.60129...],
         [17.99302...],
         [17.99302...]])
>>> generator.ground_truth_  # doctest: +ELLIPSIS
array([17.73956...])