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:
avltree
list
numberlist
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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

### `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`

### `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`

### `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`

### `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)