Skip to content

Sensitivity analysis

This section documents sensitivity analysis utilities provided by eb-optimization.

Sensitivity analysis supports evaluation of how optimization outcomes respond to changes in policy parameters, enabling assessment of robustness and identification of critical thresholds.

eb_optimization.tuning.sensitivity

CWSL cost-ratio sensitivity utilities.

This module provides helpers for computing a sensitivity curve of Cost-Weighted Service Loss (CWSL) across a grid of cost ratios:

\[ R = \frac{c_u}{c_o} \]

Given an overbuild cost coefficient \(c_o\) and ratio \(R\), the implied underbuild cost is:

\[ c_u = R \cdot c_o \]
Why this lives in eb-optimization

Computing a metric across a candidate grid of hyperparameters (like a cost ratio R) is an analysis / calibration workflow rather than a metric primitive.

  • eb-metrics remains the source of truth for metric math (e.g., cwsl).
  • eb-optimization owns grid-based evaluation, diagnostics, and tuning utilities.

This module therefore contains: - cwsl_sensitivity: array-level sweep (grid evaluation) - compute_cwsl_sensitivity_df: DataFrame-oriented wrapper (tidy long-form output)

cwsl_sensitivity(y_true, y_pred, *, R_list=(0.5, 1.0, 2.0, 3.0), co=1.0, sample_weight=None)

Evaluate CWSL across a grid of cost ratios (cost sensitivity analysis).

For each candidate ratio:

\[ R = \frac{c_u}{c_o} \]

holding co fixed and setting:

\[ c_u = R \cdot co \]

Parameters:

Name Type Description Default
y_true ndarray | Sequence[float]

Realized demand values (non-negative).

 required
y_pred ndarray | Sequence[float]

Forecast values (non-negative).

 required
R_list Sequence[float] | ndarray | Iterable[float]

Candidate cost ratios to evaluate. Non-finite and non-positive values are ignored.

 (0.5, 1.0, 2.0, 3.0)
co float | ndarray

Overbuild cost coefficient. Can be scalar or per-interval array.

 1.0
sample_weight ndarray | Sequence[float] | None

Optional non-negative weights per interval.

 None

Returns:

Type Description
dict[float, float]

Mapping {R: cwsl_value} for each valid R.

Raises:

Type Description
ValueError

If no valid ratios remain after filtering, if inputs are invalid, or if sample_weight contains negatives.

compute_cwsl_sensitivity_df(df, *, actual_col='actual_qty', forecast_col='forecast_qty', R_list=(0.5, 1.0, 2.0, 3.0), co=1.0, group_cols=None, sample_weight_col=None)

Compute CWSL sensitivity curves from a DataFrame.