Profile#

class actinvoting.Profile(d_ranking_multiplicity=None, d_borda_multiplicity=None)[source]#

A voting profile.

Parameters:

  • d_ranking_multiplicity (dict) – Key: ranking as a tuple. Value: multiplicity (number of voters, or weight).

  • d_borda_multiplicity (dict) – Key: ranking in Borda format as a tuple. Value: multiplicity (number of voters, or weight).

Examples

A profile can be represented in several ways: a dictionary associating ranking to multiplicities (number of voters), an array of unique rankings and the corresponding vector of multiplicities, as well as both these possibilities with Borda vectors instead of rankings.

You should avoid the default initialization method Profile(…), because its syntax is quite likely to change over time. Instead, use the constructors which explicitly specify the input format:

>>> print(Profile.from_d_ranking_multiplicity({(0, 1, 2): 3, (1, 0, 2): 2}))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

>>> print(Profile.from_d_borda_multiplicity({(2, 1, 0): 3, (1, 2, 0): 2}))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

>>> print(Profile.from_unique_rankings_and_multiplicities(
...     unique_rankings=[[0, 1, 2], [1, 0, 2]], multiplicities=[3, 2]))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

>>> print(Profile.from_unique_bordas_and_multiplicities(
...     unique_bordas=[[2, 1, 0], [1, 2, 0]], multiplicities=[3, 2]))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

In the case where there is an integer number of voters for each ranking, you can also list the rankings or the Borda vectors with repetitions:

>>> print(Profile.from_rankings([
...     [0, 1, 2],
...     [0, 1, 2],
...     [0, 1, 2],
...     [1, 0, 2],
...     [1, 0, 2],
... ]))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

>>> print(Profile.from_bordas([
...     [2, 1, 0],
...     [2, 1, 0],
...     [2, 1, 0],
...     [1, 2, 0],
...     [1, 2, 0],
... ]))
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)

When you have a profile, you can access all these basic ways of representing it:

>>> profile = Profile.from_d_ranking_multiplicity({(0, 1, 2): 3, (1, 0, 2): 2})
>>> profile.d_borda_multiplicity
{(np.int64(2), np.int64(1), np.int64(0)): 3, (np.int64(1), np.int64(2), np.int64(0)): 2}
>>> profile.unique_rankings
array([[0, 1, 2],
       [1, 0, 2]])
>>> profile.unique_bordas  # DOCTEST: +ELLIPSIS
array([[2, 1, 0],
       [1, 2, 0]])
>>> profile.multiplicities
array([3, 2])

Features:

>>> profile
Profile(d_ranking_multiplicity={(np.int64(0), np.int64(1), np.int64(2)): np.int64(3), (np.int64(1), np.int64(0), np.int64(2)): np.int64(2)})
>>> print(profile)
Profile((0, 1, 2): 3,
        (1, 0, 2): 2)
>>> profile.n
5
>>> profile.m
3
>>> profile.weighted_majority_matrix
array([[0, 3, 5],
       [2, 0, 5],
       [0, 0, 0]])
>>> profile.majority_matrix
array([[0., 1., 1.],
       [0., 0., 1.],
       [0., 0., 0.]])
>>> profile.is_condorcet_winner
array([ True, False, False])
>>> profile.condorcet_winners
[np.int64(0)]
>>> profile.condorcet_winner
np.int64(0)
>>> profile.nb_condorcet_winners
1
>>> profile.exists_condorcet_winner
np.True_
>>> profile.is_weak_condorcet_winner
array([ True, False, False])
>>> profile.weak_condorcet_winners
[np.int64(0)]
>>> profile.nb_weak_condorcet_winners
1
>>> profile.exists_condorcet_order
True

Majority matrix with a tie:

>>> profile = Profile.from_d_ranking_multiplicity({(0, 1, 2): 2, (1, 0, 2): 2})
>>> profile.weighted_majority_matrix
array([[0, 2, 4],
       [2, 0, 4],
       [0, 0, 0]])
>>> profile.majority_matrix
array([[0. , 0.5, 1. ],
       [0.5, 0. , 1. ],
       [0. , 0. , 0. ]])
>>> profile.is_condorcet_winner
array([False, False, False])
>>> profile.condorcet_winners
[]
>>> profile.condorcet_winner
-1
>>> profile.nb_condorcet_winners
0
>>> profile.exists_condorcet_winner
np.False_
>>> profile.is_weak_condorcet_winner
array([ True,  True, False])
>>> profile.weak_condorcet_winners
[np.int64(0), np.int64(1)]
>>> profile.nb_weak_condorcet_winners
2
>>> profile.exists_condorcet_order
False
property condorcet_winner#

Condorcet winner. If there is no Condorcet winner, then -1 by convention.

Type:

int

property condorcet_winners#

Condorcet winners. This is a list of size 0 or 1.

Type:

List

property d_borda_multiplicity#

ranking in Borda format as a tuple. Value: multiplicity (number of voters).

Type:

dict

Type:

Key

property d_ranking_multiplicity#

ranking as a tuple. Value: multiplicity (number of voters).

Type:

dict

Type:

Key

property exists_condorcet_order#

True if the majority relation is transitive.

Type:

bool

property exists_condorcet_winner#

True if there exists a Condorcet winner.

Type:

bool

classmethod from_bordas(bordas)[source]#

New profile.

Parameters:

bordas (List of List) – List of rankings in Borda format, with possible repetitions.

classmethod from_d_borda_multiplicity(d_borda_multiplicity)[source]#

New profile.

Parameters:

d_borda_multiplicity (dict) – Key: ranking in Borda format as a tuple. Value: multiplicity (number of voters).

classmethod from_d_ranking_multiplicity(d_ranking_multiplicity)[source]#

New profile.

Parameters:

d_ranking_multiplicity (dict) – Key: ranking as a tuple. Value: multiplicity (number of voters).

classmethod from_rankings(rankings)[source]#

New profile.

Parameters:

rankings (List of List) – List of rankings with possible repetitions.

classmethod from_unique_bordas_and_multiplicities(unique_bordas, multiplicities)[source]#

New profile.

Parameters:

  • unique_bordas (List of List) – List of unique rankings in Borda format.

  • multiplicities (List) – Multiplicity (number of voters) corresponding to each unique ranking.

classmethod from_unique_rankings_and_multiplicities(unique_rankings, multiplicities)[source]#

New profile.

Parameters:

  • unique_rankings (List of List) – List of unique rankings.

  • multiplicities (List) – Multiplicity (number of voters) corresponding to each unique ranking.

property is_condorcet_winner#

For each candidate c, the corresponding coefficient is True if c is the Condorcet winner.

Type:

ndarray

property is_weak_condorcet_winner#

For each candidate c, the corresponding coefficient is True if c is a weak Condorcet winner.

Type:

ndarray

property m#

Number of candidates.

Type:

int

property majority_matrix#

Majority matrix. Coefficient (c, d) is 1.0 if more voters prefer candidate c to d than the opposite, 0.5 in case of tie, and 0.0 in case of defeat. By convention, diagonal coefficients are set to 0.

Type:

ndarray

property multiplicities#

Multiplicity (number of voters) corresponding to each ranking in unique_rankings.

Type:

ndarray

property n#

Number of voters.

Type:

int

property nb_condorcet_winners#

Number of Condorcet winners. May be 0 or 1.

Type:

int

property nb_weak_condorcet_winners#

Number of weak Condorcet winners.

Type:

int

property unique_bordas#

List of unique rankings in Borda format, in the same order as unique_rankings.

Type:

ndarray

property unique_rankings#

List of unique rankings.

Type:

ndarray

property unique_rankings_and_multiplicities#

List of unique rankings and the corresponding vector of multiplicities.

Type:

Tuple

property weak_condorcet_winners#

Weak Condorcet winners.

Type:

List

property weighted_majority_matrix#

Weighted majority matrix. Coefficient (c, d) is the number of voters who prefer candidate c to candidate d. By convention, diagonal coefficients are set to 0.

Type:

ndarray