MatrixRankedPairs

class whalrus.MatrixRankedPairs(*args, converter: whalrus.converters_ballot.converter_ballot.ConverterBallot = None, matrix_weighted_majority: whalrus.matrices.matrix.Matrix = None, tie_break: whalrus.priorities.priority.Priority = Priority.UNAMBIGUOUS, **kwargs)[source]

The ranked pairs matrix.

Parameters

Examples

First, we compute a matrix W with the algorithm given in the parameter matrix_weighted_majority. The ranked pair matrix represents a graph whose vertices are the candidates. In order to build it, we consider all duels between two distinct candidates (c, d), by decreasing order of the value W(c, d). We add an edge (c, d) in the ranked pairs matrix, except if it creates a cycle in the graph, and we consider the transitive closure.

>>> m = MatrixRankedPairs(['a > b > c', 'b > c > a', 'c > a > b'], weights=[4, 3, 2])
>>> m.edges_order_
[('b', 'c'), ('a', 'b'), ('c', 'a')]
>>> m.as_array_
array([[0, 1, 1],
       [0, 0, 1],
       [0, 0, 0]], dtype=object)

In the example example above, the edge (b, c) is added. Then it is the edge (a, b) which, by transitive closure, also adds the edge (a, c). Finally the edge (c, a) (representing the victory of c over a in the weighted majority matrix) should be added, but it would introduce a cycle in the graph, so it is ignored.

If two duels have the same score, the tie-break is used. For example, with Priority.ASCENDING, we add a victory (a, …) before a victory (b, …); and we add a victory (a, c) before a victory (a, b) (because b is favored over c). A very simple but illustrative example:

>>> MatrixRankedPairs(['a > b > c'], tie_break=Priority.ASCENDING).edges_order_
[('a', 'c'), ('a', 'b'), ('b', 'c')]
property as_array_of_floats_

The matrix, as a numpy array. It is the same as as_array_, but converted to floats.

Type

Array

property edges_order_

The order in which edges should be added (if possible). It is a list of pairs of candidates. E.g. [('b', 'c'), ('c', 'a'), ('a', 'b')], where (‘b’, ‘c’) is the first edge to add.

Type

list

property matrix_weighted_majority_

The weighted majority matrix (upon which the computation of the Ranked Pairs matrix is based), once computed with the given profile).

Type

Matrix