Skip to content

Cost ratio policy

This section documents the cost ratio policy implementations provided by eb-optimization.

Cost ratio policies define how asymmetric over- and under-prediction costs are applied to forecast outputs in order to adjust decisions according to business risk preferences.

eb_optimization.policies.cost_ratio_policy

Cost-ratio (R = c_u / c_o) policy artifacts for eb-optimization.

This module defines frozen governance for selecting and applying a cost ratio R (and derived underbuild cost c_u) used by asymmetric cost metrics like CWSL.

Layering & responsibilities
  • tuning/cost_ratio.py: Calibration logic (estimating R from residuals / cost balance).
  • policies/cost_ratio_policy.py: Frozen configuration + deterministic application wrappers.

CostRatioPolicy dataclass

Frozen cost-ratio (R) policy configuration.

Attributes:

Name Type Description
R_grid Sequence[float]

Candidate ratios to search. Only strictly positive values are considered.
co float

Default overbuild cost coefficient used for entity-level estimation.
min_n int

Minimum number of observations required to estimate an entity-level R.

apply_cost_ratio_policy(y_true, y_pred, *, policy=DEFAULT_COST_RATIO_POLICY, co=None, sample_weight=None, gate='warn', identifiability_override_reason=None)

Apply a frozen cost-ratio policy to estimate a global R.

Notes

This policy boundary surfaces identifiability / stability diagnostics when available. It does NOT change the selection behavior; it only enriches the returned diagnostics.

Gating

gate controls what happens when tuning reports is_identifiable=False:

  • gate="off" : no action (still reports diagnostics)
  • gate="warn" : emit a RuntimeWarning (default)
  • gate="raise": raise ValueError
Overrides

If identifiability_override_reason is provided, the gate will not warn/raise, and the reason is recorded in diagnostics for auditability.

apply_entity_cost_ratio_policy(df, *, entity_col, y_true_col, y_pred_col, policy=DEFAULT_COST_RATIO_POLICY, co=None, sample_weight_col=None, include_diagnostics=True, gate='warn', identifiability_override_reason=None)

Apply a frozen cost-ratio policy per entity.

Notes

This policy boundary surfaces per-entity calibration diagnostics (in the diagnostics column) for eligible entities when include_diagnostics=True.

Entity-level identifiability

The tuning artifact returns per-entity diagnostics dicts. If those dicts contain an is_identifiable field, this function will: - surface a convenience is_identifiable column, and - optionally warn/raise based on gate.

If no such field exists (older tuning versions), gating is a no-op.