.. 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 ` | :ref:`list ` | :ref:`numberlist ` | **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)