Skip to content

Diagnostic execution

This section documents utilities for executing diagnostic routines in eb-evaluation.

These utilities coordinate the execution of multiple diagnostics over forecast outputs and input data.

eb_evaluation.diagnostics.run

Run-level orchestration for governance-oriented readiness evaluation.

This module is the "wiring layer" between: - raw evaluation series (y, yhat_base, yhat_ral), - diagnostic computations (DQC, FPC), - governance decision surface (DQC x FPC), - and a minimal recommended routing mode for downstream reporting.

Design goals
  • Keep diagnostic modules pure (no orchestration inside dqc.py / fpc.py).
  • Keep validation entrypoints stable (validate.py remains a thin wrapper layer).
  • Provide a single, auditable choke point to compute + gate readiness evaluation.

This module does NOT persist artifacts. Persistence/adapters should live in a separate "artifacts" layer if/when needed.

GateResult dataclass

Combined governance artifact (run-level).

This is intentionally small and "portable" as an in-memory object. If you later decide to persist it across systems, define a contract in eb-contracts.

run_governance_gate(*, y, yhat_base, yhat_ral, tau, cwsl_r=None, dqc_thresholds=None, fpc_thresholds=None, preset=None, snap_mode='ceil')

Run the minimal governance gate and return a recommended evaluation mode.

Routing semantics
  • "reroute_discrete": When FPC is INCOMPATIBLE for the applicable space (snapped if required, raw otherwise). This indicates scale-based readiness adjustment is not a valid control lever and discrete decision modeling should be used.
  • "pack_aware": When snapping is required by DQC and FPC is not incompatible. Indicates downstream evaluation should interpret τ in grid units and (if using RAL) apply snap-to-grid to adjusted forecasts before scoring.
  • "continuous": When demand is continuous-like and FPC is not incompatible.

Parameters:

Name Type Description Default
y Sequence[float]

Realized demand series.

 required
yhat_base Sequence[float]

Baseline forecasts (raw units).

 required
yhat_ral Sequence[float]

Readiness-adjusted forecasts (raw units).

 required
tau float

Tolerance band for HR@τ (raw units). If snapping is required, governance indicates τ should be interpreted in grid units downstream.

 required
cwsl_r float | None

Optional CWSL under/over cost ratio r (>= 1 typically). When provided, CWSL response is included in signals and may influence classification.

 None
dqc_thresholds DQCThresholds | None

Optional explicit thresholds. If preset is provided, explicit thresholds are not allowed.

 None
fpc_thresholds DQCThresholds | None

Optional explicit thresholds. If preset is provided, explicit thresholds are not allowed.

 None
preset GovernancePreset | str | None

Optional governance preset name/enum; determines default thresholds.

 None
snap_mode Literal['ceil', 'round', 'floor']

Snapping mode used when snapping is required.

 'ceil'

Returns:

Type Description
GateResult

Combined diagnostic results + governance decision + recommended routing.

Raises:

Type Description
ValueError

If series lengths mismatch, or if preset is mixed with explicit thresholds.