Metadata-Version: 2.4
Name: eb-features
Version: 0.1.0
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 :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# Electric barometer Feature Engineering (`eb-features`)

**eb-features** is the feature engineering layer of the **Electric Barometer** ecosystem.

It provides a structured, opinionated set of **panel-aware feature construction utilities**
for time-series modeling in operational environments—contexts where *temporal structure*,
*entity boundaries*, and *leakage safety* matter as much as model choice itself.

This package focuses on **deterministic, stateless feature generation** for classical
supervised learning pipelines, producing clean, model-ready design matrices from
long-form panel data.

---

## Naming convention

Electric Barometer packages follow a consistent naming convention:

- **Distribution names** (used with `pip install`) use hyphens  
  e.g. `pip install eb-features`
- **Python import paths** use underscores  
  e.g. `import eb_features`

This follows standard Python packaging practices and avoids ambiguity between
package names and module imports.

---

## What this package provides

### Panel-safe lag features
Lagged versions of the target series constructed **strictly within entity** boundaries.

- Configurable lag steps (index-based, frequency-agnostic)
- Deterministic naming (`lag_1`, `lag_24`, etc.)
- Explicit handling of missing history

---

### Leakage-aware rolling statistics
Rolling-window summaries designed for forecasting workflows.

- Mean, sum, min, max, std, median
- Configurable window sizes
- **Leakage-safe by default** (excludes current target value)
- Optional early availability via `min_periods`

---

### Calendar and time-derived features
Calendar attributes derived from timestamp columns.

- Hour, day-of-week, day-of-month, month
- Weekend indicators
- Optional cyclical encodings (sine/cosine) for periodic components
- Timezone-aware timestamp support

---

### Passthrough regressors and static features
Support for mixing engineered temporal features with:

- Numeric external regressors
- Static entity-level metadata
- Automatic regressor detection when not explicitly specified

Non-numeric passthrough columns are encoded using stable, dataset-local
categorical codes.

---

### Validation and guardrails
Built-in validation to catch common modeling errors early.

- Required-column checks
- Strict monotonic timestamp enforcement within entity
- Protection against cross-entity leakage
- Non-finite value detection before model handoff

---

## Design principles

`eb-features` is intentionally:

- **Stateless** — no fitted encoders or persisted mappings  
- **Deterministic** — same input + config → same output  
- **Frequency-agnostic** — works with hourly, daily, or irregular data  
- **Panel-aware** — entity boundaries are first-class constraints  

This makes it suitable for batch modeling, experimentation, and reproducible
forecast evaluation pipelines.

---

## Documentation structure

- **API Reference**  
  All feature builders and utilities are documented automatically from
  NumPy-style docstrings using `mkdocstrings`.

Conceptual motivation and modeling guidance for these features live in the
companion repositories:

- **eb-metrics** — operationally meaningful forecast metrics  
- **eb-evaluation** — structured forecast evaluation workflows  
- **eb-papers** — formal definitions and technical notes  

---

## Intended audience

This package is intended for:

- data scientists and applied ML practitioners
- forecasting and demand-planning teams
- operations and service analytics engineers
- researchers working with panel time-series data

The emphasis throughout is on **correct feature construction under operational
constraints**, not generic time-series convenience.

---

## Relationship to the Electric Barometer framework

`eb-features` provides the **feature engineering layer** of the Electric Barometer
ecosystem.

It is designed to work in concert with:

- **eb-metrics** — how forecasts are evaluated  
- **eb-evaluation** — how forecasts are compared and selected  
- **eb-adapters** — how forecasts integrate with external systems  

Together, these components support a disciplined, end-to-end approach to
*forecast readiness*—from raw data, to features, to evaluation.
