factrix.metrics.directional_pair_accuracy ¶

Small-N cross-sectional pair-ordering accuracy.

For allocation-style panels with only a handful of assets, quantile buckets can be too coarse to answer the most basic ordering question: did the higher-scored asset outperform the lower-scored asset on the same date? This module reports a descriptive pooled pairwise ordering accuracy and deliberately does not attach a naive binomial p-value over same-date pairs.

factrix.metrics.directional_pair_accuracy.directional_pair_accuracy ¶

directional_pair_accuracy(data: DataFrame, forward_periods: int = 5, factor_col: str = 'factor', return_col: str = 'forward_return') -> MetricResult

Pairwise ordering accuracy for small allocation universes.

For each non-overlapping date, compare every pair of assets with pairwise-complete factor_col and return_col values. A pair is correct when the asset with the higher factor value also has the higher forward return. Factor ties and return ties are excluded from the accuracy denominator and counted in metadata.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Long panel with `date`, `asset_id`, `factor_col` and `return_col`.	required
`forward_periods`	`int`	Sampling stride for non-overlapping dates; match the forward-return horizon so overlapping windows do not dominate the per-date series.	`5`
`factor_col`	`str`	Ranking column.	`'factor'`
`return_col`	`str`	Forward-return column.	`'forward_return'`

Returns:

Type	Description
`MetricResult`	MetricResult with `value` equal to pooled correct comparable pairs
`MetricResult`	divided by pooled comparable pairs. The unweighted mean of per-date
`MetricResult`	accuracies is reported in metadata. `p_value` and `stat` are
`MetricResult`	`None`: same-date asset pairs share shocks and are not treated as
`MetricResult`	independent Bernoulli trials.

Use cases¶

Small-N rank-order diagnostic

directional_pair_accuracy asks whether the higher-scored asset outperformed the lower-scored asset on the same date. It is useful when the universe has roughly 5-20 names and quantile buckets or fixed-K spreads are too lumpy to describe the ordering signal cleanly.
Ties and nulls are explicit

Factor ties and return ties are excluded from the comparable-pair denominator and counted in metadata. Null factor/return rows are dropped before pair construction. Read metadata["n_pairs"], factor_tie_pairs, return_tie_pairs, and dropped_rows_null before treating the headline accuracy as stable.
Descriptive by design

The metric returns no p_value: same-date asset pairs share shocks, so a naive binomial test over all pairs would overstate precision. value is the pooled comparable-pair accuracy; metadata["mean_per_date_accuracy"] keeps the unweighted per-date read for unbalanced panels. Use it as a targeted allocation diagnostic alongside the first-pass IC / FM evidence.

Choosing a function¶

Goal	Function
Rank relation with formal inference on per-date IC series	`ic`
Fixed-count long-short spread in a small universe	`k_spread`
Sign prediction against realised direction	`directional_hit_rate`
Within-date pairwise ordering accuracy	`directional_pair_accuracy`

Worked example¶

Pairwise ordering on a small allocation panel

import factrix as fx
from factrix.metrics.directional_pair_accuracy import directional_pair_accuracy
from factrix.preprocess import compute_forward_return

raw = fx.datasets.make_cs_panel(n_assets=12, n_dates=160, seed=2024)
panel = compute_forward_return(raw, forward_periods=5)

out = directional_pair_accuracy(panel, forward_periods=5)
print(out.value, out.p_value, out.metadata["n_pairs"])
# 0.56  None  198   (approximate)

factrix.metrics.directional_pair_accuracy ¶