felits 0.1.0__py3-none-any.whl

felits/__init__.py

@@ -0,0 +1,161 @@
+"""FELITS: Feature Engineering and Large-scale Integration for Time Series.
+
+Top-level package exposing the most commonly used classes and functions
+through a flat, ergonomic API::
+
+    from felits import (
+        HampelFilter, TimeSeriesScaler, SlidingWindowSplitter, Metrics,
+        cyclical_encode, fft_features, tsfresh_extract,
+        FeatureSelector, granger_feature_selection, shap_feature_selection,
+        XGBoostForecaster, RandomForestForecaster, RNNBasedModel,
+        OptunaOptimizer, deep_shap_selector,
+    )
+
+Submodules are still importable for advanced use::
+
+    from felits.preprocessing import iqr_outlier_detection
+    from felits.feature_selection import mrmr_selection
+"""
+
+from __future__ import annotations
+
+from . import data, models, optimization
+from .feature_extraction import (
+    cyclical_encode,
+    extract_all_features,
+    fats_extract,
+    fft_features,
+    lag_features,
+    rolling_statistics,
+    shift_features,
+    spectral_entropy,
+    tsfresh_extract,
+    wavelet_features,
+)
+from .feature_selection import (
+    FeatureSelector,
+    adaptive_lasso_selection,
+    elastic_net_selection,
+    granger_feature_selection,
+    lasso_selection,
+    lime_explain_instance,
+    mrmr_selection,
+    mutual_information_ksg,
+    permutation_importance_selection,
+    rf_importance_selection,
+    select_features,
+    shap_feature_selection,
+    shap_interaction_selection,
+    xgboost_importance_selection,
+)
+from .optimization import OptunaOptimizer
+from .preprocessing import (
+    DecompositionResult,
+    HampelFilter,
+    Metrics,
+    SlidingWindowSplitter,
+    TimeSeriesScaler,
+    forward_fill,
+    hampel_filter,
+    iqr_outlier_detection,
+    linear_interpolate,
+    mae,
+    mape,
+    max_error,
+    mse,
+    r2,
+    rmse,
+    seasonal_adjust,
+    smape,
+    stl_decompose,
+    three_sigma_filter,
+    time_aware_interpolate,
+)
+from .xai import deep_shap_selector, explain_forecast
+
+__version__ = "0.1.0"
+__author__ = "Félix Morales Mareco"
+__license__ = "MIT"
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+    # data
+    "data",
+    "models",
+    "optimization",
+    # preprocessing
+    "DecompositionResult",
+    "HampelFilter",
+    "Metrics",
+    "SlidingWindowSplitter",
+    "TimeSeriesScaler",
+    "forward_fill",
+    "hampel_filter",
+    "iqr_outlier_detection",
+    "linear_interpolate",
+    "mae",
+    "mape",
+    "max_error",
+    "mse",
+    "r2",
+    "rmse",
+    "seasonal_adjust",
+    "smape",
+    "stl_decompose",
+    "three_sigma_filter",
+    "time_aware_interpolate",
+    # feature_extraction
+    "cyclical_encode",
+    "extract_all_features",
+    "fats_extract",
+    "fft_features",
+    "lag_features",
+    "rolling_statistics",
+    "shift_features",
+    "spectral_entropy",
+    "tsfresh_extract",
+    "wavelet_features",
+    # feature_selection
+    "FeatureSelector",
+    "adaptive_lasso_selection",
+    "elastic_net_selection",
+    "granger_feature_selection",
+    "lasso_selection",
+    "lime_explain_instance",
+    "mrmr_selection",
+    "mutual_information_ksg",
+    "permutation_importance_selection",
+    "rf_importance_selection",
+    "select_features",
+    "shap_feature_selection",
+    "shap_interaction_selection",
+    "xgboost_importance_selection",
+    # optimization
+    "OptunaOptimizer",
+    # xai
+    "deep_shap_selector",
+    "explain_forecast",
+]
+
+# Re-export the DL models and sklearn forecasters at the top level
+from .models import (
+    BahdanauAttention,
+    LinearForecaster,
+    RandomForestForecaster,
+    RNNAttentionModel,
+    RNNBasedModel,
+    XGBoostForecaster,
+    is_dl_available,
+)
+
+__all__ += [
+    "BahdanauAttention",
+    "LinearForecaster",
+    "RNNAttentionModel",
+    "RNNBasedModel",
+    "RandomForestForecaster",
+    "XGBoostForecaster",
+    "is_dl_available",
+]

felits/_compat.py

@@ -0,0 +1,173 @@
+"""Compatibility layer for dual pandas / polars support.
+
+FELITS accepts both ``pd.DataFrame`` and ``pl.DataFrame`` (or a mix of both)
+at all public APIs. Internally the library works with :class:`polars.DataFrame`
+for performance. Conversion to pandas happens only at library boundaries
+(e.g. ``statsmodels``, ``tsfresh``) that require it.
+
+Usage
+-----
+>>> from felits._compat import to_polars, to_pandas, DataFrameLike
+>>>
+>>> def my_public_api(df: DataFrameLike, target: str):
+...     pdf = to_polars(df)          # guarantee polars
+...     result = pdf.select(pl.col(target))
+...     return to_pandas(result)     # back to pandas for the caller
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Union
+
+import numpy as np
+
+if TYPE_CHECKING:
+    import pandas as pd
+    import polars as pl
+
+DataFrameLike = Union["pd.DataFrame", "pl.DataFrame"]
+SeriesLike = Union["pd.Series", "pl.Series"]
+
+
+def to_polars(data: object, *columns: str, include_index: bool = False) -> "pl.DataFrame":
+    """Convert ``data`` to a :class:`polars.DataFrame`.
+
+    Parameters
+    ----------
+    include_index:
+        When ``True`` and ``data`` is a pandas DataFrame with a DatetimeIndex,
+        the index is included as the first column named ``"_time"``.
+    """
+    import polars as pl
+
+    if isinstance(data, pl.DataFrame):
+        return data
+    if isinstance(data, pl.Series):
+        return data.to_frame()
+    if isinstance(data, str):
+        raise TypeError(f"Cannot convert str to polars DataFrame: {data!r}")
+
+    import pandas as pd
+
+    if isinstance(data, pd.DataFrame):
+        if include_index and isinstance(data.index, pd.DatetimeIndex):
+            pdf = pl.from_pandas(data.reset_index())
+            idx_name = data.index.name or "_time"
+            if pdf.columns[0] == "index":
+                pdf = pdf.rename({"index": idx_name})
+            return pdf
+        return pl.from_pandas(data)
+    if isinstance(data, pd.Series):
+        return pl.from_pandas(data.to_frame())
+    if isinstance(data, np.ndarray):
+        if data.ndim == 1:
+            data = data.reshape(-1, 1)
+        if columns:
+            return pl.DataFrame({name: data[:, i] for i, name in enumerate(columns)})
+        return pl.DataFrame({f"col_{i}": data[:, i] for i in range(data.shape[1])})
+    if isinstance(data, dict):
+        return pl.DataFrame(data)
+    raise TypeError(f"Cannot convert {type(data).__name__} to polars DataFrame.")
+
+
+def to_pandas(data: object) -> "pd.DataFrame":
+    """Convert ``data`` to a :class:`pandas.DataFrame`.
+
+    Accepts:
+    - :class:`pandas.DataFrame` → returned unchanged
+    - :class:`polars.DataFrame` → converted via ``pl.to_pandas``
+    - :class:`polars.Series` → converted via ``pl.Series.to_pandas()``
+    """
+    import pandas as pd
+
+    if isinstance(data, pd.DataFrame):
+        return data
+    if isinstance(data, pd.Series):
+        return data.to_frame()
+
+    import polars as pl
+
+    if isinstance(data, pl.DataFrame):
+        return data.to_pandas()
+    if isinstance(data, pl.Series):
+        return data.to_pandas().to_frame()
+    if isinstance(data, np.ndarray):
+        cols = [f"col_{i}" for i in range(data.shape[1])] if data.ndim > 1 else ["value"]
+        return pd.DataFrame(data, columns=cols)
+    raise TypeError(f"Cannot convert {type(data).__name__} to pandas DataFrame.")
+
+
+def is_polars(data: object) -> bool:
+    """Check if ``data`` is a polars DataFrame/Series."""
+    try:
+        import polars as pl
+
+        return isinstance(data, (pl.DataFrame, pl.Series))
+    except ImportError:
+        return False
+
+
+def is_pandas(data: object) -> bool:
+    """Check if ``data`` is a pandas DataFrame/Series."""
+    try:
+        import pandas as pd
+
+        return isinstance(data, (pd.DataFrame, pd.Series))
+    except ImportError:
+        return False
+
+
+def to_numpy(data: object) -> np.ndarray:
+    """Convert DataFrame/Series to numpy, regardless of backend."""
+    if isinstance(data, np.ndarray):
+        return data
+    if hasattr(data, "to_numpy"):
+        return data.to_numpy()
+    return np.asarray(data, dtype=float)
+
+
+def with_columns(data: "pl.DataFrame", **kwargs: object) -> "pl.DataFrame":
+    """Add or replace columns in a polars DataFrame.
+
+    Equivalent to ``pandas``' ``df[col] = values`` pattern.
+    """
+    import polars as pl
+
+    for name, value in kwargs.items():
+        if isinstance(value, (list, np.ndarray)):
+            data = data.with_columns(pl.Series(name, value).alias(name))
+        elif isinstance(value, pl.Expr):
+            data = data.with_columns(value.alias(name))
+        elif isinstance(value, (int, float, str)):
+            data = data.with_columns(pl.lit(value).alias(name))
+        else:
+            raise TypeError(f"Unsupported column type: {type(value).__name__}")
+    return data
+
+
+def has_datetime_column(df: "pl.DataFrame") -> bool:
+    """Check if a polars DataFrame has any datetime or date column."""
+    import polars as pl
+
+    return any(
+        s in (pl.Datetime, pl.Date, pl.Datetime("ms", "UTC"), pl.Datetime("us", "UTC"))
+        for s in df.schema.values()
+    )
+
+
+def datetime_columns(df: "pl.DataFrame") -> list[str]:
+    """Return names of columns with datetime/date dtype."""
+    import polars as pl
+
+    valid = (pl.Datetime, pl.Date, pl.Datetime("ms", "UTC"), pl.Datetime("us", "UTC"))
+    return [c for c, t in df.schema.items() if t in valid]
+
+
+def is_pandas_datetime_index(df) -> bool:
+    """Check if df is a pandas DataFrame with a DatetimeIndex."""
+    try:
+        import pandas as pd
+
+        return isinstance(df, pd.DataFrame) and isinstance(df.index, pd.DatetimeIndex)
+    except ImportError:
+        return False

felits/data.py

@@ -0,0 +1,89 @@
+"""Data loaders and synthetic time-series generators.
+
+The module exposes:
+
+- :func:`load_example_dataset` — small CSV datasets bundled with FELITS
+  for demos and unit tests.
+- :func:`make_synthetic_ts` — reproducible synthetic univariate time
+  series with optional seasonality / noise.
+- :func:`load_sin_data` — convenience loader for the Paraguay SIN
+  dataset, used in the original research article. The function
+  gracefully returns ``None`` when the file is not present so the test
+  suite is not bound to a particular machine.
+"""
+
+from __future__ import annotations
+
+import os
+
+import numpy as np
+import pandas as pd
+
+__all__ = ["load_example_dataset", "load_sin_data", "make_synthetic_ts"]
+
+
+def make_synthetic_ts(
+    n_samples: int = 1000,
+    n_features: int = 1,
+    seasonality: bool = True,
+    period: int = 24,
+    noise_std: float = 0.1,
+    seed: int = 0,
+) -> pd.DataFrame:
+    """Generate a synthetic time series with daily seasonality.
+
+    Parameters
+    ----------
+    n_samples:
+        Number of rows.
+    n_features:
+        Number of exogenous feature columns (named ``"x0"``, ``"x1"``…).
+    seasonality:
+        Add a sinusoidal seasonal component to the target.
+    period:
+        Period of the seasonal component.
+    noise_std:
+        Standard deviation of the additive Gaussian noise.
+    seed:
+        Random seed for reproducibility.
+    """
+    rng = np.random.default_rng(seed)
+    t = np.arange(n_samples)
+    y = np.zeros(n_samples)
+    if seasonality:
+        y = 10 * np.sin(2 * np.pi * t / period) + 5 * np.cos(2 * np.pi * t / (period * 7))
+    y += noise_std * rng.standard_normal(n_samples)
+    df = pd.DataFrame({"y": y}, index=pd.date_range("2024-01-01", periods=n_samples, freq="h"))
+    for i in range(n_features):
+        df[f"x{i}"] = rng.standard_normal(n_samples)
+    return df
+
+
+def load_example_dataset(name: str = "synthetic_demand") -> pd.DataFrame:
+    """Load one of the small example datasets bundled with FELITS.
+
+    The default ``"synthetic_demand"`` is generated on the fly by
+    :func:`make_synthetic_ts` so users can run the quickstart without
+    any external files.
+    """
+    if name == "synthetic_demand":
+        return make_synthetic_ts(n_samples=24 * 30)
+    raise ValueError(f"Unknown example dataset {name!r}.")
+
+
+def load_sin_data(path: str | None = None) -> pd.DataFrame | None:
+    """Load the Paraguay SIN electricity-demand dataset.
+
+    The function looks for a CSV file at ``path`` or, when ``path`` is
+    ``None``, in the conventional ``dataset/processed_dataset.csv``
+    location relative to the current working directory. When no file is
+    found it returns ``None`` rather than raising, so that the test suite
+    is environment-agnostic.
+    """
+    if path is None:
+        path = os.path.join("dataset", "processed_dataset.csv")
+    if not os.path.isfile(path):
+        return None
+    df = pd.read_csv(path, index_col="Date")
+    df.index = pd.to_datetime(df.index)
+    return df

felits/feature_extraction/__init__.py

@@ -0,0 +1,21 @@
+"""Feature engineering for time series."""
+
+from __future__ import annotations
+
+from .automated import extract_all_features, fats_extract, tsfresh_extract
+from .spectral import fft_features, spectral_entropy, wavelet_features, welch_psd
+from .temporal import cyclical_encode, lag_features, rolling_statistics, shift_features
+
+__all__ = [
+    "cyclical_encode",
+    "extract_all_features",
+    "fats_extract",
+    "fft_features",
+    "lag_features",
+    "rolling_statistics",
+    "shift_features",
+    "spectral_entropy",
+    "tsfresh_extract",
+    "wavelet_features",
+    "welch_psd",
+]

felits/feature_extraction/automated.py

@@ -0,0 +1,142 @@
+"""Automated feature-extraction backends (FATS, tsfresh)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+from scipy import stats as _stats
+
+from .._compat import datetime_columns, is_pandas_datetime_index, to_polars
+
+__all__ = [
+    "tsfresh_extract",
+    "fats_extract",
+    "extract_all_features",
+]
+
+
+def tsfresh_extract(
+    df,
+    column_id: str,
+    column_sort: str,
+    target: Optional[np.ndarray] = None,
+    default_fc_parameters: Optional[dict | object] = None,
+    n_jobs: int = 0,
+    disable_progressbar: bool = True,
+):
+    """Run tsfresh feature extraction (requires pandas DataFrame internally)."""
+    try:
+        from tsfresh import extract_features as _tsf_extract
+        from tsfresh import select_features as _tsf_select
+        from tsfresh.feature_extraction import MinimalFCParameters
+    except ImportError as exc:
+        raise ImportError("tsfresh_extract requires tsfresh.") from exc
+
+    pdf = to_polars(df)
+    pandas_df = pdf.to_pandas()
+
+    if default_fc_parameters is None:
+        default_fc_parameters = MinimalFCParameters()
+    features = _tsf_extract(
+        pandas_df,
+        column_id=column_id,
+        column_sort=column_sort,
+        default_fc_parameters=default_fc_parameters,
+        n_jobs=n_jobs,
+        disable_progressbar=disable_progressbar,
+    )
+    if target is not None:
+        unique_ids = pandas_df[column_id].unique()
+        target_aligned = (
+            target.loc[unique_ids] if hasattr(target, "loc") else target[: len(unique_ids)]
+        )
+        features = _tsf_select(features, target_aligned)
+    return to_polars(features) if not isinstance(features, type(pdf)) else features
+
+
+def fats_extract(series, n_periods: int = 1) -> dict[str, float]:
+    """Compute FATS-style scalar features on a 1-D series."""
+    arr = np.asarray(series, dtype=float).ravel()
+    arr = arr[np.isfinite(arr)]
+    if arr.size < 4:
+        return {
+            k: float("nan")
+            for k in [
+                "amplitude",
+                "beyond_1_std",
+                "beyond_2_std",
+                "car_sigma",
+                "car_mean",
+                "car_std",
+                "skew",
+                "kurtosis",
+                "median_abs_dev",
+            ]
+        }
+    med = float(np.median(arr))
+    mad = float(np.median(np.abs(arr - med)))
+    sigma = 1.4826 * mad
+    if sigma == 0:
+        sigma = float(np.std(arr))
+    return {
+        "amplitude": float(arr.max() - arr.min()),
+        "beyond_1_std": float(np.mean(np.abs(arr - arr.mean()) > 1.0 * arr.std())),
+        "beyond_2_std": float(np.mean(np.abs(arr - arr.mean()) > 2.0 * arr.std())),
+        "car_sigma": float(arr.std() / max(abs(arr.mean()), 1e-12)),
+        "car_mean": float(arr.mean()),
+        "car_std": float(arr.std()),
+        "skew": float(_stats.skew(arr)),
+        "kurtosis": float(_stats.kurtosis(arr)),
+        "median_abs_dev": float(mad),
+    }
+
+
+def extract_all_features(
+    df,
+    target: str,
+    *,
+    add_cyclic: bool = True,
+    cyclic_period: int = 24,
+    add_rolling: bool = True,
+    rolling_windows: tuple[int, ...] = (24, 168),
+    add_lags: bool = True,
+    lags: tuple[int, ...] = (1, 24, 168),
+    add_spectral: bool = True,
+):
+    """Convenience pipeline: cyclic + rolling + lag + (optional) spectral features.
+
+    Returns a :class:`polars.DataFrame` regardless of input type.
+    """
+    import polars as pl
+
+    from .spectral import fft_features, spectral_entropy
+    from .temporal import cyclical_encode, lag_features, rolling_statistics
+
+    pdf = to_polars(df)
+    out = pdf
+
+    if add_cyclic:
+        if is_pandas_datetime_index(df):
+            out = cyclical_encode(df)
+        elif isinstance(out, pl.DataFrame):
+            dt_cols = datetime_columns(out)
+            if dt_cols:
+                out = cyclical_encode(out, datetime_col=dt_cols[0])
+        else:
+            out = cyclical_encode(out)
+
+    if add_rolling:
+        out = rolling_statistics(out, columns=[target], windows=rolling_windows)
+
+    if add_lags:
+        out = lag_features(out, columns=[target], lags=lags, drop_na=False)
+
+    if add_spectral:
+        target_arr = out[target].to_numpy()
+        spec = fft_features(target_arr, top_k=5)
+        ent = spectral_entropy(target_arr)
+        for k, v in spec.items():
+            out = out.with_columns(pl.lit(float(v)).alias(f"fft_{k}"))
+        out = out.with_columns(pl.lit(float(ent)).alias("spectral_entropy"))
+    return out