eb-optimization 0.1.0__py3-none-any.whl

eb_optimization/policies/tau_policy.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+"""
+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.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Mapping, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+from eb_optimization.tuning.tau import (
+    TauMethod,
+    estimate_tau,
+    estimate_entity_tau,
+    hr_at_tau,
+)
+
+
+@dataclass(frozen=True)
+class TauPolicy:
+    """
+    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`.
+    """
+
+    method: TauMethod = "target_hit_rate"
+    min_n: int = 30
+
+    # Passed to estimate_tau(...)
+    estimate_kwargs: Mapping[str, Any] = None  # type: ignore[assignment]
+
+    # Governance
+    cap_with_global: bool = False
+    global_cap_quantile: float = 0.99
+
+    def __post_init__(self) -> None:
+        # dataclasses + Mapping default guard
+        if self.estimate_kwargs is None:  # type: ignore[truthy-bool]
+            object.__setattr__(self, "estimate_kwargs", {})
+
+        if self.min_n < 1:
+            raise ValueError(f"min_n must be >= 1. Got {self.min_n}.")
+        if not (0.0 < self.global_cap_quantile <= 1.0):
+            raise ValueError(
+                f"global_cap_quantile must be in (0, 1]. Got {self.global_cap_quantile}."
+            )
+
+
+# ----------------------------------------------------------------------
+# Default, exported policy
+# ----------------------------------------------------------------------
+DEFAULT_TAU_POLICY = TauPolicy(
+    method="target_hit_rate",
+    min_n=30,
+    estimate_kwargs={
+        "target_hit_rate": 0.90,
+        "tau_floor": 0.0,
+        "tau_cap": None,
+    },
+    cap_with_global=False,
+    global_cap_quantile=0.99,
+)
+
+
+def apply_tau_policy(
+    y: Union[pd.Series, np.ndarray, Iterable[float]],
+    yhat: Union[pd.Series, np.ndarray, Iterable[float]],
+    policy: TauPolicy = DEFAULT_TAU_POLICY,
+) -> Tuple[float, Dict[str, Any]]:
+    """
+    Apply a frozen τ policy to produce τ (global).
+
+    Returns
+    -------
+    (tau, diagnostics)
+    """
+    est = estimate_tau(
+        y=y,
+        yhat=yhat,
+        method=policy.method,
+        **dict(policy.estimate_kwargs),
+    )
+    return (float(est.tau), dict(est.diagnostics or {}))
+
+
+def apply_tau_policy_hr(
+    y: Union[pd.Series, np.ndarray, Iterable[float]],
+    yhat: Union[pd.Series, np.ndarray, Iterable[float]],
+    policy: TauPolicy = DEFAULT_TAU_POLICY,
+) -> Tuple[float, float, Dict[str, Any]]:
+    """
+    Apply τ policy, then compute HR@τ.
+
+    Returns
+    -------
+    (hr, tau, diagnostics)
+    """
+    tau, diag = apply_tau_policy(y=y, yhat=yhat, policy=policy)
+    if not np.isfinite(tau):
+        return (np.nan, np.nan, diag)
+    hr = hr_at_tau(y=y, yhat=yhat, tau=tau)
+    return (float(hr), float(tau), diag)
+
+
+def apply_entity_tau_policy(
+    df: pd.DataFrame,
+    *,
+    entity_col: str,
+    y_col: str,
+    yhat_col: str,
+    policy: TauPolicy = DEFAULT_TAU_POLICY,
+    include_diagnostics: bool = True,
+) -> pd.DataFrame:
+    """
+    Apply a frozen τ policy per entity (with optional global cap governance).
+
+    This wraps tuning.estimate_entity_tau but pins governance via TauPolicy.
+    """
+    return estimate_entity_tau(
+        df=df,
+        entity_col=entity_col,
+        y_col=y_col,
+        yhat_col=yhat_col,
+        method=policy.method,
+        min_n=policy.min_n,
+        estimate_kwargs=policy.estimate_kwargs,
+        cap_with_global=policy.cap_with_global,
+        global_cap_quantile=policy.global_cap_quantile,
+        include_diagnostics=include_diagnostics,
+    )
+
+
+__all__ = [
+    "TauPolicy",
+    "DEFAULT_TAU_POLICY",
+    "apply_tau_policy",
+    "apply_tau_policy_hr",
+    "apply_entity_tau_policy",
+]

eb_optimization/search/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+"""
+Search primitives for the Electric Barometer optimization layer.
+
+The `eb_optimization.search` package contains **generic, reusable search kernels**
+that implement *how* to search over a discrete candidate space, independent of
+any specific metric, policy, or business objective.
+
+Design intent
+-------------
+- **search/**: mechanics of search (argmin/argmax, tie-breaking, grid iteration)
+- **tuning/**: what to search + objective definition + returned artifacts
+- **policies/**: frozen, declarative outputs of tuning (no search at runtime)
+
+Key rules
+---------
+- No domain-specific policy logic
+- No metric semantics
+- No pandas-heavy workflows
+- Pure, deterministic search utilities
+"""
+
+__all__ = [
+    "grid",
+    "kernels",
+]

eb_optimization/search/grid.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+"""
+Grid construction utilities for optimization search spaces.
+
+This module provides small, deterministic helpers for constructing bounded,
+interpretable parameter grids used by offline optimization routines.
+
+Responsibilities:
+- Create numerically stable, reproducible grids for scalar parameters
+- Enforce positivity and boundary constraints
+- Standardize grid behavior across tuners
+
+Non-responsibilities:
+- Evaluating objectives
+- Selecting optimal parameters
+- Performing any optimization logic
+
+Design philosophy:
+This utility favors bounded, discrete search spaces for interpretability, auditability,
+and deployability of learned policies.
+"""
+
+import numpy as np
+import math
+
+def make_float_grid(x_min: float, x_max: float, step: float, decimals: int = 10) -> np.ndarray:
+    r"""Create a numerically robust 1D grid over a closed interval.
+
+    This utility is used throughout optimization to create bounded, interpretable
+    candidate sets for discrete parameter search (e.g., uplift multipliers, thresholds).
+
+    The returned grid:
+
+    - starts at `x_min`
+    - increments by `step`
+    - includes `x_max` (to the extent permitted by floating-point arithmetic)
+    - is clipped and de-duplicated for numerical stability
+
+    Parameters
+    ----------
+    x_min
+        Lower bound for the grid (inclusive). Must be strictly positive.
+    x_max
+        Upper bound for the grid (inclusive). Must be greater than or equal to `x_min`.
+    step
+        Step size between candidates. Must be strictly positive.
+    decimals
+        Rounding precision used to stabilize floats and de-duplicate.
+
+    Returns
+    -------
+    numpy.ndarray
+        A 1D array of unique grid values in ascending order.
+
+    Raises
+    ------
+    ValueError
+        If `step` is not strictly positive, if `x_min` is not strictly positive,
+        or if `x_max < x_min`.
+
+    Notes
+    -----
+    This utility ensures reproducible and stable grid construction for parameter tuning
+    and optimization purposes, while favoring discrete, bounded search spaces for
+    interpretability and deployability.
+    """
+    if step <= 0.0:
+        raise ValueError("step must be strictly positive.")
+    if x_min <= 0.0:
+        raise ValueError("x_min must be strictly positive.")
+    if x_max < x_min:
+        raise ValueError("x_max must be >= x_min.")
+
+    # Step-aligned grid starts at the first multiple of `step` that is >= x_min.
+    start = math.ceil(x_min / step) * step
+
+    # Generate core grid points [start, start + step, ..., x_max]
+    # Add a tiny epsilon to ensure inclusion when we're right on the boundary.
+    eps = 10 ** (-(decimals + 2))
+    core = np.arange(start, x_max + eps, step, dtype=float)
+
+    # Always include x_min and x_max explicitly
+    vals = np.concatenate(([float(x_min)], core, [float(x_max)]))
+
+    # Stabilize: round then unique then sort
+    vals = np.round(vals, decimals=decimals)
+    vals = np.unique(vals)
+    vals.sort()
+
+    return vals

eb_optimization/search/kernels.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+"""
+Generic discrete-search kernels for eb-optimization.
+
+This module defines *mechanical* optimization primitives for selecting an
+argmin or argmax over a finite candidate set.
+
+Responsibilities
+----------------
+- Iterate over a discrete candidate set
+- Evaluate a scalar objective function
+- Apply deterministic tie-breaking rules
+- Return the selected candidate and its score
+
+Non-responsibilities
+--------------------
+- Defining candidate grids (handled by ``search.grid``)
+- Computing domain-specific objectives (e.g., cost, HR@τ, utility)
+- Inspecting data distributions or residuals
+- Returning diagnostics, plots, or policies
+
+Design philosophy
+-----------------
+These kernels are intentionally simple, deterministic, and domain-agnostic.
+They serve as reusable building blocks for higher-level tuning logic
+(``tuning`` modules), enabling consistent and auditable optimization behavior
+across the Electric Barometer ecosystem.
+"""
+
+from typing import Callable, Iterable, Literal, TypeVar
+import numpy as np
+
+T = TypeVar("T")
+
+__all__ = [
+    "argmin_over_candidates",
+    "argmax_over_candidates",
+]
+
+
+def argmin_over_candidates(
+    candidates: Iterable[T],
+    score_fn: Callable[[T], float],
+    *,
+    tie_break: Literal["first", "last", "closest_to_zero"] = "first",
+) -> tuple[T, float]:
+    """
+    Select the candidate that minimizes a scalar score.
+
+    Parameters
+    ----------
+    candidates
+        Iterable of candidate values (e.g., floats, ints, tuples).
+    score_fn
+        Function mapping a candidate to a scalar score.
+    tie_break
+        Deterministic tie-breaking rule:
+        - ``"first"``: first candidate with minimal score
+        - ``"last"``: last candidate with minimal score
+        - ``"closest_to_zero"``: among ties, choose candidate with smallest
+          absolute value
+
+    Returns
+    -------
+    (best_candidate, best_score)
+
+    Raises
+    ------
+    ValueError
+        If ``candidates`` is empty or if ``score_fn`` returns a non-finite value.
+    """
+    best_candidate: T | None = None
+    best_score: float | None = None
+
+    for cand in candidates:
+        score = float(score_fn(cand))
+
+        if not np.isfinite(score):
+            raise ValueError(f"Non-finite score returned for candidate {cand!r}")
+
+        if best_score is None or score < best_score:
+            best_candidate = cand
+            best_score = score
+            continue
+
+        if score == best_score:
+            if tie_break == "last":
+                best_candidate = cand
+            elif tie_break == "closest_to_zero":
+                if abs(float(cand)) < abs(float(best_candidate)):  # type: ignore[arg-type]
+                    best_candidate = cand
+
+    if best_candidate is None or best_score is None:
+        raise ValueError("candidates must be a non-empty iterable")
+
+    return best_candidate, best_score
+
+
+def argmax_over_candidates(
+    candidates: Iterable[T],
+    score_fn: Callable[[T], float],
+    *,
+    tie_break: Literal["first", "last", "closest_to_zero"] = "first",
+) -> tuple[T, float]:
+    """
+    Select the candidate that maximizes a scalar score.
+
+    This is the argmax analogue of ``argmin_over_candidates``.
+    """
+    return argmin_over_candidates(
+        candidates=candidates,
+        score_fn=lambda c: -float(score_fn(c)),
+        tie_break=tie_break,
+    )

eb_optimization/tuning/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+"""
+Tuning utilities for the Electric Barometer ecosystem.
+
+The `eb_optimization.tuning` package contains grid-search and calibration helpers
+used to *select* hyperparameters and operating points for evaluation workflows.
+
+Design intent
+-------------
+- **eb-metrics**: metric math (single-source-of-truth implementations)
+- **eb-evaluation**: deterministic evaluation plumbing / orchestration
+- **eb-optimization**: tuning, search, calibration, and sensitivity sweeps
+
+Public API philosophy
+---------------------
+Keep the package import surface stable by exporting *modules* instead of
+re-exporting function symbols. This avoids import-time breakage when internals
+are renamed during refactors.
+"""
+
+__all__ = [
+    "cost_ratio",
+    "sensitivity",
+    "tau",
+    "ral",
+]

eb_optimization/tuning/cost_ratio.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+r"""
+Cost ratio (R) tuning utilities.
+
+This module provides calibration helpers for selecting the underbuild-to-overbuild
+cost ratio:
+
+$$
+    R = \frac{c_u}{c_o}
+$$
+
+These routines belong in **eb-optimization** because they *choose/govern* parameters
+from data over a candidate set (grid search + calibration diagnostics). They are not
+metric primitives (eb-metrics) and are not runtime policies (eb-optimization/policies).
+
+Layering:
+- search/ : reusable candidate-space utilities (grids, kernels)
+- tuning/ : define candidate grids + objectives + return calibration artifacts
+- policies/ : frozen artifacts that apply parameters deterministically at runtime
+"""
+
+from typing import Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+
+from .._utils import broadcast_param, handle_sample_weight, to_1d_array
+from ..search.kernels import argmin_over_candidates
+
+__all__ = [
+    "estimate_R_cost_balance",
+    "estimate_entity_R_from_balance",
+]
+
+
+# ---------------------------------------------------------------------
+# Global calibration (array-like)
+# ---------------------------------------------------------------------
+def estimate_R_cost_balance(
+    y_true: ArrayLike,
+    y_pred: ArrayLike,
+    R_grid: Sequence[float] = (0.5, 1.0, 2.0, 3.0),
+    co: Union[float, ArrayLike] = 1.0,
+    sample_weight: ArrayLike | None = None,
+) -> float:
+    r"""
+    Estimate a global cost ratio $R = c_u / c_o$ via cost balance.
+
+    This routine selects a single, global cost ratio $R$ by searching a
+    candidate grid and choosing the value where the total weighted underbuild
+    cost is closest to the total weighted overbuild cost.
+
+    For each candidate $R$ in ``R_grid``:
+
+    $$
+    \begin{aligned}
+    c_{u,i} &= R \cdot c_{o,i} \\
+    s_i &= \max(0, y_i - \hat{y}_i) \\
+    e_i &= \max(0, \hat{y}_i - y_i) \\
+    C_u(R) &= \sum_i w_i \; c_{u,i} \; s_i \\
+    C_o(R) &= \sum_i w_i \; c_{o,i} \; e_i
+    \end{aligned}
+    $$
+
+    and the selected value is:
+
+    $$
+    R^* = \arg\min_R \; \left| C_u(R) - C_o(R) \right|.
+    $$
+
+    Parameters
+    ----------
+    y_true
+        Realized demand (non-negative), shape (n_samples,).
+    y_pred
+        Forecast demand (non-negative), shape (n_samples,). Must match ``y_true``.
+    R_grid
+        Candidate ratios to search. Only strictly positive values are considered.
+    co
+        Overbuild cost coefficient $c_o$. May be scalar or 1D array of shape (n_samples,).
+        Underbuild cost is implied as $c_{u,i} = R \cdot c_{o,i}$.
+    sample_weight
+        Optional non-negative weights. If None, all intervals receive weight 1.0.
+
+    Returns
+    -------
+    float
+        Selected cost ratio in ``R_grid`` minimizing |under_cost - over_cost|.
+
+        Tie-breaking:
+        - In the degenerate perfect-forecast case (zero error everywhere), returns
+          the candidate closest to 1.0.
+        - Otherwise, if multiple candidates yield the same minimal gap, the first
+          encountered candidate (in filtered grid order) is returned.
+    """
+    y_true_arr = to_1d_array(y_true, "y_true")
+    y_pred_arr = to_1d_array(y_pred, "y_pred")
+
+    if y_true_arr.shape != y_pred_arr.shape:
+        raise ValueError(
+            "y_true and y_pred must have the same shape; "
+            f"got {y_true_arr.shape} and {y_pred_arr.shape}"
+        )
+
+    if np.any(y_true_arr < 0) or np.any(y_pred_arr < 0):
+        raise ValueError("y_true and y_pred must be non-negative.")
+
+    co_arr = broadcast_param(co, y_true_arr.shape, "co")
+    if np.any(co_arr <= 0):
+        raise ValueError("co must be strictly positive.")
+
+    w = handle_sample_weight(sample_weight, y_true_arr.shape[0])
+
+    shortfall = np.maximum(0.0, y_true_arr - y_pred_arr)
+    overbuild = np.maximum(0.0, y_pred_arr - y_true_arr)
+
+    R_grid_arr = np.asarray(R_grid, dtype=float)
+    if R_grid_arr.ndim != 1 or R_grid_arr.size == 0:
+        raise ValueError("R_grid must be a non-empty 1D sequence of floats.")
+
+    positive_R = R_grid_arr[R_grid_arr > 0]
+    if positive_R.size == 0:
+        raise ValueError("R_grid must contain at least one positive value.")
+
+    # Degenerate case: perfect forecast (no error anywhere)
+    if np.all(shortfall == 0.0) and np.all(overbuild == 0.0):
+        idx = int(np.argmin(np.abs(positive_R - 1.0)))
+        return float(positive_R[idx])
+
+    co_arr_f = co_arr.astype(float, copy=False)
+    w_f = w.astype(float, copy=False)
+
+    def _gap_for_R(R: float) -> float:
+        cu_arr = float(R) * co_arr_f
+        under_cost = float(np.sum(w_f * cu_arr * shortfall))
+        over_cost = float(np.sum(w_f * co_arr_f * overbuild))
+        return abs(under_cost - over_cost)
+
+    best_R, _best_gap = argmin_over_candidates(
+        candidates=positive_R,
+        score_fn=_gap_for_R,
+        tie_break="first",  # preserves prior behavior
+    )
+
+    return float(best_R)
+
+
+# ---------------------------------------------------------------------
+# Entity-level calibration (DataFrame)
+# ---------------------------------------------------------------------
+def estimate_entity_R_from_balance(
+    df: pd.DataFrame,
+    entity_col: str,
+    y_true_col: str,
+    y_pred_col: str,
+    ratios: Sequence[float] = (0.5, 1.0, 2.0, 3.0),
+    co: float = 1.0,
+    sample_weight_col: Optional[str] = None,
+) -> pd.DataFrame:
+    r"""
+    Estimate an entity-level cost ratio via a cost-balance grid search.
+
+    This function estimates a per-entity underbuild-to-overbuild cost ratio:
+
+    $$
+        R_e = \frac{c_{u,e}}{c_o}
+    $$
+
+    by searching over a user-provided grid of candidate ratios.
+
+    Returns one row per entity with chosen R and supporting diagnostics.
+    """
+    required = {entity_col, y_true_col, y_pred_col}
+    missing = required - set(df.columns)
+    if missing:
+        raise KeyError(f"Missing required columns in df: {sorted(missing)}")
+
+    if sample_weight_col is not None and sample_weight_col not in df.columns:
+        raise KeyError(f"sample_weight_col {sample_weight_col!r} not found in df")
+
+    ratios_arr = np.asarray(list(ratios), dtype=float)
+    if ratios_arr.ndim != 1 or ratios_arr.size == 0 or np.any(ratios_arr <= 0):
+        raise ValueError("ratios must be a non-empty 1D sequence of positive floats.")
+
+    if co <= 0:
+        raise ValueError("co must be strictly positive.")
+
+    results: list[dict] = []
+    grouped = df.groupby(entity_col, sort=False)
+
+    for entity_id, g in grouped:
+        y_true = g[y_true_col].to_numpy(dtype=float)
+        y_pred = g[y_pred_col].to_numpy(dtype=float)
+
+        if sample_weight_col is not None:
+            w = g[sample_weight_col].to_numpy(dtype=float)
+        else:
+            w = np.ones_like(y_true, dtype=float)
+
+        if y_true.shape != y_pred.shape:
+            raise ValueError(
+                f"For entity {entity_id!r}, y_true and y_pred have different shapes: "
+                f"{y_true.shape} vs {y_pred.shape}"
+            )
+        if np.any(y_true < 0) or np.any(y_pred < 0):
+            raise ValueError(
+                f"For entity {entity_id!r}, y_true and y_pred must be non-negative."
+            )
+        if np.any(w < 0):
+            raise ValueError(
+                f"For entity {entity_id!r}, sample weights must be non-negative."
+            )
+
+        shortfall = np.maximum(0.0, y_true - y_pred)
+        overbuild = np.maximum(0.0, y_pred - y_true)
+
+        # Degenerate case: no error at all for this entity
+        if np.all(shortfall == 0.0) and np.all(overbuild == 0.0):
+            idx = int(np.argmin(np.abs(ratios_arr - 1.0)))
+            R_e = float(ratios_arr[idx])
+            cu_e = R_e * float(co)
+            results.append(
+                {
+                    entity_col: entity_id,
+                    "R": R_e,
+                    "cu": cu_e,
+                    "co": float(co),
+                    "under_cost": 0.0,
+                    "over_cost": 0.0,
+                    "diff": 0.0,
+                }
+            )
+            continue
+
+        w_f = w.astype(float, copy=False)
+        co_f = float(co)
+
+        def _diff_for_R(R: float) -> float:
+            cu_val = float(R) * co_f
+            under_cost = float(np.sum(w_f * cu_val * shortfall))
+            over_cost = float(np.sum(w_f * co_f * overbuild))
+            return abs(under_cost - over_cost)
+
+        best_R, best_diff = argmin_over_candidates(
+            candidates=ratios_arr,
+            score_fn=_diff_for_R,
+            tie_break="first",  # preserves prior behavior
+        )
+
+        # Recompute diagnostics for the chosen R (single pass)
+        best_R_f = float(best_R)
+        best_cu = best_R_f * co_f
+        best_under_cost = float(np.sum(w_f * best_cu * shortfall))
+        best_over_cost = float(np.sum(w_f * co_f * overbuild))
+
+        results.append(
+            {
+                entity_col: entity_id,
+                "R": best_R_f,
+                "cu": float(best_cu),
+                "co": float(co_f),
+                "under_cost": float(best_under_cost),
+                "over_cost": float(best_over_cost),
+                "diff": float(best_diff),
+            }
+        )
+
+    return pd.DataFrame(results)