.. index:: single: ranking_dataset_common
.. _ranking_dataset_common/0:

.. rst-class:: right

**category**

``ranking_dataset_common``
==========================

Shared predicates for collecting, analyzing, and validating ranking datasets.

| **Availability:** 
|    ``logtalk_load(ranking_protocols(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-04-18

| **Compilation flags:**
|    ``static``


| **Uses:**
|    :ref:`avltree <avltree/0>`
|    :ref:`list <list/0>`
|    :ref:`numberlist <numberlist/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: pairwise_dataset_declared_items/2
.. _ranking_dataset_common/0::pairwise_dataset_declared_items/2:

``pairwise_dataset_declared_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the pairwise dataset declared items preserving declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_declared_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_declared_items(+object_identifier,-list)`` - ``one``


------------

.. index:: pairwise_dataset_items/2
.. _ranking_dataset_common/0::pairwise_dataset_items/2:

``pairwise_dataset_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique pairwise dataset items preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_items(+object_identifier,-list)`` - ``one``


------------

.. index:: pairwise_dataset_preferences/2
.. _ranking_dataset_common/0::pairwise_dataset_preferences/2:

``pairwise_dataset_preferences/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the pairwise dataset preferences as ``p(Winner,Loser,Weight)`` terms.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_preferences(Dataset,Preferences)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_preferences(+object_identifier,-list)`` - ``one``


------------

.. index:: pairwise_dataset_connected_components/2
.. _ranking_dataset_common/0::pairwise_dataset_connected_components/2:

``pairwise_dataset_connected_components/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the connected components induced by the pairwise preference graph.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_connected_components(Dataset,Components)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_connected_components(+object_identifier,-list(list))`` - ``one``


------------

.. index:: pairwise_dataset_summary/2
.. _ranking_dataset_common/0::pairwise_dataset_summary/2:

``pairwise_dataset_summary/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a summary of a pairwise dataset, including item, preference, component, and isolated-item counts.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_summary(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_summary(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: pairwise_dataset_win_totals/2
.. _ranking_dataset_common/0::pairwise_dataset_win_totals/2:

``pairwise_dataset_win_totals/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns per-item total win weights for a pairwise dataset.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_win_totals(Dataset,Totals)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_win_totals(+object_identifier,-list(pair))`` - ``one``


------------

.. index:: pairwise_dataset_matchups/2
.. _ranking_dataset_common/0::pairwise_dataset_matchups/2:

``pairwise_dataset_matchups/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns aggregated pairwise matchups as ``matchup(Item1,Item2,Item1Wins,Item2Wins)`` terms preserving item declaration order inside each pair.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_dataset_matchups(Dataset,Matchups)``
| **Mode and number of proofs:**
|    ``pairwise_dataset_matchups(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: pairwise_measurement_dataset_declared_items/2
.. _ranking_dataset_common/0::pairwise_measurement_dataset_declared_items/2:

``pairwise_measurement_dataset_declared_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the pairwise measurement dataset declared items preserving declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_measurement_dataset_declared_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``pairwise_measurement_dataset_declared_items(+object_identifier,-list)`` - ``one``


------------

.. index:: pairwise_measurement_dataset_items/2
.. _ranking_dataset_common/0::pairwise_measurement_dataset_items/2:

``pairwise_measurement_dataset_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique pairwise measurement dataset items preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_measurement_dataset_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``pairwise_measurement_dataset_items(+object_identifier,-list)`` - ``one``


------------

.. index:: pairwise_measurement_dataset_measurements/2
.. _ranking_dataset_common/0::pairwise_measurement_dataset_measurements/2:

``pairwise_measurement_dataset_measurements/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the pairwise measurement dataset observations as ``m(Item1,Item2,Value,Weight)`` terms preserving enumeration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_measurement_dataset_measurements(Dataset,Measurements)``
| **Mode and number of proofs:**
|    ``pairwise_measurement_dataset_measurements(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: pairwise_measurement_dataset_connected_components/2
.. _ranking_dataset_common/0::pairwise_measurement_dataset_connected_components/2:

``pairwise_measurement_dataset_connected_components/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the connected components induced by the pairwise measurement support graph.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_measurement_dataset_connected_components(Dataset,Components)``
| **Mode and number of proofs:**
|    ``pairwise_measurement_dataset_connected_components(+object_identifier,-list(list))`` - ``one``


------------

.. index:: pairwise_measurement_dataset_summary/2
.. _ranking_dataset_common/0::pairwise_measurement_dataset_summary/2:

``pairwise_measurement_dataset_summary/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a summary of a pairwise measurement dataset, including item, measurement, component, and isolated-item counts.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairwise_measurement_dataset_summary(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``pairwise_measurement_dataset_summary(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: temporal_pairwise_dataset_declared_items/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_declared_items/2:

``temporal_pairwise_dataset_declared_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the temporal pairwise dataset declared items preserving declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_declared_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_declared_items(+object_identifier,-list)`` - ``one``


------------

.. index:: temporal_pairwise_dataset_items/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_items/2:

``temporal_pairwise_dataset_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique temporal pairwise dataset items preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_items(+object_identifier,-list)`` - ``one``


------------

.. index:: temporal_pairwise_dataset_periods/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_periods/2:

``temporal_pairwise_dataset_periods/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique temporal pairwise dataset periods preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_periods(Dataset,Periods)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_periods(+object_identifier,-list)`` - ``one``


------------

.. index:: temporal_pairwise_dataset_games/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_games/2:

``temporal_pairwise_dataset_games/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the temporal pairwise dataset games as ``game(Period,Item1,Item2,Score)`` terms preserving enumeration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_games(Dataset,Games)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_games(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: temporal_pairwise_dataset_games/3
.. _ranking_dataset_common/0::temporal_pairwise_dataset_games/3:

``temporal_pairwise_dataset_games/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the temporal pairwise dataset games for a single period as ``game(Item1,Item2,Score)`` terms preserving enumeration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_games(Dataset,Period,Games)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_games(+object_identifier,+term,-list(compound))`` - ``one``


------------

.. index:: temporal_pairwise_dataset_connected_components/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_connected_components/2:

``temporal_pairwise_dataset_connected_components/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the connected components induced by the temporal pairwise game graph.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_connected_components(Dataset,Components)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_connected_components(+object_identifier,-list(list))`` - ``one``


------------

.. index:: temporal_pairwise_dataset_summary/2
.. _ranking_dataset_common/0::temporal_pairwise_dataset_summary/2:

``temporal_pairwise_dataset_summary/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a summary of a temporal pairwise dataset, including item, period, game, component, and isolated-item counts.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``temporal_pairwise_dataset_summary(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``temporal_pairwise_dataset_summary(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: grouped_dataset_groups/2
.. _ranking_dataset_common/0::grouped_dataset_groups/2:

``grouped_dataset_groups/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique grouped-dataset groups preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_groups(Dataset,Groups)``
| **Mode and number of proofs:**
|    ``grouped_dataset_groups(+object_identifier,-list)`` - ``one``


------------

.. index:: grouped_dataset_items/2
.. _ranking_dataset_common/0::grouped_dataset_items/2:

``grouped_dataset_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique items declared across all groups in a grouped dataset preserving their first declaration order.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_items(Dataset,Items)``
| **Mode and number of proofs:**
|    ``grouped_dataset_items(+object_identifier,-list)`` - ``one``


------------

.. index:: grouped_dataset_items/3
.. _ranking_dataset_common/0::grouped_dataset_items/3:

``grouped_dataset_items/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the unique items declared for a grouped-dataset group.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_items(Dataset,Group,Items)``
| **Mode and number of proofs:**
|    ``grouped_dataset_items(+object_identifier,+term,-list)`` - ``one``


------------

.. index:: grouped_dataset_summary/2
.. _ranking_dataset_common/0::grouped_dataset_summary/2:

``grouped_dataset_summary/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a summary of a grouped dataset, including group, item, and relevance-judgment counts.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_summary(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``grouped_dataset_summary(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: validate_pairwise_dataset/1
.. _ranking_dataset_common/0::validate_pairwise_dataset/1:

``validate_pairwise_dataset/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a pairwise ranking dataset and throws an error if the dataset is malformed or disconnected.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_pairwise_dataset(Dataset)``
| **Mode and number of proofs:**
|    ``validate_pairwise_dataset(+object_identifier)`` - ``one``


------------

.. index:: validate_pairwise_dataset/2
.. _ranking_dataset_common/0::validate_pairwise_dataset/2:

``validate_pairwise_dataset/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a pairwise ranking dataset and returns its dataset summary when validation succeeds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_pairwise_dataset(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``validate_pairwise_dataset(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: validate_pairwise_measurement_dataset/1
.. _ranking_dataset_common/0::validate_pairwise_measurement_dataset/1:

``validate_pairwise_measurement_dataset/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a pairwise measurement dataset and throws an error if the dataset is malformed or disconnected.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_pairwise_measurement_dataset(Dataset)``
| **Mode and number of proofs:**
|    ``validate_pairwise_measurement_dataset(+object_identifier)`` - ``one``


------------

.. index:: validate_pairwise_measurement_dataset/2
.. _ranking_dataset_common/0::validate_pairwise_measurement_dataset/2:

``validate_pairwise_measurement_dataset/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a pairwise measurement dataset and returns its dataset summary when validation succeeds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_pairwise_measurement_dataset(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``validate_pairwise_measurement_dataset(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: validate_grouped_dataset/1
.. _ranking_dataset_common/0::validate_grouped_dataset/1:

``validate_grouped_dataset/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a grouped ranking dataset and throws an error if the dataset is malformed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_grouped_dataset(Dataset)``
| **Mode and number of proofs:**
|    ``validate_grouped_dataset(+object_identifier)`` - ``one``


------------

.. index:: validate_temporal_pairwise_dataset/1
.. _ranking_dataset_common/0::validate_temporal_pairwise_dataset/1:

``validate_temporal_pairwise_dataset/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a temporal pairwise ranking dataset and throws an error if the dataset is malformed or disconnected.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_temporal_pairwise_dataset(Dataset)``
| **Mode and number of proofs:**
|    ``validate_temporal_pairwise_dataset(+object_identifier)`` - ``one``


------------

.. index:: validate_temporal_pairwise_dataset/2
.. _ranking_dataset_common/0::validate_temporal_pairwise_dataset/2:

``validate_temporal_pairwise_dataset/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a temporal pairwise ranking dataset and returns its dataset summary when validation succeeds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_temporal_pairwise_dataset(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``validate_temporal_pairwise_dataset(+object_identifier,-list(compound))`` - ``one``


------------

.. index:: validate_grouped_dataset/2
.. _ranking_dataset_common/0::validate_grouped_dataset/2:

``validate_grouped_dataset/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates a grouped ranking dataset and returns its dataset summary when validation succeeds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate_grouped_dataset(Dataset,Summary)``
| **Mode and number of proofs:**
|    ``validate_grouped_dataset(+object_identifier,-list(compound))`` - ``one``


------------

Protected predicates
--------------------

.. index:: grouped_dataset_item_relevances/4
.. _ranking_dataset_common/0::grouped_dataset_item_relevances/4:

``grouped_dataset_item_relevances/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects the declared items for a grouped-dataset group paired with their relevance values under the given missing-relevance policy.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_item_relevances(Dataset,Group,MissingRelevance,ItemRelevances)``
| **Mode and number of proofs:**
|    ``grouped_dataset_item_relevances(+object_identifier,+term,+atom,-list(pair))`` - ``one``


------------

.. index:: grouped_dataset_relevance_frequencies/2
.. _ranking_dataset_common/0::grouped_dataset_relevance_frequencies/2:

``grouped_dataset_relevance_frequencies/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggregates grouped item relevances into a relevance-frequency dictionary.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_relevance_frequencies(ItemRelevances,FrequencyDictionary)``
| **Mode and number of proofs:**
|    ``grouped_dataset_relevance_frequencies(+list(pair),-compound)`` - ``one``


------------

.. index:: grouped_dataset_item_relevance_scores/3
.. _ranking_dataset_common/0::grouped_dataset_item_relevance_scores/3:

``grouped_dataset_item_relevance_scores/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Maps grouped item relevances to per-item score deltas using a relevance-points dictionary.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_item_relevance_scores(ItemRelevances,PointsDictionary,ItemScores)``
| **Mode and number of proofs:**
|    ``grouped_dataset_item_relevance_scores(+list(pair),+compound,-list(pair))`` - ``one``


------------

.. index:: grouped_dataset_tie_blocks/4
.. _ranking_dataset_common/0::grouped_dataset_tie_blocks/4:

``grouped_dataset_tie_blocks/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collects grouped-dataset item relevances into descending relevance tie blocks represented as ``tie_block(Relevance, Items)`` terms, preserving the declaration order of items inside each block.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``grouped_dataset_tie_blocks(Dataset,Group,MissingRelevance,TieBlocks)``
| **Mode and number of proofs:**
|    ``grouped_dataset_tie_blocks(+object_identifier,+term,+atom,-list(compound))`` - ``one``


------------

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

