Tau policy

This section documents tau-based policy implementations provided by eb-optimization.

Tau policies define threshold- or quantile-based decision rules that control when and how forecast-driven actions are triggered, enabling consistent handling of risk tolerance and sensitivity across optimization workflows.

eb_optimization.policies.tau_policy

Tau (τ) policy artifacts for eb-optimization.

This module defines frozen governance for selecting a tolerance τ used by HR@τ.

• tuning/tau.py: calibration logic (estimating τ from residuals)
• policies/tau_policy.py: frozen configuration + deterministic application wrappers

Policies should be stable, auditable, and safe to apply at runtime.

TauPolicy dataclass

Frozen τ policy configuration.

This is the governance object you can persist, version, and ship to downstream consumers.

Notes

• estimate_kwargs are passed through to estimate_tau.
• If cap_with_global is True, entity τ values are capped by a global cap derived from the full residual distribution at global_cap_quantile.

apply_tau_policy(y, yhat, policy=DEFAULT_TAU_POLICY)

Apply a frozen τ policy to produce τ (global).

Returns:

Type	Description
(tau, diagnostics)

apply_tau_policy_hr(y, yhat, policy=DEFAULT_TAU_POLICY)

Apply τ policy, then compute HR@τ.

Returns:

Type	Description
(hr, tau, diagnostics)

apply_entity_tau_policy(df, *, entity_col, y_col, yhat_col, policy=DEFAULT_TAU_POLICY, include_diagnostics=True)

Apply a frozen τ policy per entity (with optional global cap governance).

This wraps tuning.estimate_entity_tau but pins governance via TauPolicy.