Skip to content

Readiness adjustment policy

This section documents readiness adjustment layer (RAL) policy implementations provided by eb-optimization.

RAL policies define how forecast outputs are adjusted based on readiness signals and operational thresholds to balance service risk and cost efficiency.

eb_optimization.policies.ral_policy

Policy artifacts for the Readiness Adjustment Layer (RAL).

This module defines portable, immutable policy objects produced by offline optimization and consumed by deterministic evaluation and production workflows.

Responsibilities: - Represent learned RAL parameters (global and optional segment-level uplifts) - Provide a stable, serializable contract between optimization and evaluation - Support audit and governance workflows

Non-responsibilities: - Learning or tuning parameters - Applying policies to data - Defining metric or loss functions

Design philosophy: Policies are artifacts, not algorithms. They encode decisions derived from optimization, not the optimization process itself.

RALPolicy dataclass

Portable policy artifact for the Readiness Adjustment Layer (RAL).

A :class:~eb_optimization.policies.ral_policy.RALPolicy is the output of an offline tuning process (e.g., grid search or evolutionary optimization) and the input to deterministic evaluation / production application.

Conceptually, RAL applies a multiplicative uplift to a baseline forecast:

\[ \hat{y}^{(r)} = u \cdot \hat{y} \]

where u can be either:

  • a global uplift (global_uplift), applied to all rows, and/or
  • segment-level uplifts stored in uplift_table, keyed by segment_cols

Segment-level uplifts must fall back to the global uplift for unseen segment combinations at application time.

Attributes:

Name Type Description
global_uplift float

The global multiplicative uplift used as a fallback and baseline readiness adjustment.
segment_cols list[str]

The segmentation columns used to key uplift_table. Empty means "global-only".
uplift_table DataFrame | None

Optional DataFrame with columns [*segment_cols, "uplift"] containing segment-level uplifts. If None or empty, the policy is global-only.
Notes

This dataclass is intentionally simple and serializable. It is meant to be:

  • produced offline in eb-optimization
  • applied deterministically in eb-evaluation
  • loggable/auditable as part of operational governance

The policy does not encode metric definitions or optimization state—only the artifacts needed to execute the adjustment.

is_segmented()

Return True if the policy contains segment-level uplifts.

adjust_forecast(df, forecast_col)

Apply the RAL policy to adjust the forecast values.

This method applies the global uplift to all rows, and applies segment-level uplifts if the policy is segmented and matching segments exist in the uplift_table.

Parameters:

Name Type Description Default
df DataFrame

The input DataFrame containing the forecast to adjust.

 required
forecast_col str

The name of the column in df containing the forecast values to adjust.

 required

Returns:

Type Description
Series

A series with the adjusted forecast values.

transform(df, forecast_col)

Transform the input DataFrame by applying the forecast adjustment.

RALBands dataclass

Risk-region thresholds for a two-band additive RAL policy.

mid Lower bound for the mid-risk region (inclusive). high Lower bound for the high-risk region (inclusive).

The two-band transform is: - add d_high when yhat >= high - add d_mid when mid <= yhat < high

RALBandThresholds dataclass

Canonical two-band thresholds artifact.

This is the same concept as :class:~eb_optimization.policies.ral_policy.RALBands, but exposed as a named artifact for the canonical "learn thresholds + deltas" RAL approach (Option E).

mid Lower bound for the mid-risk region (inclusive). high Lower bound for the high-risk region (inclusive).

Notes
  • high must be >= mid.
  • Thresholds are assumed to be non-negative. (Many domains normalize to [0, 1], but we do not hard-cap at 1.0 to allow safe usage when values can exceed 1.)

RALDeltas dataclass

Two-band additive deltas for a two-band RAL policy.

RALTwoBandPolicy dataclass

Portable policy artifact for two-band additive RAL.

This policy encodes the exact "two-band" additive RAL used in the ISO-NE example notebook:

  • If baseline forecast \(\hat{y}\) is in the mid-risk band: $$ \hat{y}^{(r)} = \hat{y} + d_{\text{mid}} $$
  • If baseline forecast \(\hat{y}\) is in the high-risk band: $$ \hat{y}^{(r)} = \hat{y} + d_{\text{high}} $$

Deltas can be:

  • global (fallback) via global_deltas, and/or
  • per-key overrides via per_key_deltas, keyed by a segment key column (e.g., interface).
Notes

This class is intentionally a policy artifact (parameters + deterministic application). It does not learn deltas; it only stores and applies them.

get_deltas(key=None)

Return deltas for a key (or the global deltas if none/unknown).

adjust_forecast(df, forecast_col, *, key_col=None)

Apply the two-band additive RAL policy to a forecast column.

Parameters:

Name Type Description Default
df DataFrame

Input DataFrame containing the forecast to adjust.

 required
forecast_col str

Column name containing baseline forecast values.

 required
key_col str

Column name containing keys for per-key deltas (e.g., "interface"). If omitted, the global deltas are applied.

 None

Returns:

Type Description
Series

Adjusted forecast values as a series named "readiness_forecast".

transform(df, forecast_col, *, key_col=None)

Transform the input DataFrame by applying the forecast adjustment.

to_dict()

Serialize to a JSON-friendly dict.

from_dict(d) classmethod

Deserialize from a dict produced by to_dict().

RALThresholdTwoBandPolicy dataclass

Canonical RAL policy artifact: learnable thresholds + additive deltas (Option E).

This policy generalizes :class:~eb_optimization.policies.ral_policy.RALTwoBandPolicy by allowing both thresholds and deltas to be specified globally and overridden per-key (e.g., per interface).

Application (for each row) uses the thresholds for the row's key (or global): - add d_high when yhat >= high - add d_mid when mid <= yhat < high

Notes
  • This is still a policy artifact, not an optimizer.
  • Guardrails (like min tail count) should be enforced by the tuner that produces it.

get_thresholds(key=None)

Return thresholds for a key (or the global thresholds if none/unknown).

get_deltas(key=None)

Return deltas for a key (or the global deltas if none/unknown).

adjust_forecast(df, forecast_col, *, key_col=None)

Apply the canonical (threshold + delta) two-band RAL policy.

Parameters:

Name Type Description Default
df DataFrame

Input DataFrame containing the forecast to adjust.

 required
forecast_col str

Column name containing baseline forecast values.

 required
key_col str

Column name containing keys for per-key overrides (e.g., "interface"). If omitted, global thresholds and deltas are applied.

 None

Returns:

Type Description
Series

Adjusted forecast values as a series named "readiness_forecast".

adjust_forecast_capped(df, forecast_col, *, key_col=None, lower=0.0, upper=1.0)

Apply the canonical policy and optionally cap the adjusted forecast.

This is a low-risk guardrail for domains with known physical bounds.

Parameters:

Name Type Description Default
df DataFrame

Input DataFrame containing the forecast to adjust.

 required
forecast_col str

Column name containing baseline forecast values.

 required
key_col str

Column name containing keys for per-key overrides (e.g., "interface").

 None
lower float

Lower cap applied via np.maximum.

 0.0
upper float or None

Upper cap applied via np.minimum. Use None to disable the upper cap.

 1.0

Returns:

Type Description
Series

Adjusted and (optionally) capped forecast as "readiness_forecast".

transform(df, forecast_col, *, key_col=None)

Transform the input DataFrame by applying the forecast adjustment.

to_dict()

Serialize to a JSON-friendly dict.

from_dict(d) classmethod

Deserialize from a dict produced by to_dict().

apply_ral_policy(df, forecast_col, policy=DEFAULT_RAL_POLICY)

Convenience functional wrapper to apply a RALPolicy.