ncaa_eval.evaluation.perturbation module

Game-theory slider perturbation for bracket probability matrices.

Applies two independent transformations to a pairwise probability matrix:

  1. Temperature (Upset Aggression): Power scaling that compresses probabilities toward 0.5 (more upsets, T > 1) or sharpens them away from 0.5 (more chalk, T < 1).

  2. Seed Blend (Seed-Weight): Linear interpolation between the (possibly temperature-adjusted) model output and historical first-round seed priors.

Both transformations preserve complementarity: P[i,j] + P[j,i] = 1 for all (i, j) pairs.

ncaa_eval.evaluation.perturbation.build_seed_prior_matrix(seed_map: dict[int, int], team_ids: Sequence[int]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Build an (n × n) seed prior probability matrix.

S[i, j] = P(team_i beats team_j) based on historical seed win rates keyed by |seed_i − seed_j|.

Parameters:

  • seed_map – Maps team_id → seed_number (1–16).

  • team_ids – Ordered team IDs matching matrix indices.

Returns:

Float64 matrix of shape (n, n) with diagonal zeros and S[i,j] + S[j,i] = 1.

ncaa_eval.evaluation.perturbation.perturb_probability_matrix(P: ndarray[tuple[Any, ...], dtype[float64]], seed_map: dict[int, int], team_ids: Sequence[int], temperature: float = 1.0, seed_weight: float = 0.0) → ndarray[tuple[Any, ...], dtype[float64]][source]

Apply game-theory slider perturbation to a pairwise probability matrix.

Applies two independent transformations in sequence:

  1. Temperature scaling: p' = p^(1/T) / (p^(1/T) + (1-p)^(1/T))

  2. Seed blend: p'' = (1-w)*p' + w*p_seed_prior

Parameters:

  • P – Square probability matrix where P[i,j] is the probability that team i beats team j. Must satisfy P[i,j] + P[j,i] = 1 and P[i,i] = 0.

  • seed_map – Maps team_id → seed_number (1–16).

  • team_ids – Ordered team IDs matching matrix indices.

  • temperature – Controls upset/chalk spectrum. T > 1 = more upsets, T < 1 = more chalk, T = 1 = neutral.

  • seed_weight – Controls model/seed blend. 0 = pure model, 1 = pure seed prior.

Returns:

Perturbed matrix of same shape satisfying complementarity.

Raises:

ValueError – If temperature ≤ 0 or seed_weight not in [0, 1].

ncaa_eval.evaluation.perturbation.power_transform(P: ndarray[tuple[Any, ...], dtype[float64]], temperature: float) → ndarray[tuple[Any, ...], dtype[float64]][source]

Apply power/temperature scaling to a probability matrix.

Computes p' = p^(1/T) / (p^(1/T) + (1-p)^(1/T)) element-wise.

Properties:

  • T=1.0: identity (p’ = p).

  • T>1: compresses probabilities toward 0.5 (more upsets).

  • T<1: sharpens probabilities away from 0.5 (more chalk).

  • Preserves p=0, p=1, p=0.5 as fixed points.

  • Preserves diagonal zeros.

  • Preserves complementarity: p'[i,j] + p'[j,i] = 1.

Parameters:

  • P – Square probability matrix with diagonal zeros.

  • temperature – Temperature T > 0.

Returns:

Transformed matrix with same shape and dtype.

Raises:

ValueError – If temperature is not positive.

ncaa_eval.evaluation.perturbation.slider_to_temperature(slider_value: int) → float[source]

Map an integer slider value to a temperature parameter.

Parameters:

slider_value – Integer in [-5, +5].

Returns:

T = 2^(slider_value / 3). T=1.0 at slider_value=0 (neutral).

Raises:

ValueError – If slider_value is outside [-5, +5].