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.



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')]

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


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.


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