eb-evaluation 0.2.3__tar.gz → 0.2.7__tar.gz

{eb_evaluation-0.2.3/src/eb_evaluation.egg-info → eb_evaluation-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eb-evaluation
-Version: 0.2.3
+Version: 0.2.7
 Summary: Electric Barometer: DataFrame-based evaluation utilities for CWSL and related metrics.
 Author-email: "Kyle Corrie (Economistician)" <kcorrie@economistician.com>
 License-Expression: BSD-3-Clause
@@ -21,14 +21,24 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.24
 Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
 Requires-Dist: eb-metrics<0.3,>=0.2
 Requires-Dist: eb-adapters<0.3,>=0.2
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
-Requires-Dist: scikit-learn>=1.3; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: boosting
+Requires-Dist: xgboost>=2.0; extra == "boosting"
+Requires-Dist: lightgbm>=4.0; extra == "boosting"
+Requires-Dist: catboost>=1.2; extra == "boosting"
+Provides-Extra: all
+Requires-Dist: pytest>=8.0; extra == "all"
+Requires-Dist: pytest-cov>=5.0; extra == "all"
+Requires-Dist: xgboost>=2.0; extra == "all"
+Requires-Dist: lightgbm>=4.0; extra == "all"
+Requires-Dist: catboost>=1.2; extra == "all"
 Dynamic: license-file
 
 # Electric Barometer · Evaluation (`eb-evaluation`)
@@ -46,7 +56,7 @@ Evaluation and model selection utilities for applying Electric Barometer metrics
 
 `eb-evaluation` provides the evaluation and model selection layer of the Electric Barometer ecosystem. It applies metric primitives to forecasts and observations across entities, groups, and hierarchical structures, enabling consistent assessment of forecasting performance in operational settings.
 
-The package focuses on DataFrame-first evaluation workflows, including tolerance-based scoring, cost-sensitive comparison, and readiness-oriented adjustment logic. It does not define feature construction or model interfaces; instead, it consumes standardized inputs from upstream layers and produces evaluation outputs that can be used for model selection, reporting, and decision support.
+The package focuses on DataFrame-first evaluation workflows, including cost-sensitive comparison, tolerance-aware scoring given explicit thresholds, and readiness-oriented adjustment logic. It does not define feature construction or model interfaces; instead, it consumes standardized inputs from upstream layers and produces evaluation outputs that can be used for model selection, reporting, and decision support.
 
 ---
 
@@ -75,35 +85,35 @@ The package supports Python 3.10 and later.
 ## Core Concepts
 
 - **DataFrame-first evaluation** — Evaluation logic operates directly on tabular forecast and observation data, enabling transparent aggregation, grouping, and comparison across entities and hierarchies.
-- **Cost- and tolerance-aware scoring** — Forecast performance is assessed using metrics that reflect asymmetric cost, acceptable deviation thresholds, and operational risk rather than purely symmetric statistical error.
+- **Cost- and tolerance-aware scoring** — Forecast performance is assessed using metrics that reflect asymmetric cost and explicitly supplied deviation thresholds, rather than purely symmetric statistical error.
 - **Hierarchical and panel semantics** — Evaluation respects entity boundaries, grouping structure, and temporal alignment, ensuring correctness in multi-level forecasting environments.
 - **Model comparability** — Forecasts produced by heterogeneous models can be evaluated and compared using a consistent set of metrics and aggregation rules.
-- **Readiness-oriented selection** — Model selection emphasizes execution feasibility and operational adequacy, not just aggregate accuracy, supporting decision-aligned forecasting workflows.
+- **Readiness-oriented selection** — Model selection emphasizes execution feasibility and operational adequacy as reflected in evaluation metrics, not just aggregate accuracy, supporting decision-aligned forecasting workflows.
 
 ---
 
 ## Minimal Example
 
-The example below shows how forecasts and observations can be evaluated and compared across entities using Electric Barometer metrics in a DataFrame-first workflow.
+The example below shows how forecast accuracy can be evaluated across entities
+using Electric Barometer metrics in a DataFrame-first workflow.
 
 ```python
 import pandas as pd
-from eb_evaluation.dataframe.compare import compare_models
+from eb_evaluation.dataframe import compute_cwsl_df
 
 # Example evaluation data
 df = pd.DataFrame({
     "entity_id": ["A", "A", "B", "B"],
     "date": pd.to_datetime(["2024-01-01", "2024-01-02"] * 2),
     "actual": [10, 12, 7, 9],
-    "model_a": [9, 11, 8, 10],
-    "model_b": [11, 13, 6, 8],
+    "prediction": [9, 11, 8, 10],
 })
 
-# Compare models using a common evaluation contract
-results = compare_models(
+# Compute Cost-Weighted Service Loss (CWSL)
+results = compute_cwsl_df(
     df,
     actual_col="actual",
-    prediction_cols=["model_a", "model_b"],
+    prediction_col="prediction",
     entity_col="entity_id",
     time_col="date",
 )
@@ -115,5 +125,5 @@ print(results)
 
 ## License
 
-BSD 3-Clause License.  
+BSD 3-Clause License.
 © 2025 Kyle Corrie.

{eb_evaluation-0.2.3 → eb_evaluation-0.2.7}/README.md

@@ -13,7 +13,7 @@ Evaluation and model selection utilities for applying Electric Barometer metrics
 
 `eb-evaluation` provides the evaluation and model selection layer of the Electric Barometer ecosystem. It applies metric primitives to forecasts and observations across entities, groups, and hierarchical structures, enabling consistent assessment of forecasting performance in operational settings.
 
-The package focuses on DataFrame-first evaluation workflows, including tolerance-based scoring, cost-sensitive comparison, and readiness-oriented adjustment logic. It does not define feature construction or model interfaces; instead, it consumes standardized inputs from upstream layers and produces evaluation outputs that can be used for model selection, reporting, and decision support.
+The package focuses on DataFrame-first evaluation workflows, including cost-sensitive comparison, tolerance-aware scoring given explicit thresholds, and readiness-oriented adjustment logic. It does not define feature construction or model interfaces; instead, it consumes standardized inputs from upstream layers and produces evaluation outputs that can be used for model selection, reporting, and decision support.
 
 ---
 
@@ -42,35 +42,35 @@ The package supports Python 3.10 and later.
 ## Core Concepts
 
 - **DataFrame-first evaluation** — Evaluation logic operates directly on tabular forecast and observation data, enabling transparent aggregation, grouping, and comparison across entities and hierarchies.
-- **Cost- and tolerance-aware scoring** — Forecast performance is assessed using metrics that reflect asymmetric cost, acceptable deviation thresholds, and operational risk rather than purely symmetric statistical error.
+- **Cost- and tolerance-aware scoring** — Forecast performance is assessed using metrics that reflect asymmetric cost and explicitly supplied deviation thresholds, rather than purely symmetric statistical error.
 - **Hierarchical and panel semantics** — Evaluation respects entity boundaries, grouping structure, and temporal alignment, ensuring correctness in multi-level forecasting environments.
 - **Model comparability** — Forecasts produced by heterogeneous models can be evaluated and compared using a consistent set of metrics and aggregation rules.
-- **Readiness-oriented selection** — Model selection emphasizes execution feasibility and operational adequacy, not just aggregate accuracy, supporting decision-aligned forecasting workflows.
+- **Readiness-oriented selection** — Model selection emphasizes execution feasibility and operational adequacy as reflected in evaluation metrics, not just aggregate accuracy, supporting decision-aligned forecasting workflows.
 
 ---
 
 ## Minimal Example
 
-The example below shows how forecasts and observations can be evaluated and compared across entities using Electric Barometer metrics in a DataFrame-first workflow.
+The example below shows how forecast accuracy can be evaluated across entities
+using Electric Barometer metrics in a DataFrame-first workflow.
 
 ```python
 import pandas as pd
-from eb_evaluation.dataframe.compare import compare_models
+from eb_evaluation.dataframe import compute_cwsl_df
 
 # Example evaluation data
 df = pd.DataFrame({
     "entity_id": ["A", "A", "B", "B"],
     "date": pd.to_datetime(["2024-01-01", "2024-01-02"] * 2),
     "actual": [10, 12, 7, 9],
-    "model_a": [9, 11, 8, 10],
-    "model_b": [11, 13, 6, 8],
+    "prediction": [9, 11, 8, 10],
 })
 
-# Compare models using a common evaluation contract
-results = compare_models(
+# Compute Cost-Weighted Service Loss (CWSL)
+results = compute_cwsl_df(
     df,
     actual_col="actual",
-    prediction_cols=["model_a", "model_b"],
+    prediction_col="prediction",
     entity_col="entity_id",
     time_col="date",
 )
@@ -82,5 +82,5 @@ print(results)
 
 ## License
 
-BSD 3-Clause License.  
-© 2025 Kyle Corrie.
+BSD 3-Clause License.
+© 2025 Kyle Corrie.

{eb_evaluation-0.2.3 → eb_evaluation-0.2.7}/pyproject.toml

@@ -3,7 +3,7 @@
 ######################################
 [project]
 name = "eb-evaluation"
-version = "0.2.3"
+version = "0.2.7"
 description = "Electric Barometer: DataFrame-based evaluation utilities for CWSL and related metrics."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -39,6 +39,7 @@ classifiers = [
 dependencies = [
   "numpy>=1.24",
   "pandas>=2.0",
+  "scikit-learn>=1.3",
 
   # Electric Barometer compatibility band (0.2.x)
   "eb-metrics>=0.2,<0.3",
@@ -62,7 +63,6 @@ Documentation = "https://github.com/Economistician/eb-docs"
 # CI / test-only dependencies
 test = [
   "pytest>=8.0",
-  "scikit-learn>=1.3",
 ]
 
 # Local developer tooling
@@ -71,6 +71,24 @@ dev = [
   "pytest-cov>=5.0",
 ]
 
+# Optional "boosting engines" commonly used in the AutoEngine zoo.
+# These are intentionally extras because they can be heavy / platform-specific.
+boosting = [
+  "xgboost>=2.0",
+  "lightgbm>=4.0",
+  "catboost>=1.2",
+]
+
+# Combined extra to satisfy the "extras: all" CI contract.
+# Aggregates optional test + dev tooling + optional engines.
+all = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "xgboost>=2.0",
+  "lightgbm>=4.0",
+  "catboost>=1.2",
+]
+
 ######################################
 # Build system
 ######################################
@@ -89,4 +107,4 @@ where = ["src"]
 ######################################
 [tool.pytest.ini_options]
 pythonpath = ["src"]
-addopts = "-ra"
+addopts = "-ra"

{eb_evaluation-0.2.3 → eb_evaluation-0.2.7}/src/eb_evaluation/__init__.py

@@ -12,7 +12,7 @@ architecture:
 
 - ``eb_metrics`` defines **metric math** (CWSL, NSL, UD, HR@τ, FRS, etc.)
 - ``eb-evaluation`` provides **tabular orchestration**, grouping logic,
-  sensitivity analysis, tolerance calibration, and model selection
+  and model selection
 
 Primary capabilities include:
 
@@ -20,13 +20,8 @@ DataFrame evaluation
     - Single-slice and grouped CWSL computation
     - Hierarchical evaluation across multiple aggregation levels
     - Long-form (tidy) panel outputs for plotting and reporting
-    - Entity-aware evaluation with entity-specific cost ratios
-    - Cost-ratio (R = cu / co) sensitivity analysis
-
-Tolerance (τ) calibration
-    - Data-driven τ estimation from historical residuals
-    - Global and entity-level τ estimation with governance guards
-    - HR@τ computation with automatically selected tolerances
+    - Entity-aware evaluation using externally supplied entity-specific cost ratios
+    - Governance-oriented evaluation and workflow orchestration
 
 Model selection
     - Cost-aware comparison of forecast models
@@ -42,41 +37,33 @@ Design principles
 - **Deterministic & explicit**: no hidden heuristics; all behavior is
   controlled via parameters and documented outputs.
 
+Optimization utilities such as tolerance (τ) calibration, cost-ratio estimation,
+and sensitivity sweeps live exclusively in ``eb-optimization``.
+
 This package is intended to be used alongside ``eb_metrics`` and
 ``eb-adapters`` as part of the broader Electric Barometer ecosystem.
 """
 
+from __future__ import annotations
+
 from .dataframe import (
     compute_cwsl_df,
+    evaluate_governance_panel_df,
     evaluate_groups_df,
     evaluate_hierarchy_df,
     evaluate_panel_df,
     evaluate_panel_with_entity_R,
-    compute_cwsl_sensitivity_df,
-    cwsl_sensitivity_df,
-    estimate_entity_R_from_balance,
-)
-
-from .dataframe.tolerance import (
-    hr_at_tau,
-    estimate_tau,
-    estimate_entity_tau,
-    hr_auto_tau,
-    TauEstimate,
+    run_governance_workflow_df,
+    run_governance_workflow_df_dict,
 )
 
 __all__ = [
     "compute_cwsl_df",
+    "evaluate_governance_panel_df",
     "evaluate_groups_df",
     "evaluate_hierarchy_df",
     "evaluate_panel_df",
     "evaluate_panel_with_entity_R",
-    "compute_cwsl_sensitivity_df",
-    "cwsl_sensitivity_df",
-    "estimate_entity_R_from_balance",
-    "hr_at_tau",
-    "estimate_tau",
-    "estimate_entity_tau",
-    "hr_auto_tau",
-    "TauEstimate",
+    "run_governance_workflow_df",
+    "run_governance_workflow_df_dict",
 ]

{eb_evaluation-0.2.3 → eb_evaluation-0.2.7}/src/eb_evaluation/adjustment/__init__.py

@@ -16,10 +16,12 @@ Key ideas
 Public API
 ----------
 - `ReadinessAdjustmentLayer`
+- `apply_ral`
 """
 
-from .readiness_adjustment import ReadinessAdjustmentLayer
+from .ral import ReadinessAdjustmentLayer, apply_ral
 
 __all__ = [
     "ReadinessAdjustmentLayer",
+    "apply_ral",
 ]

{eb_evaluation-0.2.3 → eb_evaluation-0.2.7}/src/eb_evaluation/adjustment/_utils.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Internal utilities for the Readiness Adjustment Layer.
 
@@ -8,17 +6,17 @@ implementation. These utilities are **not** part of the public API and may chang
 notice.
 
 The intent is to keep the main algorithm (and its public surface area) in
-`eb_evaluation.adjustment.readiness_adjustment` clean and readable.
+`eb_evaluation.adjustment.ral` clean and readable.
 """
 
+from __future__ import annotations
+
 from collections.abc import Callable, Sequence
-from typing import Any, Union, overload
 
 import numpy as np
 import pandas as pd
 
-
-ArrayLike = Union[np.ndarray, Sequence[float], pd.Series, pd.DataFrame]
+ArrayLike = np.ndarray | Sequence[float] | pd.Series | pd.DataFrame
 
 
 # ---------------------------------------------------------------------------
@@ -57,7 +55,7 @@ def validate_numeric_array(arr: ArrayLike, name: str = "array") -> np.ndarray:
     - This helper does *not* drop missing values. If you need filtering behavior, perform
       it upstream and call this only once the array should be clean.
     """
-    if isinstance(arr, (pd.Series, pd.DataFrame)):
+    if isinstance(arr, pd.Series | pd.DataFrame):
         arr = arr.to_numpy()
 
     out = np.asarray(arr, dtype=float)
@@ -105,15 +103,15 @@ def safe_mean(values: np.ndarray) -> float:
 # ---------------------------------------------------------------------------
 def groupby_apply_values(
     df: pd.DataFrame,
-    group_cols: Union[str, Sequence[str]],
+    group_cols: str | Sequence[str],
     value_col: str,
     func: Callable[[np.ndarray], float],
 ) -> pd.DataFrame:
     """Apply a numeric reducer to a column, grouped by one or more keys.
 
     This helper groups ``df`` by ``group_cols`` and applies ``func`` to the values of
-    ``value_col`` for each group. The function is called with a **validated**, finite
-    float array.
+    ``value_col`` for each group. The function is called with a validated, finite float
+    array.
 
     Parameters
     ----------