Tournament Graph¶

Tournament graph diagnostics.

Build the directed tournament graph from pairwise outcomes and analyse its strongly connected component (SCC) structure. Non-trivial SCCs (size > 1) indicate clusters of models that cannot be linearly ordered — i.e. pockets of non-transitivity.

class winference.tournament.TournamentGraph(models)[source]¶

Bases: object

Directed tournament graph built from pairwise comparison data.

Parameters:: models (list[str]) – Unique model identifiers.

Examples

>>> tg = TournamentGraph(["A", "B", "C"])
>>> tg.add_result("A", "B", win=True)
>>> tg.add_result("B", "C", win=True)
>>> tg.add_result("C", "A", win=True)
>>> tg.scc_sizes()
[3]

add_result(model_a, model_b, win)[source]¶

Record a single comparison outcome (model_a wins if win=True).

Parameters:

model_a (str)
model_b (str)
win (bool)

Return type:

None

add_results_df(df, col_a='model_a', col_b='model_b', col_win='a_wins')[source]¶

Bulk-load from a DataFrame with columns for model_a, model_b, a_wins (bool).

Parameters:

df (DataFrame)
col_a (str, default: 'model_a')
col_b (str, default: 'model_b')
col_win (str, default: 'a_wins')

Return type:

None

win_rate_matrix()[source]¶

Return the NxN matrix W where W[i,j] = P(i beats j).

Return type:: ndarray[tuple[Any, ...], dtype[double]]

strongly_connected_components(threshold=0.5)[source]¶

Return SCCs via Tarjan’s algorithm.

Each SCC is a list of model names. SCCs of size > 1 represent non-transitive clusters.

Parameters:: threshold (float, default: 0.5)
Return type:: list[list[str]]

scc_sizes(threshold=0.5)[source]¶

Sorted list of SCC sizes (descending).

Parameters:: threshold (float, default: 0.5)
Return type:: list[int]

nontransitivity_index(threshold=0.5)[source]¶

Fraction of models inside non-trivial SCCs (size > 1).

0.0 = perfectly transitive, 1.0 = all models in one big cycle.

Parameters:: threshold (float, default: 0.5)
Return type:: float

count_cyclic_triples()[source]¶

Count cyclic vs total triples.

Return type:: tuple[int, int]
Returns:: Tuple of (n_cyclic, n_total). Under a transitive model n_cyclic = 0.

summary(threshold=0.5)[source]¶

Quick diagnostic summary.

Parameters:: threshold (float, default: 0.5)
Return type:: dict[str, int | float]