eb-features 0.1.0__py3-none-any.whl

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/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/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)}."
+        )

eb_features/panel/config.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+"""
+Configuration objects for panel time-series feature engineering.
+
+This module defines declarative configuration used by the panel feature engineering
+pipeline. The configuration is designed to be:
+
+- **frequency-agnostic** (lags/windows are expressed in index steps, not wall-clock time)
+- **stateless** (config describes what to compute; no fitted state is stored)
+- **explicit** (feature families are enabled/disabled via lists/flags)
+
+Notes
+-----
+This configuration is consumed by [`FeatureEngineer`][eb_features.panel.engineer.FeatureEngineer]
+and related helper modules (lags, rolling, calendar, encoders).
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Sequence, Tuple
+
+# -------------------------------------------------------------------------
+# Public constants (useful for validation, docs, and IDE discoverability)
+# -------------------------------------------------------------------------
+
+#: Allowed rolling statistics for rolling window features.
+ALLOWED_ROLLING_STATS: Tuple[str, ...] = ("mean", "std", "min", "max", "sum", "median")
+
+#: Allowed calendar feature keys derived from timestamps.
+ALLOWED_CALENDAR_FEATURES: Tuple[str, ...] = ("hour", "dow", "dom", "month", "is_weekend")
+
+
+@dataclass(frozen=True)
+class FeatureConfig:
+    r"""
+    Configuration for panel time-series feature engineering.
+
+    The feature engineering pipeline assumes a long-form panel DataFrame with an entity
+    identifier column, a timestamp column, and a numeric target column. This configuration
+    describes which feature families to generate and which passthrough columns to include.
+
+    Notes
+    -----
+    - Lag steps and rolling windows are expressed in **index steps** (rows) at the input
+      frequency, not in wall-clock units.
+    - Lags and rolling windows are computed **within each entity**.
+    - If ``dropna=True``, rows lacking sufficient lag/rolling history are dropped after
+      feature construction.
+
+    Attributes
+    ----------
+    lag_steps : Sequence[int] | None
+        Positive lag offsets (in steps) applied to the target. For each ``k`` in ``lag_steps``,
+        the feature ``lag_{k}`` is added.
+    rolling_windows : Sequence[int] | None
+        Positive rolling window lengths (in steps) applied to the target. For each ``w`` in
+        ``rolling_windows`` and each stat in ``rolling_stats``, the feature
+        ``roll_{w}_{stat}`` is added.
+    rolling_stats : Sequence[str]
+        Rolling statistics to compute. Allowed values are:
+        ``{"mean", "std", "min", "max", "sum", "median"}``.
+    calendar_features : Sequence[str]
+        Calendar features derived from the timestamp column. Allowed values are:
+        ``{"hour", "dow", "dom", "month", "is_weekend"}``.
+    use_cyclical_time : bool
+        If True, add sine/cosine encodings for hour and day-of-week when those base
+        calendar columns are present.
+    regressor_cols : Sequence[str] | None
+        Numeric external regressors to pass through. If None, numeric columns may be
+        auto-detected by the calling pipeline (excluding entity/timestamp/target and
+        ``static_cols``).
+    static_cols : Sequence[str] | None
+        Entity-level metadata columns already present on the input DataFrame. These are
+        passed through directly as features.
+    dropna : bool
+        If True, drop rows with NaNs in any engineered feature columns (typically caused
+        by lags and rolling windows).
+    """
+
+    lag_steps: Optional[Sequence[int]] = field(default_factory=lambda: (1, 2, 24))
+
+    rolling_windows: Optional[Sequence[int]] = field(default_factory=lambda: (3, 24))
+    rolling_stats: Sequence[str] = field(
+        default_factory=lambda: ("mean", "std", "min", "max", "sum")
+    )
+
+    calendar_features: Sequence[str] = field(
+        default_factory=lambda: ("hour", "dow", "month", "is_weekend")
+    )
+    use_cyclical_time: bool = True
+
+    regressor_cols: Optional[Sequence[str]] = None
+    static_cols: Optional[Sequence[str]] = None
+
+    dropna: bool = True

eb_features/panel/constants.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+"""
+Shared constants for panel feature engineering.
+
+This module centralizes small, stable configuration values used across the
+``eb_features.panel`` subpackage. Keeping these definitions in one place prevents
+validation drift between modules and provides a single reference point for both
+implementation and documentation.
+
+Notes
+-----
+- These constants are intentionally minimal and low-churn.
+- They define *allowed values*, *default configurations*, and *calendar parameters*
+  used consistently across feature builders.
+"""
+
+from typing import Final, FrozenSet, Tuple
+
+# -----------------------------------------------------------------------------
+# Allowed feature keys
+# -----------------------------------------------------------------------------
+ALLOWED_ROLLING_STATS: FrozenSet[str] = frozenset(
+    {"mean", "std", "min", "max", "sum", "median"}
+)
+"""
+Allowed rolling-window summary statistics.
+
+Each statistic corresponds to a feature name of the form:
+
+$$
+\mathrm{roll\_{w}\_{stat}}(t)
+$$
+
+where ``w`` is the window length (in index steps) and ``stat`` is one of the allowed values.
+"""
+
+
+ALLOWED_CALENDAR_FEATURES: FrozenSet[str] = frozenset(
+    {"hour", "dow", "dom", "month", "is_weekend"}
+)
+"""
+Allowed calendar features derived from the timestamp column.
+
+Calendar features are added as integer-valued columns and may optionally be accompanied by
+cyclical encodings (sine/cosine) for periodic components.
+"""
+
+# -----------------------------------------------------------------------------
+# Default configuration values (used by FeatureConfig)
+# -----------------------------------------------------------------------------
+DEFAULT_LAG_STEPS: Final[Tuple[int, ...]] = (1, 2, 24)
+
+DEFAULT_ROLLING_WINDOWS: Final[Tuple[int, ...]] = (3, 24)
+DEFAULT_ROLLING_STATS: Final[Tuple[str, ...]] = ("mean", "std", "min", "max", "sum")
+
+DEFAULT_CALENDAR_FEATURES: Final[Tuple[str, ...]] = (
+    "hour",
+    "dow",
+    "month",
+    "is_weekend",
+)
+
+# -----------------------------------------------------------------------------
+# Calendar / cyclical encoding parameters
+# -----------------------------------------------------------------------------
+HOUR_PERIOD: Final[int] = 24
+"""Period used for cyclical hour-of-day encodings."""
+
+DOW_PERIOD: Final[int] = 7
+"""Period used for cyclical day-of-week encodings."""
+
+# pandas dt.dayofweek convention: Monday=0 ... Sunday=6
+WEEKEND_DAYS: Final[Tuple[int, int]] = (5, 6)
+"""Day-of-week values corresponding to Saturday and Sunday."""

eb_features/panel/encoders.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+"""
+Encoding utilities for panel feature engineering.
+
+This module provides small, stateless helpers to make feature matrices numeric.
+
+Current scope
+-------------
+The panel feature engineering pipeline produces a feature frame that may contain
+a mixture of numeric and non-numeric columns (e.g., entity metadata strings).
+Many downstream estimators expect purely numeric arrays. The helper in this module
+encodes non-numeric columns using pandas categorical codes.
+
+Important
+---------
+Categorical codes are stable **only within the provided DataFrame**. Because this
+module is intentionally stateless (no fitted mapping is persisted), codes may differ
+between training and inference if category sets or ordering differ.
+
+For production modeling pipelines that require consistent encodings across datasets,
+consider:
+- pre-encoding categoricals upstream (one-hot, target encoding, etc.), or
+- introducing a fitted encoder with persisted category mappings.
+"""
+
+from typing import Iterable
+
+import pandas as pd
+from pandas.api.types import is_bool_dtype, is_numeric_dtype
+
+
+def encode_non_numeric_as_category_codes(
+    feature_frame: pd.DataFrame,
+    *,
+    columns: Iterable[str] | None = None,
+    dtype: str = "int32",
+) -> pd.DataFrame:
+    """
+    Encode non-numeric feature columns as categorical codes.
+
+    Parameters
+    ----------
+    feature_frame : pandas.DataFrame
+        Feature DataFrame whose columns will be encoded as needed.
+    columns : Iterable[str] | None, default None
+        Columns to consider for encoding. If None, all columns are considered.
+    dtype : str, default "int32"
+        Output dtype for encoded columns. (Booleans are converted to 0/1 and cast
+        to this dtype; categorical codes are integers cast to this dtype.)
+
+    Returns
+    -------
+    pandas.DataFrame
+        Copy of ``feature_frame`` where:
+        - boolean columns are converted to {0,1}
+        - non-numeric, non-boolean columns are replaced by categorical integer codes
+
+    Notes
+    -----
+    - Missing values in non-numeric columns are assigned the code ``-1`` by pandas.
+    - Category ordering is made deterministic by sorting observed values by their
+      string representation before assigning codes.
+    """
+    df = feature_frame.copy()
+    selected = list(df.columns) if columns is None else list(columns)
+
+    missing = [c for c in selected if c not in df.columns]
+    if missing:
+        raise KeyError(f"Columns not found in feature_frame: {missing}.")
+
+    for col in selected:
+        s = df[col]
+
+        # Convert booleans to 0/1 (numeric), for a clean numeric feature matrix.
+        if is_bool_dtype(s):
+            df[col] = s.astype("int8").astype(dtype)
+            continue
+
+        # Leave numeric columns unchanged.
+        if is_numeric_dtype(s):
+            continue
+
+        # Deterministic category ordering for a given input DataFrame.
+        observed = s.dropna().unique().tolist()
+        categories = sorted(observed, key=lambda x: str(x))
+
+        cat = pd.Categorical(s, categories=categories, ordered=False)
+        df[col] = cat.codes.astype(dtype)
+
+    return df