Metadata-Version: 2.4
Name: eb-evaluation
Version: 0.2.10
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
Project-URL: Homepage, https://github.com/Economistician/eb-evaluation
Project-URL: Repository, https://github.com/Economistician/eb-evaluation
Project-URL: Issues, https://github.com/Economistician/eb-evaluation/issues
Project-URL: Documentation, https://github.com/Economistician/eb-docs
Keywords: electric-barometer,forecast-evaluation,asymmetric-loss,readiness,forecasting,pandas
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
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.2.9
Requires-Dist: eb-adapters==0.2.5
Provides-Extra: test
Requires-Dist: pytest>=8.0; 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`)

[![CI](https://github.com/Economistician/eb-evaluation/actions/workflows/ci.yml/badge.svg)](https://github.com/Economistician/eb-evaluation/actions/workflows/ci.yml)
![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
![Python Versions](https://img.shields.io/pypi/pyversions/eb-evaluation)
![PyPI](https://img.shields.io/pypi/v/eb-evaluation)

Evaluation and model selection utilities for applying Electric Barometer metrics across entities, groups, and operational contexts.

---

## Overview

`eb-evaluation` applies Electric Barometer metrics across entities, groups, and hierarchies with DataFrame-first workflows, diagnostics, and cost-aware model selection. Metric primitives live in `eb-metrics`; feature construction and model adapters live elsewhere.

---

## Installation

`eb-evaluation` is distributed as a standard Python package.

```bash
pip install eb-evaluation
```

The package supports Python 3.11 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 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 as reflected in evaluation metrics, not just aggregate accuracy, supporting decision-aligned forecasting workflows.

---

## Minimal Example

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 import compute_cwsl_df, evaluate_groups_df

df = pd.DataFrame({
    "entity_id": ["A", "A", "B", "B"],
    "actual": [10, 12, 7, 9],
    "prediction": [9, 11, 8, 10],
})

# Single-slice CWSL (scalar)
loss = compute_cwsl_df(
    df,
    y_true_col="actual",
    y_pred_col="prediction",
    cu=2.0,
    co=1.0,
)

# Per-entity metrics, including FRS (requires cwsl_max)
results = evaluate_groups_df(
    df,
    group_cols=["entity_id"],
    actual_col="actual",
    forecast_col="prediction",
    cu=2.0,
    co=1.0,
    cwsl_max=0.30,
)

print(loss)
print(results)
```

---

## License

BSD 3-Clause License.
© 2026 Kyle Corrie.
