Skip to content

Tau tuning

This section documents utilities for estimating and tuning tau parameters in eb-optimization.

Tau tuning supports calibration of threshold- and quantile-based decision parameters that control when optimization policies trigger actions, enabling consistent sensitivity and risk tolerance across optimization workflows.

eb_optimization.tuning.tau

Data-driven tolerance (τ) selection utilities for HR@τ.

This module provides deterministic, residual-only methods for selecting the tolerance parameter τ used by the hit-rate metric HR@τ (hit rate within an absolute-error band).

The hit-rate metric is:

\[ \mathrm{HR}@\tau = \frac{1}{n}\sum_{i=1}^{n}\mathbf{1}\left(|y_i-\hat{y}_i|\le \tau\right) \]

Here, τ defines an acceptability band: the maximum absolute error considered operationally acceptable.

Design notes
  • τ is estimated from historical residuals only (no exogenous data, no model assumptions).
  • The module supports global τ estimation and entity-level τ estimation.
  • Optional governance controls allow capping entity τ values by a global cap to prevent tolerance inflation.

TauEstimate dataclass

Result container for τ estimation.

hr_at_tau(y, yhat, tau)

Compute HR@τ: fraction of observations whose absolute error is within τ.

estimate_tau(y, yhat, method='target_hit_rate', *, target_hit_rate=0.9, grid=None, grid_size=101, grid_quantiles=(0.0, 0.99), knee_rule='slope_threshold', slope_threshold=0.0025, lambda_=0.1, tau_max=None, tau_floor=0.0, tau_cap=None)

Estimate a global tolerance τ from residuals.

estimate_entity_tau(df, *, entity_col, y_col, yhat_col, method='target_hit_rate', min_n=30, estimate_kwargs=None, cap_with_global=False, global_cap_quantile=0.99, include_diagnostics=True)

Estimate τ per entity from residuals.

hr_auto_tau(y, yhat, method='target_hit_rate', **estimate_kwargs)

Estimate τ from residuals, then compute HR@τ. Returns (hr, tau, diagnostics).