MatrixWeightedMajority¶

class
whalrus.
MatrixWeightedMajority
(*args, converter: whalrus.converters_ballot.converter_ballot.ConverterBallot = None, higher_vs_lower: Optional[numbers.Number] = 1, lower_vs_higher: Optional[numbers.Number] = 0, indifference: Optional[numbers.Number] = Fraction(1, 2), ordered_vs_unordered: Optional[numbers.Number] = 1, unordered_vs_ordered: Optional[numbers.Number] = 0, unordered_vs_unordered: Optional[numbers.Number] = Fraction(1, 2), ordered_vs_absent: Optional[numbers.Number] = None, absent_vs_ordered: Optional[numbers.Number] = None, unordered_vs_absent: Optional[numbers.Number] = None, absent_vs_unordered: Optional[numbers.Number] = None, absent_vs_absent: Optional[numbers.Number] = None, diagonal_score: numbers.Number = 0, default_score: numbers.Number = 0, antisymmetric: bool = False, **kwargs)[source]¶ The weighted majority matrix.
Parameters:  args – Cf. parent class.
 converter (ConverterBallot) – Default:
ConverterBallotToOrder
.  higher_vs_lower (Number or None) – Number of points for candidate c when it is ordered higher than candidate d.
 lower_vs_higher (Number or None) – Number of points for candidate c when it is ordered lower than candidate d.
 indifference (Number or None) – Number of points for candidate c when it is ordered and tied with candidate d.
 ordered_vs_unordered (Number or None) – Number of points for candidate c when it is ordered and d is unordered.
 unordered_vs_ordered (Number or None) – Number of points for candidate c when it is unordered and d is ordered.
 unordered_vs_unordered (Number or None) – Number of points for candidate c when it is unordered and d is unordered.
 ordered_vs_absent (Number or None) – Number of points for candidate c when it is ordered and d is absent.
 absent_vs_ordered (Number or None) – Number of points for candidate c when it is absent and d is ordered.
 unordered_vs_absent (Number or None) – Number of points for candidate c when it is unordered and d is absent.
 absent_vs_unordered (Number or None) – Number of points for candidate c when it is absent and d is unordered.
 absent_vs_absent (Number or None) – Number of points for candidate c when it is absent and d is absent.
 diagonal_score (Number) – Value of the diagonal coefficients.
 default_score (Number) – Default score in the matrix in case of division by 0 (except for the diagonal coefficients).
 antisymmetric (bool) – If True, then an antisymmetric version of the matrix is computed (by subtracting the transposed matrix at the end of the computation).
 kwargs – Cf. parent class.
Examples
In the most general syntax, firstly, you define the matrix computation algorithm:
>>> matrix = MatrixWeightedMajority(diagonal_score=.5)
Secondly, you use it as a callable to load a particular election (profile, candidates):
>>> matrix(ballots=['a > b', 'b > a'], weights=[3, 1], voters=['v', 'w'], candidates={'a', 'b'}) # doctest:+ELLIPSIS <... object at ...>
Finally, you can access the computed variables:
>>> matrix.as_array_ array([[Fraction(1, 2), Fraction(3, 4)], [Fraction(1, 4), Fraction(1, 2)]], dtype=object)
Later, if you wish, you can load another profile with the same matrix computation algorithm, and so on.
Optionally, you can specify an election (profile and candidates) as soon as the
Matrix
object is initialized. This allows for “oneliners” such as:>>> MatrixWeightedMajority(ballots=['a > b', 'b > a'], weights=[3, 1], voters=['x', 'y'], ... candidates={'a', 'b'}, diagonal_score=.5).as_array_ array([[Fraction(1, 2), Fraction(3, 4)], [Fraction(1, 4), Fraction(1, 2)]], dtype=object)
Antisymmetric version:
>>> MatrixWeightedMajority(ballots=['a > b', 'b > a'], weights=[3, 1], voters=['x', 'y'], ... candidates={'a', 'b'}, antisymmetric=True).as_array_ array([[0, Fraction(1, 2)], [Fraction(1, 2), 0]], dtype=object)
An “unordered” candidate is a candidate that the voter has seen but not included in her ranking; i.e. it is in the attribute
BallotOrder.candidates_not_in_b
of the ballot. An “absent” candidate is a candidate that the voter has not even seen; i.e. it is inself.candidates_
, but not the attributeBallot.candidates
of the ballot. For all the “scoring” parameters (fromhigher_vs_lower
toabsent_vs_absent
), the value None can be used. In that case, the corresponding occurrences are not taken into account in the average (neither the numerator, not the denominator). Consider this example:>>> ballots = ['a > b', 'a ~ b']
With
indifference=Fraction(1, 2)
(default), the ratio of voters who prefer a to b is (1 + 1 / 2) / 2 = 3 / 4 (the indifferent voter gives 1 / 2 point and is counted in the denominator):>>> MatrixWeightedMajority(ballots).as_array_ array([[0, Fraction(3, 4)], [Fraction(1, 4), 0]], dtype=object)
With
indifference=0
, the ratio of voters who prefer a to b is 1 / 2 (the indifferent voter gives no point, but is counted in the denominator):>>> MatrixWeightedMajority(ballots, indifference=0).as_array_ array([[0, Fraction(1, 2)], [0, 0]], dtype=object)
With
indifference=None
, the ratio of voters who prefer a to b is 1 / 1 = 1 (the indifferent voter is not counted in the average at all):>>> MatrixWeightedMajority(ballots, indifference=None).as_array_ array([[0, 1], [0, 0]])

as_array_
¶ The matrix, as a numpy array. Each row and each column corresponds to a candidate (in the order of
candidates_as_list_
).Type: Array

as_array_of_floats_
¶ The matrix, as a numpy array. It is the same as
as_array_
, but converted to floats.Type: Array

candidates_as_list_
¶ The list of candidates. Candidates are sorted if possible.
Type: list

candidates_indexes_
¶ The candidates as a dictionary. To each candidate, it associates its index in
candidates_as_list_
.Type: NiceDict

gross_
¶ The “gross” matrix. Keys are pairs of candidates. Each coefficient is the weighted number of points (used as numerator in the average).
Examples
>>> from whalrus import MatrixWeightedMajority >>> MatrixWeightedMajority(ballots=['a > b', 'a ~ b'], weights=[2, 1]).gross_ {('a', 'a'): 0, ('a', 'b'): Fraction(5, 2), ('b', 'a'): Fraction(1, 2), ('b', 'b'): 0}
Type: NiceDict

weights_
¶ The matrix of weights. Keys are pairs of candidates. Each coefficient is the total weight (used as denominator in the average).
Examples
In most usual cases, all nondiagonal coefficients are equal, and are equal to the total weight of all voters:
>>> from whalrus import MatrixWeightedMajority >>> MatrixWeightedMajority(ballots=['a > b', 'a ~ b'], weights=[2, 1]).weights_ {('a', 'a'): 0, ('a', 'b'): 3, ('b', 'a'): 3, ('b', 'b'): 0}
However, if some scoring parameters are None, some weights can be lower than the total weight of all voters:
>>> from whalrus import MatrixWeightedMajority >>> MatrixWeightedMajority(ballots=['a > b', 'a ~ b'], weights=[2, 1], ... indifference=None).weights_ {('a', 'a'): 0, ('a', 'b'): 2, ('b', 'a'): 2, ('b', 'b'): 0}
Type: NiceDict