class svvamp.ProfileSubsetCandidates(parent_profile, candidates_subset)[source]#

Sub-profile for a subset of the original candidates.

This class is used internally by SVVAMP. It is not intended for the end user.

Parameters:

  • parent_profile (Profile) – The initial profile.

  • candidates_subset (list) – Normally a list of candidates indexes, like [0, 2, 3], but a list of booleans like [True False True True False] should work as well. Candidates belonging to the subset.

Notes

N.B.: if candidates_subset is a list of integers, it must be sorted in ascending order.

N.B.: in this object, candidates are re-numbered, for example [0, 1, 2]. So, if the winner of an election is w in the sub-profile, it corresponds to candidates_subset[w] in the parent profile (supposing that candidates_subset is given as a list of indexes, not as a list of booleans).

Examples

>>> initialize_random_seeds()
>>> preferences_ut_test = np.random.randint(-5, 5, (10, 5))
>>> parent_profile = Profile(preferences_ut=preferences_ut_test)
>>> profile = ProfileSubsetCandidates(parent_profile=parent_profile, candidates_subset=[0, 1, 2])
>>> profile.labels_candidates
['0', '1', '2']
>>> profile.preferences_borda_ut
array([[2. , 0. , 1. ],
       [2. , 0. , 1. ],
       [1. , 0. , 2. ],
       [0. , 1.5, 1.5],
       [0. , 2. , 1. ],
       [1.5, 0. , 1.5],
       [0. , 1. , 2. ],
       [0.5, 0.5, 2. ],
       [1.5, 1.5, 0. ],
       [1. , 0. , 2. ]])
>>> profile.matrix_duels_ut
array([[0, 5, 3],
       [3, 0, 2],
       [6, 7, 0]])
>>> profile.matrix_duels_rk
array([[0, 6, 3],
       [4, 0, 2],
       [7, 8, 0]])
>>> profile.matrix_victories_ut_abs
array([[0. , 0.5, 0. ],
       [0. , 0. , 0. ],
       [1. , 1. , 0. ]])
>>> profile.matrix_victories_ut_abs_ctb
array([[0., 1., 0.],
       [0., 0., 0.],
       [1., 1., 0.]])
>>> profile.matrix_victories_ut_rel
array([[0., 1., 0.],
       [0., 0., 0.],
       [1., 1., 0.]])
>>> profile.matrix_victories_ut_rel_ctb
array([[0., 1., 0.],
       [0., 0., 0.],
       [1., 1., 0.]])
>>> profile.matrix_victories_rk
array([[0., 1., 0.],
       [0., 0., 0.],
       [1., 1., 0.]])
>>> profile.matrix_victories_rk_ctb
array([[0., 1., 0.],
       [0., 0., 0.],
       [1., 1., 0.]])
>>> profile.total_utility_c
array([ 2, -8,  6])

Instead, the subset of candidates can be given by a list of Booleans:

>>> profile = ProfileSubsetCandidates(
...     parent_profile=parent_profile,
...     candidates_subset=[True, True, True, False, False]
... )
>>> profile.n_c
3
property labels_candidates#

List of n_c strings (names of the candidates).

property matrix_duels_rk#

2d array of integers. matrix_duels_rk[c, d] is the number of voters who rank candidate c before d (in the sense of preferences_rk). By convention, diagonal coefficients are set to 0.

>>> from svvamp import Profile
>>> profile = Profile(preferences_rk=[[0, 1, 2], [0, 1, 2]])
>>> profile.matrix_duels_rk
array([[0, 2, 2],
       [0, 0, 2],
       [0, 0, 0]])
property matrix_duels_ut#

2d array of integers. matrix_duels_ut[c, d] is the number of voters who have a strictly greater utility for c than for d. By convention, diagonal coefficients are set to 0.

>>> from svvamp import Profile
>>> profile = Profile(preferences_rk=[[0, 1, 2], [0, 1, 2]])
>>> profile.matrix_duels_ut
array([[0, 2, 2],
       [0, 0, 2],
       [0, 0, 0]])
property matrix_victories_rk#

2d array of values in {0, 0.5, 1}. Matrix of victories based on matrix_duels_rk.

matrix_victories_rk[c, d] is:

  • 1 iff matrix_duels_rk[c, d] > matrix_duels_rk[d, c], i.e. iff matrix_duels_rk[c, d] > V / 2.

  • 0.5 iff matrix_duels_rk[c, d] = matrix_duels_rk[d, c], i.e. iff matrix_duels_rk[c, d] = V / 2.

  • 0 iff matrix_duels_rk[c, d] < matrix_duels_rk[d, c], i.e. iff matrix_duels_rk[c, d] < V / 2.

By convention, diagonal coefficients are set to 0.

Examples

A victory:

>>> profile = Profile(preferences_rk=[[0, 1], [0, 1]])
>>> profile.matrix_victories_rk
array([[0., 1.],
       [0., 0.]])

A tie:

>>> profile = Profile(preferences_rk=[[0, 1], [1, 0]])
>>> profile.matrix_victories_rk
array([[0. , 0.5],
       [0.5, 0. ]])
property matrix_victories_rk_ctb#

2d array of values in {0, 1}. Matrix of victories based on matrix_duels_rk, with tie-breaks on candidates.

matrix_victories_rk_ctb[c, d] is:

  • 1 iff matrix_duels_rk[c, d] > matrix_duels_rk[d, c], or matrix_duels_rk[c, d] = matrix_duels_rk[d, c] and c < d.

  • 0 iff matrix_duels_rk[c, d] < matrix_duels_rk[d, c], or matrix_duels_rk[c, d] = matrix_duels_rk[d, c] and d < c.

By convention, diagonal coefficients are set to 0.

Examples

A victory (without tie-breaking):

>>> profile = Profile(preferences_rk=[[0, 1], [0, 1]])
>>> profile.matrix_victories_rk_ctb
array([[0., 1.],
       [0., 0.]])

A victory with tie-breaking:

>>> profile = Profile(preferences_rk=[[0, 1], [1, 0]])
>>> profile.matrix_victories_rk_ctb
array([[0., 1.],
       [0., 0.]])
property matrix_victories_ut_abs#

2d array of values in {0, 0.5, 1}. Matrix of absolute victories based on matrix_duels_ut.

matrix_victories_ut_abs[c, d] is:

  • 1 iff matrix_duels_ut[c, d] > V / 2.

  • 0.5 iff matrix_duels_ut[c, d] = V / 2.

  • 0 iff matrix_duels_ut[c, d] < V / 2.

By convention, diagonal coefficients are set to 0.

Examples

A victory:

>>> profile = Profile(preferences_ut=[[1, 0], [1, 0]])
>>> profile.matrix_victories_ut_abs
array([[0., 1.],
       [0., 0.]])

A half-victory, but the other candidate has lost:

>>> profile = Profile(preferences_ut=[[1, 0], [42, 42]])
>>> profile.matrix_victories_ut_abs
array([[0. , 0.5],
       [0. , 0. ]])

A half-victory for each candidate:

>>> profile = Profile(preferences_ut=[[1, 0], [0, 1]])
>>> profile.matrix_victories_ut_abs
array([[0. , 0.5],
       [0.5, 0. ]])

A defeat for each candidate:

>>> profile = Profile(preferences_ut=[[0, 0], [0, 0]])
>>> profile.matrix_victories_ut_abs
array([[0., 0.],
       [0., 0.]])
property matrix_victories_ut_abs_ctb#

2d array of values in {0, 1}. Matrix of absolute victories based on matrix_duels_ut, with tie-breaks on candidates.

matrix_victories_ut_abs_ctb[c, d] is:

  • 1 iff matrix_duels_ut[c, d] > V / 2, or matrix_duels_ut[c, d] = V / 2 and c < d.

  • 0 iff matrix_duels_ut[c, d] < V / 2, or matrix_duels_ut[c, d] = V / 2 and d < c.

By convention, diagonal coefficients are set to 0.

Examples

A victory (without tie-breaking):

>>> profile = Profile(preferences_ut=[[1, 0], [1, 0]])
>>> profile.matrix_victories_ut_abs_ctb
array([[0., 1.],
       [0., 0.]])

A victory with tie-breaking:

>>> profile = Profile(preferences_ut=[[1, 0], [0, 1]])
>>> profile.matrix_victories_ut_abs_ctb
array([[0., 1.],
       [0., 0.]])

Another case of victory with tie-breaking:

>>> profile = Profile(preferences_ut=[[1, 0], [42, 42]])
>>> profile.matrix_victories_ut_abs_ctb
array([[0., 1.],
       [0., 0.]])

A defeat for each candidate:

>>> profile = Profile(preferences_ut=[[0, 0], [0, 0]])
>>> profile.matrix_victories_ut_abs_ctb
array([[0., 0.],
       [0., 0.]])
property matrix_victories_ut_rel#

2d array of values in {0, 0.5, 1}. Matrix of relative victories based on matrix_duels_ut.

matrix_victories_ut_rel[c, d] is:

  • 1 iff matrix_duels_ut[c, d] > matrix_duels_ut[d, c].

  • 0.5 iff matrix_duels_ut[c, d] = matrix_duels_ut[d, c].

  • 0 iff matrix_duels_ut[c, d] < matrix_duels_ut[d, c].

By convention, diagonal coefficients are set to 0.

Examples

A relative victory (which is not an absolute victory):

>>> profile = Profile(preferences_ut=[[1, 0], [0, 0], [0, 0]])
>>> profile.matrix_victories_ut_rel
array([[0., 1.],
       [0., 0.]])

A tie:

>>> profile = Profile(preferences_ut=[[1, 0], [0, 1], [0, 0]])
>>> profile.matrix_victories_ut_rel
array([[0. , 0.5],
       [0.5, 0. ]])
property matrix_victories_ut_rel_ctb#

2d array of values in {0, 1}. Matrix of relative victories based on matrix_duels_ut, with tie-breaks on candidates.

matrix_victories_ut_rel_ctb[c, d] is:

  • 1 iff matrix_duels_ut[c, d] > matrix_duels_ut[d, c], or matrix_duels_ut[c, d] = matrix_duels_ut[d, c] and c < d.

  • 0 iff matrix_duels_ut[c, d] < matrix_duels_ut[d, c], or matrix_duels_ut[c, d] = matrix_duels_ut[d, c] and d < c.

By convention, diagonal coefficients are set to 0.

Examples

A relative victory (without tie-breaking):

>>> profile = Profile(preferences_ut=[[1, 0], [0, 0], [0, 0]])
>>> profile.matrix_victories_ut_rel_ctb
array([[0., 1.],
       [0., 0.]])

A relative victory with tie-breaking:

>>> profile = Profile(preferences_ut=[[1, 0], [0, 1], [0, 0]])
>>> profile.matrix_victories_ut_rel_ctb
array([[0., 1.],
       [0., 0.]])
property n_c#

Number of candidates.

Type:

int

property n_v#

Number of voters.

Type:

int

property preferences_borda_rk#

2d array of integers. preferences_borda_rk[v, c] gains 1 point for each candidate d such that voter v ranks c before d. So, these Borda scores are between 0 and C - 1.

property preferences_borda_ut#

2d array of floats. preferences_borda_ut[v, c] gains 1 point for each d such that v strictly prefers c to d (in the sense of utilities), and 0.5 point for each d such that v is indifferent between c and d. So, these Borda scores are between 0 and C - 1.

property preferences_rk#

2d array of integers. preferences_rk[v, k] is the candidate at rank k for voter v. For example, preferences_rk[v, 0] is v’s preferred candidate.

property preferences_ut#

2d array of floats. preferences_ut[v, c] is the utility of candidate c as seen by voter v.

property total_utility_c#

1d array of numbers. total_utility_c[c] is the total utility for candidate c (i.e. the sum of c’s column in matrix preferences_ut).

Examples

>>> from svvamp import Profile
>>> profile = Profile(preferences_ut=[[5, 1, 2], [4, 10, 1]])
>>> profile.total_utility_c
array([ 9, 11,  3])