.. _library_ranked_pairs:

``ranked_pairs``
================

Ranked Pairs pairwise preference ranker. It builds the direct pairwise
victory graph from aggregated matchups, considers victories in
descending direct-victory strength order, and locks each victory unless
it would create a directed cycle in the accepted lock graph.

The library implements the ``ranker_protocol`` defined in the
``ranking_protocols`` library. It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
``pairwise_ranking_dataset_protocol`` protocol from the
``ranking_protocols`` library. See the ``test_datasets`` directory for
examples. The current implementation requires a well-formed connected
pairwise dataset so that all ranked items remain part of a single
comparison graph.

API documentation
-----------------

Open the
`../../apis/library_index.html#ranked_pairs <../../apis/library_index.html#ranked_pairs>`__
link in a web browser.

Loading
-------

To load this library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(ranked_pairs(loader)).

Testing
-------

To test this library predicates, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(ranked_pairs(tester)).

Features
--------

- **Pairwise Preference Learning**: Learns one deterministic score per
  item from aggregated pairwise outcomes.
- **Ranked Pairs Locking**: Processes direct victories in descending
  strength order and accepts each victory unless it would create a
  directed cycle in the current lock graph.
- **Configurable Direct Victory Semantics**: Supports both winning-votes
  and victory-margins victory-strength modes before locking.
- **Configurable Equal-Strength Tie Breaking**: Supports both standard
  term-order and dataset declaration-order resolution when direct
  victories have the same strength.
- **Locked-Pair Access**: Exposes the accepted lock graph in lock order
  using the ``locked_pairs/2`` predicate.
- **Deterministic Ranking**: Orders candidate items by the number of
  opponents reachable in the final locked relation with deterministic
  tie-breaking.
- **Strict Dataset Validation**: Rejects duplicate items, undeclared
  items, self-preferences, non-positive weights, and disconnected
  comparison graphs.
- **Training Diagnostics**: Learned rankers include dataset summary
  metadata, the effective victory-strength mode, and the accepted lock
  graph.
- **Ranker Export**: Learned rankers can be exported as self-contained
  terms.
- **Shared Condorcet Infrastructure**: Reuses the shared direct-victory
  preprocessing helpers from the ``ranking_protocols`` library.

Usage
-----

Learning a ranker
~~~~~~~~~~~~~~~~~

::

   % Learn from a pairwise ranking dataset object
   | ?- ranked_pairs::learn(my_dataset, Ranker).
   ...

   % Learn with custom direct-victory semantics
   | ?- ranked_pairs::learn(my_dataset, Ranker, [victory_strength(margins)]).
   ...

   % Learn with custom equal-strength tie breaking
   | ?- ranked_pairs::learn(my_dataset, Ranker, [tie_breaking(declaration_order)]).
   ...

Inspecting diagnostics
~~~~~~~~~~~~~~~~~~~~~~

::

   % Inspect the effective options and accepted locks
   | ?- ranked_pairs::learn(my_dataset, Ranker),
        ranked_pairs::diagnostics(Ranker, Diagnostics).
   Diagnostics = [...]
   ...

Ranking candidate items
~~~~~~~~~~~~~~~~~~~~~~~

::

   % Rank a candidate set from most preferred to least preferred
   | ?- ranked_pairs::learn(my_dataset, Ranker),
        ranked_pairs::rank(Ranker, [item_a, item_b, item_c], Ranking).
   Ranking = [...]
   ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset. Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.

Inspecting locked pairs
~~~~~~~~~~~~~~~~~~~~~~~

::

   % Inspect the accepted lock graph in lock order
   | ?- ranked_pairs::learn(my_dataset, Ranker),
        ranked_pairs::locked_pairs(Ranker, LockedPairs).
   LockedPairs = [...]
   ...

The ``locked_pairs/2`` predicate returns an ordered list of
``lock(Winner, Loser, Strength)`` terms representing the victories that
were accepted during the Ranked Pairs locking phase.

Exporting the ranker
~~~~~~~~~~~~~~~~~~~~

Learned rankers can be exported as a list of clauses or to a file for
later use.

::

   % Export as predicate clauses
   | ?- ranked_pairs::learn(my_dataset, Ranker),
        ranked_pairs::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
   Clauses = [my_ranker(ranked_pairs_ranker(...))]
   ...

   % Export to a file
   | ?- ranked_pairs::learn(my_dataset, Ranker),
        ranked_pairs::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
   ...

Diagnostics syntax
------------------

The ``diagnostics/2`` predicate returns a list of metadata terms with
the form:

::

   [
       model(ranked_pairs),
       options(Options),
       locked_pairs(LockedPairs),
       dataset_summary(DatasetSummary)
   ]

Where:

- ``model(ranked_pairs)`` identifies the learning algorithm that
  produced the ranker.
- ``options(Options)`` stores the effective learning options after
  merging the user options with the library defaults.
- ``locked_pairs(LockedPairs)`` stores the accepted lock graph in the
  order in which victories were locked.
- ``dataset_summary(DatasetSummary)`` stores a summary list describing
  the validated training dataset.

Use the ``ranking_protocols`` ``diagnostic/2`` and ``ranker_options/2``
helper predicates when you only need a single metadata term or the
effective options.

Options
-------

The following options can be passed to the ``learn/3`` predicate:

- ``victory_strength(winning_votes)``: Use the winning side's aggregated
  vote total as the direct victory strength.
- ``victory_strength(margins)``: Use the victory margin as the direct
  victory strength.
- ``tie_breaking(term_order)``: Break equal-strength direct-victory ties
  using the standard term order of the winner and loser item
  identifiers.
- ``tie_breaking(declaration_order)``: Break equal-strength
  direct-victory ties using the training item declaration order
  preserved by the pairwise dataset helpers.

The defaults are ``victory_strength(winning_votes)`` and
``tie_breaking(term_order)``.

Scoring semantics
-----------------

The learned ``scores/2`` values count how many opponents are reachable
from each item in the final locked relation. These scores are therefore
integers in the range from ``0`` to ``N-1``, where ``N`` is the number
of learned items.

This choice keeps the ``rank/3`` behavior aligned with the locked graph
that the algorithm actually accepts: a higher score means that the item
precedes more opponents after all accepted locks are closed
transitively.

The effective scores can therefore change when ``tie_breaking/1``
changes the order in which equal-strength victories are considered for
locking.

Ranker representation
---------------------

The learned ranker is represented by a compound term of the form:

::

   ranked_pairs_ranker(Items, Scores, Diagnostics)

Where:

- ``Items``: List of ranked items.
- ``Scores``: List of integer ``Item-Score`` pairs.
- ``Diagnostics``: List of metadata terms, including the effective
  options, the accepted locked pairs, and the dataset summary.

When exported using ``export_to_clauses/4`` or ``export_to_file/4``,
this ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.

See also
--------

For the strongest-path Condorcet-family alternative sharing the same
``victory_strength(...)`` option, see the ``schulze_ranker`` library.
