eb-features 0.1.0__tar.gz

eb_features-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Kyle Corrie
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

eb_features-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+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.

eb_features-0.1.0/README.md

@@ -0,0 +1,137 @@
+# 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.

eb_features-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "eb-features"
+version = "0.1.0"
+description = "Feature engineering utilities for panel time-series data in the Electric Barometer ecosystem."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+license-files = ["LICENSE*"]
+
+authors = [
+  { name = "Kyle Corrie (Economistician)", email = "kcorrie@economistician.com" }
+]
+
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+]
+
+keywords = ["forecasting", "features", "feature-engineering", "time-series", "panel-data", "operations-research"]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://github.com/Economistician/eb-features"
+Repository = "https://github.com/Economistician/eb-features"
+Issues = "https://github.com/Economistician/eb-features/issues"
+Documentation = "https://economistician.github.io/eb-docs/"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+]
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"
+testpaths = ["tests"]

eb_features-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eb_features-0.1.0/src/eb_features/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+"""
+Feature engineering utilities for the Electric Barometer ecosystem.
+
+This package provides modular, domain-agnostic feature engineering components
+used across forecasting, evaluation, and operational modeling workflows.
+
+Subpackages
+-----------
+panel
+    Feature engineering utilities for panel (entity × timestamp) time-series data.
+
+Notes
+-----
+This package intentionally exposes a small public API. Most functionality is
+accessed through subpackages such as `eb_features.panel`.
+"""
+
+__all__ = []

eb_features-0.1.0/src/eb_features/panel/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+"""
+Panel time-series feature engineering.
+
+This subpackage provides lightweight, frequency-agnostic feature engineering utilities
+for *panel* time-series data, i.e., data indexed by:
+
+- an **entity** identifier (store, SKU, customer, sensor, etc.), and
+- a **timestamp** column
+
+The primary public interface is:
+
+- [`FeatureConfig`][eb_features.panel.engineering.FeatureConfig]: declarative feature configuration
+- [`FeatureEngineer`][eb_features.panel.engineering.FeatureEngineer]: stateless transformer that
+  produces a model-ready ``(X, y, feature_names)`` triple from a long-form DataFrame.
+
+Design goals
+------------
+- **Stateless**: no fit/transform lifecycle; features are generated deterministically from inputs.
+- **Frequency-agnostic**: lags and rolling windows are expressed in index steps, not wall-clock units.
+- **Leakage-aware**: feature construction is intended to use only information available at or
+  before prediction time (depending on configuration and implementation details).
+
+Notes
+-----
+This subpackage is intentionally conservative in scope. It focuses on producing features suitable
+for classical supervised learning pipelines (tree models, linear models, shallow neural nets) that
+expect a fixed-width design matrix.
+
+See Also
+--------
+- [`eb_features.panel.engineering.FeatureEngineer`][eb_features.panel.engineering.FeatureEngineer]
+- [`eb_features.panel.engineering.FeatureConfig`][eb_features.panel.engineering.FeatureConfig]
+"""
+
+from eb_features.panel.engineering import FeatureConfig, FeatureEngineer
+
+__all__ = [
+    "FeatureConfig",
+    "FeatureEngineer",
+]

eb_features-0.1.0/src/eb_features/panel/calendar.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+"""
+Calendar and time-derived features for panel time series.
+
+This module provides utilities to derive calendar/time features from a timestamp column.
+It is designed for *panel* time-series data (entity × timestamp) and is typically used
+as part of a broader feature engineering pipeline.
+
+Supported base calendar features
+--------------------------------
+Given a timestamp column ``timestamp_col``:
+
+- ``"hour"``: Hour of day in ``[0, 23]``
+- ``"dow"``: Day of week in ``[0, 6]`` where Monday=0 (pandas convention)
+- ``"dom"``: Day of month in ``[1, 31]``
+- ``"month"``: Month in ``[1, 12]``
+- ``"is_weekend"``: Weekend indicator (Saturday/Sunday) as ``0/1``
+
+Optional cyclical encodings
+---------------------------
+Certain calendar attributes are periodic and can be represented with sine/cosine pairs:
+
+- hour (period 24):
+
+$$
+\sin\left(2\pi \frac{\mathrm{hour}}{24}\right),\quad
+\cos\left(2\pi \frac{\mathrm{hour}}{24}\right)
+$$
+
+- day of week (period 7):
+
+$$
+\sin\left(2\pi \frac{\mathrm{dow}}{7}\right),\quad
+\cos\left(2\pi \frac{\mathrm{dow}}{7}\right)
+$$
+
+These encodings are added only when:
+- the corresponding base feature (hour or dow) is present, and
+- ``use_cyclical_time=True``.
+
+Notes
+-----
+- Feature construction is *stateless*: functions operate only on the provided DataFrame.
+- Time features are derived from ``pandas.to_datetime`` conversion of ``timestamp_col``.
+  Timezone-aware timestamps are supported; feature values reflect the timestamp's local
+  representation as stored in the column.
+"""
+
+from typing import Iterable, List, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+
+from eb_features.panel.constants import (
+    ALLOWED_CALENDAR_FEATURES,
+    DOW_PERIOD,
+    HOUR_PERIOD,
+    WEEKEND_DAYS,
+)
+
+
+def add_calendar_features(
+    df: pd.DataFrame,
+    *,
+    timestamp_col: str,
+    calendar_features: Sequence[str],
+    use_cyclical_time: bool = True,
+) -> Tuple[pd.DataFrame, List[str], List[str]]:
+    r"""
+    Add calendar/time-derived features to a DataFrame.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Input DataFrame containing a timestamp column.
+    timestamp_col : str
+        Name of the timestamp column.
+    calendar_features : Sequence[str]
+        Base calendar features to derive. Allowed values are:
+        ``{"hour", "dow", "dom", "month", "is_weekend"}``.
+    use_cyclical_time : bool, default True
+        If True, add sine/cosine encodings for hour and/or day-of-week when those
+        base features are included.
+
+    Returns
+    -------
+    df_out : pandas.DataFrame
+        Copy of ``df`` with the requested calendar features added as columns.
+    feature_cols : list[str]
+        Names of all features added by this call, including cyclical encodings (if any).
+    calendar_cols : list[str]
+        Names of base calendar feature columns added (excludes cyclical encodings).
+
+    Raises
+    ------
+    KeyError
+        If ``timestamp_col`` is not present in ``df``.
+    ValueError
+        If an unsupported calendar feature is requested.
+
+    Notes
+    -----
+    The derived columns are currently named:
+
+    - ``hour``
+    - ``dayofweek`` (for requested ``"dow"``)
+    - ``dayofmonth`` (for requested ``"dom"``)
+    - ``month``
+    - ``is_weekend``
+
+    This naming is stable and intended to be referenced by downstream steps.
+    """
+    if timestamp_col not in df.columns:
+        raise KeyError(f"Timestamp column {timestamp_col!r} not found in DataFrame.")
+
+    _validate_calendar_features(calendar_features)
+
+    df_out = df.copy()
+    ts = pd.to_datetime(df_out[timestamp_col])
+
+    calendar_cols: List[str] = []
+    feature_cols: List[str] = []
+
+    for name in calendar_features:
+        if name == "hour":
+            col = "hour"
+            df_out[col] = ts.dt.hour.astype("int16")
+            calendar_cols.append(col)
+        elif name == "dow":
+            col = "dayofweek"
+            df_out[col] = ts.dt.dayofweek.astype("int16")
+            calendar_cols.append(col)
+        elif name == "dom":
+            col = "dayofmonth"
+            df_out[col] = ts.dt.day.astype("int16")
+            calendar_cols.append(col)
+        elif name == "month":
+            col = "month"
+            df_out[col] = ts.dt.month.astype("int16")
+            calendar_cols.append(col)
+        elif name == "is_weekend":
+            col = "is_weekend"
+            df_out[col] = ts.dt.dayofweek.isin(WEEKEND_DAYS).astype("int8")
+            calendar_cols.append(col)
+        else:  # pragma: no cover
+            # Guarded by _validate_calendar_features, but keep a defensive fallback.
+            raise ValueError(
+                f"Unsupported calendar feature {name!r}. Allowed: {sorted(ALLOWED_CALENDAR_FEATURES)}."
+            )
+
+    feature_cols.extend(calendar_cols)
+
+    # ---------------------------------------------------------------------
+    # Optional cyclical encodings
+    # ---------------------------------------------------------------------
+    if use_cyclical_time:
+        if "hour" in calendar_cols:
+            hour = df_out["hour"].astype(float)
+            df_out["hour_sin"] = np.sin(2.0 * np.pi * hour / float(HOUR_PERIOD))
+            df_out["hour_cos"] = np.cos(2.0 * np.pi * hour / float(HOUR_PERIOD))
+            feature_cols.extend(["hour_sin", "hour_cos"])
+
+        if "dayofweek" in calendar_cols:
+            dow = df_out["dayofweek"].astype(float)
+            df_out["dow_sin"] = np.sin(2.0 * np.pi * dow / float(DOW_PERIOD))
+            df_out["dow_cos"] = np.cos(2.0 * np.pi * dow / float(DOW_PERIOD))
+            feature_cols.extend(["dow_sin", "dow_cos"])
+
+    return df_out, feature_cols, calendar_cols
+
+
+def _validate_calendar_features(calendar_features: Iterable[str]) -> None:
+    r"""
+    Validate that requested calendar features are supported.
+
+    Parameters
+    ----------
+    calendar_features : Iterable[str]
+        Candidate calendar feature keys.
+
+    Raises
+    ------
+    ValueError
+        If any feature key is unsupported.
+    """
+    requested = list(calendar_features)
+    invalid = [f for f in requested if f not in ALLOWED_CALENDAR_FEATURES]
+    if invalid:
+        raise ValueError(
+            "Unsupported calendar feature(s) requested: "
+            f"{invalid}. Allowed: {sorted(ALLOWED_CALENDAR_FEATURES)}."
+        )