Metadata-Version: 2.4
Name: eb-features
Version: 0.2.7
Summary: Feature engineering utilities for panel time-series data in the Electric Barometer ecosystem.
Author-email: "Kyle Corrie (Economistician)" <kcorrie@economistician.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/Economistician/eb-features
Project-URL: Repository, https://github.com/Economistician/eb-features
Project-URL: Issues, https://github.com/Economistician/eb-features/issues
Project-URL: Documentation, https://economistician.github.io/eb-docs/
Keywords: forecasting,features,feature-engineering,time-series,panel-data,operations-research
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
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: all
Requires-Dist: pytest>=8.0; extra == "all"
Requires-Dist: pytest-cov>=5.0; extra == "all"
Dynamic: license-file

# Electric Barometer · Features (`eb-features`)

[![CI](https://github.com/Economistician/eb-features/actions/workflows/ci.yml/badge.svg)](https://github.com/Economistician/eb-features/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-features)
![PyPI](https://img.shields.io/pypi/v/eb-features)

Feature engineering primitives for panel-based forecasting systems, designed to integrate seamlessly with the Electric Barometer ecosystem.

---

## Overview

`eb-features` builds deterministic, panel-aware forecasting features (lags, rolling aggregates, calendar encodings) with explicit entity and time boundaries. It does not train models or evaluate forecasts.

---

## Installation

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

```bash
pip install eb-features
```

The package supports Python 3.11 and later.

---

## Core Concepts

- **Panel-aware feature construction** — Features are constructed with explicit awareness of entity boundaries and temporal ordering, ensuring correctness in multi-entity forecasting settings.
- **Deterministic transformations** — Feature generation is designed to be reproducible and free of stochastic behavior, supporting auditability and consistent downstream evaluation.
- **Temporal causality** — All features respect time directionality, preventing information leakage from future observations into historical feature sets.
- **Rolling and lag semantics** — Common forecasting features such as lags and rolling aggregates are treated as first-class primitives with clear, well-defined behavior.
- **Validation by construction** — Feature pipelines include explicit checks and constraints to ensure structural validity before model training or evaluation.

---

## Minimal Example

The example below shows how to construct lagged and rolling features for panel data while preserving entity boundaries and temporal ordering.

```python
import pandas as pd
from eb_features import add_lag_features, add_rolling_features

df = pd.DataFrame({
    "entity_id": ["A", "A", "A", "A", "B", "B", "B", "B"],
    "date": pd.to_datetime(
        ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04"] * 2
    ),
    "y": [10, 12, 11, 13, 7, 9, 8, 10],
})
df = df.sort_values(["entity_id", "date"], kind="mergesort")

df, lag_cols = add_lag_features(
    df,
    entity_col="entity_id",
    target_col="y",
    lag_steps=[1, 2],
)

df, roll_cols = add_rolling_features(
    df,
    entity_col="entity_id",
    target_col="y",
    rolling_windows=[3],
    rolling_stats=["mean"],
)

print(lag_cols, roll_cols)
print(df)
```

---

## License

BSD 3-Clause License.
© 2026 Kyle Corrie.

<!-- Trusted publishing verification -->
