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.

Examples

>>> from winference import TournamentGraph
>>> 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]

Parameters:: models (list[str])

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 model_a, model_b, a_wins (bool) columns.

Parameters:

df (DataFrame) – Frame of comparison outcomes, one row per comparison.
col_a (str) – Column holding the first model name.
col_b (str) – Column holding the second model name.
col_win (str) – Boolean column that is True when col_a won.

Return type:

None

win_rate_matrix()[source]¶

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

Return type:: NDArray[float64]

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)
Return type:: list[list[str]]

scc_sizes(threshold=0.5)[source]¶

Sorted list of SCC sizes (descending).

Parameters:: threshold (float)
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)
Return type:: float

count_cyclic_triples()[source]¶

Count cyclic vs total triples.

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

summary(threshold=0.5)[source]¶

Quick diagnostic summary.

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