ncaa_eval.evaluation.providers module

Probability provider protocols and implementations.

Provides the ProbabilityProvider protocol and concrete implementations for pairwise win probability computation:

• MatrixProvider — wraps a pre-computed probability matrix.

• EloProvider — wraps a stateful model’s predict_matchup method.

• EnsembleProvider — wraps a StackedEnsemble as a provider.

• build_probability_matrix() — builds an n×n pairwise matrix.

class ncaa_eval.evaluation.providers.EloProvider(model: Any)

Bases: object

Wraps a StatefulModel as a ProbabilityProvider.

Uses the model’s predict_matchup method for probability computation.

Parameters:

model – Any StatefulModel instance with predict_matchup.

batch_matchup_probabilities(team_a_ids: Sequence[int], team_b_ids: Sequence[int], context: MatchupContext) → ndarray[tuple[Any, ...], dtype[float64]]

Return batch probabilities by looping predict_matchup.

Iterates team pairs, calling predict_matchup per matchup, and collects results into a list.

Elo is O(1) per pair so looping is acceptable.

matchup_probability(team_a_id: int, team_b_id: int, context: MatchupContext) → float

Return P(team_a beats team_b) via the model’s predict_matchup.

Delegates to the model’s predict_matchup method, which retrieves both teams’ current ratings and applies the Elo logistic expected-score formula.

class ncaa_eval.evaluation.providers.EnsembleProvider(ensemble: StackedEnsemble, data_dir: Path, season: int)

Bases: object

Wraps a StackedEnsemble as a ProbabilityProvider.

Calls ensemble.predict_bracket(data_dir, season) once on first use and caches the result as a MatrixProvider for subsequent lookups. This allows a StackedEnsemble to be passed to build_probability_matrix() and the Monte Carlo bracket simulator identically to single-model mode.

Parameters:

• ensemble – A trained StackedEnsemble instance.

• data_dir – Path to the local Parquet data store.

• season – Target season year.

batch_matchup_probabilities(team_a_ids: Sequence[int], team_b_ids: Sequence[int], context: MatchupContext) → ndarray[tuple[Any, ...], dtype[float64]]

Return batch probabilities from the cached ensemble matrix.

Triggers ensemble bracket prediction on first call; subsequent calls use the cached matrix.

matchup_probability(team_a_id: int, team_b_id: int, context: MatchupContext) → float

Return P(team_a beats team_b) from the ensemble probability matrix.

Triggers ensemble bracket prediction on first call; subsequent calls use the cached matrix.

class ncaa_eval.evaluation.providers.MatrixProvider(prob_matrix: ndarray[tuple[Any, ...], dtype[float64]], team_ids: Sequence[int])

Bases: object

Wraps a pre-computed probability matrix as a ProbabilityProvider.

Parameters:

• prob_matrix – n×n pairwise probability matrix.

• team_ids – Sequence of team IDs matching matrix indices.

batch_matchup_probabilities(team_a_ids: Sequence[int], team_b_ids: Sequence[int], context: MatchupContext) → ndarray[tuple[Any, ...], dtype[float64]]

Return batch probabilities from the stored matrix.

Extracts row/column indices from the team pairs, vectorizes lookups into the probability matrix, and returns a list of win probabilities.

matchup_probability(team_a_id: int, team_b_id: int, context: MatchupContext) → float

Return P(team_a beats team_b) from the stored matrix.

Indexes into the pre-built probability matrix using the team-to-index mapping, returning P(team_i beats team_j) directly from the stored array.

class ncaa_eval.evaluation.providers.ProbabilityProvider(*args, **kwargs)

Bases: Protocol

Protocol for pairwise win probability computation.

All implementations must satisfy the complementarity contract: P(A beats B) + P(B beats A) = 1 for every (A, B) pair.

batch_matchup_probabilities(team_a_ids: Sequence[int], team_b_ids: Sequence[int], context: MatchupContext) → ndarray[tuple[Any, ...], dtype[float64]]

Return P(a_i beats b_i) for all pairs.

Parameters:

• team_a_ids – Sequence of first-team IDs.

• team_b_ids – Sequence of second-team IDs (same length).

• context – Matchup context.

Returns:

1-D float64 array of shape (len(team_a_ids),).

matchup_probability(team_a_id: int, team_b_id: int, context: MatchupContext) → float

Return P(team_a beats team_b).

Parameters:

• team_a_id – First team’s canonical ID.

• team_b_id – Second team’s canonical ID.

• context – Matchup context (season, day_num, neutral).

Returns:

Probability in [0, 1].

ncaa_eval.evaluation.providers.build_probability_matrix(provider: ProbabilityProvider, team_ids: Sequence[int], context: MatchupContext) → ndarray[tuple[Any, ...], dtype[float64]]

Build n×n pairwise win probability matrix.

Uses upper-triangle batch call, then fills P[j,i] = 1 - P[i,j] via the complementarity contract.

Parameters:

• provider – Probability provider implementing the protocol.

• team_ids – Team IDs in bracket order.

• context – Matchup context.

Returns:

Float64 array of shape (n, n). Diagonal is zero.