Gate

train.gate.GateVerdict

The gate’s decision over a candidate’s scores.

Usage

train.gate.GateVerdict(
    promote,
    reason,
    stats,
)

Attributes

promote: bool: Whether the candidate should replace the incumbent.
reason: str: Human-readable justification recorded alongside the decision.
stats: dict[str, float]: The named statistics the decision was derived from.

train.gate.GateResult

The corrected paired gate over a candidate and incumbent at matched budget.

Usage

Source

train.gate.GateResult(
    candidate,
    incumbent,
    coverage_wins,
    coverage_losses,
    coverage_sign_p,
    coverage_sig,
    budget_held,
    cell_auc,
    incumbent_auc,
    auc_not_regressed,
    harmful_favors_incumbent,
    promote
)

Attributes

candidate: str: The candidate’s name.
incumbent: str: The incumbent’s name.
coverage_wins: int: Warranted rows where only the candidate fires.
coverage_losses: int: Warranted rows where only the incumbent fires.
coverage_sign_p: float: Exact sign-test p-value over discordant coverage pairs.
coverage_sig: bool: Whether coverage significantly favors the candidate.
budget_held: bool: Whether candidate fires do not exceed incumbent fires.
cell_auc: float: The candidate’s sentinel AUC.
incumbent_auc: float: The incumbent’s sentinel AUC.
auc_not_regressed: bool: Whether candidate AUC is at least incumbent AUC.
harmful_favors_incumbent: bool | None: Whether harmful-fire judging favors the incumbent, or None while judging is pending.
promote: bool | None: The full verdict, or None while harmful-fire judging is pending.

train.gate.corrected_gate()

Evaluate the corrected paired gate over common rows at matched budget.

Usage

Source

train.gate.corrected_gate(
    candidate_fire_scores,
    incumbent_fire_scores,
    *,
    candidate,
    incumbent,
    incumbent_fire_threshold,
    labels,
    warranted,
    harmful_favors_incumbent=None
)

Every score input has an explicit higher-is-fire contract. Callers starting from a no-fire probability must orient it before calling this function. The incumbent fires strictly above incumbent_fire_threshold; the candidate is then matched conservatively to that fire count. warranted selects the caller-defined stratum in which discordant coverage pairs count.

Parameters

candidate_fire_scores: np.ndarray: Candidate scores where larger values mean fire.
incumbent_fire_scores: np.ndarray: Incumbent scores where larger values mean fire.
candidate: str: Candidate name recorded in the result.
incumbent: str: Incumbent name recorded in the result.
incumbent_fire_threshold: float: Strict lower bound for incumbent fires.
labels: np.ndarray: Binary labels used for both sentinel AUC calculations.
warranted: np.ndarray: Boolean mask selecting rows where coverage wins and losses count.
harmful_favors_incumbent: bool | None = None: Deferred harmful-fire judgment, or None while pending.

Returns

GateResult: Every gate component and the promotion verdict when harmful judging exists.

train.gate.sentinel_auc()

Return ROC-AUC for explicitly oriented higher-is-fire scores.

Usage

Source

train.gate.sentinel_auc(labels, fire_scores)

Parameters

labels: np.ndarray: Binary labels where true or 1 identifies rows that should fire.
fire_scores: np.ndarray: Scores where larger values mean a row is more likely to fire.

Returns

float: The ROC-AUC reported by scikit-learn.

train.gate.sign_test_p()

Return the exact two-sided sign-test p-value over discordant pairs.

Usage

Source

train.gate.sign_test_p(wins, losses)

Parameters

wins: int: Discordant pairs favoring the candidate.
losses: int: Discordant pairs favoring the incumbent.

Returns

float: The exact two-sided p-value, or 1.0 when there are no discordant pairs.

Raises

ValueError: If either count is negative.

train.gate.threshold_for_budget()

Return a threshold whose exceedance count stays within an alert budget.

Usage

Source

train.gate.threshold_for_budget(scores, *, fires_per_100, total_turns)

The threshold fires where score >= threshold. It is conservative around ties: a tied score is excluded when including the whole tie would exceed the budget.

Parameters

scores: np.ndarray: Scores whose larger values are more eligible to fire.
fires_per_100: float: Maximum fires allowed per 100 total turns.
total_turns: int: Turn count used to convert the rate into an integer budget.

Returns

float: The lowest threshold that admits as many scores as possible within budget.

Raises

ValueError: If scores are empty, total_turns is not positive, or the rate is negative.

train.gate.matched_fire_mask()

Return a higher-is-fire mask matched conservatively to a fire budget.

Usage

Source

train.gate.matched_fire_mask(fire_scores, *, budget_fires)

Parameters

fire_scores: np.ndarray: Explicitly oriented scores where larger values mean a row is more likely to fire.
budget_fires: int: Maximum number of rows that may fire.

Returns

np.ndarray: A boolean mask firing on the highest scores without splitting ties.

Raises

ValueError: If fire_scores is empty or budget_fires is negative.