.. _library_ranking_protocols:

``ranking_protocols``
=====================

This library provides protocols used in the implementation of machine
learning ranking algorithms. Rankers are represented as objects
implementing the ``ranker_protocol`` protocol. Datasets are represented
as objects implementing the ``pairwise_ranking_dataset_protocol``,
``pairwise_measurement_dataset_protocol``,
``temporal_pairwise_ranking_dataset_protocol``, or the
``ranking_dataset_protocol`` protocol.

This library also provides reusable test datasets and smoke tests for
the shared ranking-family contracts.

Protocol requirements
---------------------

The dataset protocols defined by this library impose the following
semantic and validity expectations:

- ``pairwise_ranking_dataset_protocol`` datasets should declare each
  item once, use only declared items in preferences, assign positive
  weights to preferences between distinct items, and may still need
  stronger conditions such as a strongly connected directed win graph
  for algorithms like Bradley-Terry that require finite
  maximum-likelihood estimates.
- ``pairwise_measurement_dataset_protocol`` datasets should declare each
  item once, use only declared items in measurements, assign numeric
  measurement values, and assign positive weights to measurements
  between distinct items. Each
  ``measurement(Item1, Item2, Value, Weight)`` fact denotes a weighted
  signed scalar observation on the oriented edge ``Item1 -> Item2``,
  where positive values favor ``Item1``, negative values favor
  ``Item2``, and zero denotes a neutral observation.
- ``temporal_pairwise_ranking_dataset_protocol`` datasets should declare
  each item and period once, use only declared items and periods in
  games, keep game participants distinct, and restrict scores to the set
  ``{0.0, 0.5, 1.0}``. A fact ``game(Period, Item1, Item2, Score)``
  records the observed result for ``Item1`` against ``Item2``, with the
  score for ``Item2`` implicitly equal to ``1.0 - Score``.

Shared categories
-----------------

The library includes a small family of reusable categories intended to
be imported by ranking algorithm implementations:

- ``ranking_dataset_common`` — dataset collection, summaries, graph
  connectivity, connected-component analysis, and pairwise/grouped
  dataset correctness checks, including pairwise measurement helpers,
  temporal pairwise rating-period helpers, and grouped tie-block
  extraction helpers for algorithms that consume tied rankings directly.
- ``glicko2_common`` — shared internal Glicko-2 numeric helpers for
  scale conversions, per-period player updates, and volatility root
  solving used by both the batch and periodic Glicko-2 rankers.
- ``condorcet_victory_common`` — shared direct-victory preprocessing
  helpers for Condorcet-family rankers that derive dense directed
  victory strengths from aggregated pairwise matchups under the
  ``victory_strength(...)`` option semantics.
- ``ranker_common`` — representation-independent access to
  learned-ranker diagnostics plus reusable helpers for exporting learned
  rankers.
- ``grouped_strength_ranker_common`` — reusable positive-strength,
  strong-connectivity, and iterative-update helpers for grouped ranking
  models that estimate one latent strength parameter per item.

These categories are designed to keep ranking implementations compact
while keeping the shared protocol-facing behavior reusable.

Diagnostics
-----------

The ``ranker_common`` category provides shared accessor predicates such
as ``diagnostics/2``, ``diagnostic/2``, and ``ranker_options/2``,
together with the shared ``export_to_file/4`` export helper. These
predicates make it possible to inspect and export learned rankers
without depending on the exact term representation used by a particular
ranking algorithm implementation.

The detailed contents of the diagnostics data are ranking algorithm
implementation dependent. For example, one ranker may report convergence
status, iteration count, and dataset summaries, while another may report
a different set of metadata terms or only a subset of those details.
When using diagnostics in application code, rely on the shared access
predicates and the documentation of the specific ranking algorithm you
are using.

Export header format
--------------------

The shared ranker exporter in the ``ranker_common`` category writes a
header before the exported clauses in the following format:

::

   % exported ranker predicate: Functor/Arity
   % training dataset: Dataset
   % diagnostics: Diagnostics
   % Functor(Ranker)
   Functor(Ranker)

When exporting a serialized ranker term, using a noun such as
``ranker/1`` or ``model/1`` is recommended. The ``Ranker`` argument can
then be passed to the rank predicates.

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

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

Loading
-------

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

::

   | ?- logtalk_load(ranking_protocols(loader)).

Testing
-------

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

::

   | ?- logtalk_load(ranking_protocols(tester)).

Test datasets
-------------

Several sample datasets are included in the ``test_datasets`` directory:

- ``head_to_head.lgt`` — A compact pairwise-comparison dataset with four
  items and weighted preferences suitable for smoke testing
  deterministic ranking.

- ``search_results.lgt`` — A grouped ranking dataset with two query
  groups, three items per group, and non-negative integer relevance
  judgments.

- ``malformed_pairwise.lgt`` — A negative fixture where a preference
  mentions an undeclared item.

- ``malformed_duplicate_items.lgt`` — A negative pairwise fixture where
  an item is declared more than once.

- ``malformed_self_preference.lgt`` — A negative pairwise fixture where
  an item is preferred over itself.

- ``malformed_non_positive_weight.lgt`` — A negative pairwise fixture
  where a preference weight is not positive.

- ``disconnected_pairwise.lgt`` — A pairwise fixture with more than one
  connected component, useful for testing algorithms that require
  identifiable global scores.

- ``cyclic_pairwise.lgt`` — A connected pairwise fixture with a
  preference cycle, useful for smoke testing algorithms on
  non-transitive data.

- ``condorcet_divergence_pairwise.lgt`` — A compact connected pairwise
  fixture where the current ``schulze_ranker`` and ``ranked_pairs``
  implementations produce different rankings, useful for cross-method
  regression tests.

- ``malformed_grouped.lgt`` — A negative fixture where a grouped
  relevance value is not a non-negative integer.

- ``sparse_preferences.lgt`` — A sparse pairwise dataset with an
  isolated item, useful for testing dataset summaries and
  disconnected-graph detection.

- ``two_item_measurements.lgt`` — A compact pairwise measurement dataset
  with two items and one signed measurement, useful for smoke testing
  exact two-item least-squares fits.

- ``regular_measurements.lgt`` — A compact connected pairwise
  measurement dataset whose measurements are perfectly explained by a
  zero-sum score potential, useful for regression tests with zero
  residuals.

- ``cyclic_measurements.lgt`` — A compact connected pairwise measurement
  dataset with cyclic inconsistency, useful for smoke testing zero
  global scores with non-zero residuals.

- ``disconnected_measurements.lgt`` — A pairwise measurement fixture
  with more than one connected component, useful for testing
  identifiable-score checks.

- ``malformed_measurement_unknown_item.lgt`` — A negative measurement
  fixture where a measurement mentions an undeclared item.

- ``malformed_measurement_duplicate_items.lgt`` — A negative measurement
  fixture where an item is declared more than once.

- ``malformed_measurement_self.lgt`` — A negative measurement fixture
  where an item is measured against itself.

- ``malformed_measurement_non_numeric.lgt`` — A negative measurement
  fixture where a measurement value is not numeric.

- ``malformed_measurement_non_positive_weight.lgt`` — A negative
  measurement fixture where a measurement weight is not positive.

- ``temporal_two_period_chain.lgt`` — A compact temporal pairwise
  dataset with two rating periods and three players, useful for smoke
  testing periodic rating carryover.

- ``temporal_draws.lgt`` — A compact temporal pairwise dataset with a
  draw, useful for testing score handling in temporal game results.

- ``temporal_idle_periods.lgt`` — A temporal pairwise dataset with an
  empty period between two played periods, useful for testing inactivity
  handling.
