felits 0.1.0__tar.gz

felits-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Byte-compiled & caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.tox/
+.nox/
+.coverage
+coverage.xml
+htmlcov/
+
+# Virtual environments
+.venv/
+.venv*/
+env/
+venv/
+
+# Distribution
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE
+.vscode/
+.idea/
+.kilo/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data files (user-local)
+dataset/
+*.csv
+*.parquet
+*.h5
+*.hdf5
+
+# Lockfiles (libraries don't commit lockfiles)
+uv.lock
+Pipfile.lock
+poetry.lock
+
+# Python version file (user-local)
+.python-version
+
+# docs
+research-docs/

felits-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Félix Morales Mareco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

felits-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: felits
+Version: 0.1.0
+Summary: Feature Engineering and Large-scale Integration for Time Series
+Project-URL: Homepage, https://github.com/felits/felits
+Project-URL: Issues, https://github.com/felits/felits/issues
+Author: Félix Morales Mareco
+License: MIT
+License-File: LICENSE
+Keywords: feature-engineering,forecasting,machine-learning,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.14,>=3.11
+Requires-Dist: lime>=0.2.0.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: optuna>=3.5
+Requires-Dist: pandas>=2.0
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.11
+Requires-Dist: shap>=0.44
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: tsfresh>=0.20
+Provides-Extra: all
+Requires-Dist: duckdb>=1.0; extra == 'all'
+Requires-Dist: pywavelets>=1.5; extra == 'all'
+Requires-Dist: tensorflow>=2.15; extra == 'all'
+Requires-Dist: xgboost>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: duckdb>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: pywavelets>=1.5; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: xgboost>=2.0; extra == 'dev'
+Provides-Extra: dl
+Requires-Dist: tensorflow>=2.15; extra == 'dl'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.0; extra == 'duckdb'
+Provides-Extra: wavelet
+Requires-Dist: pywavelets>=1.5; extra == 'wavelet'
+Provides-Extra: xgb
+Requires-Dist: xgboost>=2.0; extra == 'xgb'
+Description-Content-Type: text/markdown
+
+# FELITS: Feature Engineering and Large-scale Integration for Time Series
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11|3.12|3.13-blue.svg)](https://www.python.org/downloads/)
+
+FELITS is an open-source Python library for end-to-end **time series analysis and forecasting**, with a focus on **Short-Term Load Forecasting (STLF)**. It provides a complete pipeline: signal cleaning, feature engineering, feature selection, predictive modelling, and explainable AI (XAI).
+
+The library is the result of the INIC01-6 research project (CONACYT, Paraguay) and was used to produce the methodology for a published research article.
+
+## Highlights
+
+- **Preprocessing** — outlier detection (IQR, Hampel/MAD, 3-sigma), STL decomposition, dual-scaler pattern
+- **Feature extraction** — cyclic encodings, lag/shift features, rolling statistics, FFT, wavelets, tsfresh, FATS-style
+- **Feature selection** — Granger causality, KSG mutual information, mRMR, Adaptive LASSO, RF/XGB importance
+- **Models** — XGBoost, RandomForest, LinearRegression, plus `tf.keras` RNN models (LSTM/GRU/BiLSTM/BiGRU) and Bahdanau attention variants
+- **XAI** — LIME, SHAP, and **Deep SHAP as a closed-loop meta-optimizer** for feature elimination
+- **Optuna** hyperparameter optimization with multi-objective TPE sampler
+- **Dual API** — all modules accept both `pandas` and `polars` DataFrames; internal logic uses `polars` for performance
+
+## Requirements
+
+- Python ≥3.11, <3.14 (TensorFlow requires ≤3.13)
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+```bash
+git clone https://github.com/felits/felits.git
+cd felits
+
+# Create venv and install with uv (recommended)
+uv venv --python 3.13
+uv pip install -e ".[all,dev]"
+```
+
+### Extra dependency groups
+
+| Extra | Includes |
+|---|---|
+| `[dl]` | TensorFlow for RNN/Attention models |
+| `[xgb]` | XGBoost |
+| `[wavelet]` | PyWavelets |
+| `[duckdb]` | DuckDB for SQL-style batch feature engineering |
+| `[all]` | Everything above |
+
+### Python version management
+
+uv handles Python downloads automatically. To switch Python versions:
+
+```bash
+uv python install 3.13       # download Python 3.13
+uv venv --python 3.13 .venv  # create a venv with it
+```
+
+## Quickstart
+
+```python
+import polars as pl
+from felits.preprocessing import HampelFilter, TimeSeriesScaler
+from felits.feature_extraction import cyclical_encode, rolling_statistics
+from felits.feature_selection import FeatureSelector
+from felits.models import XGBoostForecaster
+from felits import Metrics
+
+df = pl.read_csv("demand.csv", try_parse_dates=True)
+df = df.with_columns(
+    pl.Series("value_clean", HampelFilter(window_size=24).transform(df["value"]))
+)
+df = cyclical_encode(df, datetime_col="timestamp")
+df = rolling_statistics(df, columns=["value_clean"], windows=[24, 168], stats=["mean", "std"])
+
+model = XGBoostForecaster(n_estimators=500, max_depth=6)
+model.fit(X_train, y_train)
+preds = model.predict(X_test)
+
+m = Metrics(y_test, preds)
+print(m.dict_metrics())
+```
+
+## Project layout
+
+```
+felits/
+├── _compat.py               # pandas/polars compatibility layer
+├── preprocessing/           # outliers, decomposition, scaling, imputation, metrics
+├── feature_extraction/      # temporal, spectral, automated
+├── feature_selection/       # causal, information, regularization, ensemble, xai
+├── models/                  # base, sklearn, dl (separate modules)
+│   ├── base.py              #   _SklearnForecaster, TF detection
+│   ├── sklearn.py           #   XGBoost/RF/Linear wrappers
+│   └── dl.py                #   RNN/Attention models (requires TF)
+├── optimization.py          # Optuna wrappers
+├── xai.py                   # LIME, SHAP, deep SHAP closed-loop
+└── data.py                  # loaders and synthetic data
+examples/                    # Runnable .py example scripts
+notebooks/                   # Jupyter notebooks for each example
+tests/                       # pytest suite (79+ tests)
+```
+
+## Citation
+
+If you use FELITS in academic work, please cite the associated research article (see `research-docs/`).
+
+## License
+
+MIT — see `LICENSE`.

felits-0.1.0/README.md

@@ -0,0 +1,106 @@
+# FELITS: Feature Engineering and Large-scale Integration for Time Series
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11|3.12|3.13-blue.svg)](https://www.python.org/downloads/)
+
+FELITS is an open-source Python library for end-to-end **time series analysis and forecasting**, with a focus on **Short-Term Load Forecasting (STLF)**. It provides a complete pipeline: signal cleaning, feature engineering, feature selection, predictive modelling, and explainable AI (XAI).
+
+The library is the result of the INIC01-6 research project (CONACYT, Paraguay) and was used to produce the methodology for a published research article.
+
+## Highlights
+
+- **Preprocessing** — outlier detection (IQR, Hampel/MAD, 3-sigma), STL decomposition, dual-scaler pattern
+- **Feature extraction** — cyclic encodings, lag/shift features, rolling statistics, FFT, wavelets, tsfresh, FATS-style
+- **Feature selection** — Granger causality, KSG mutual information, mRMR, Adaptive LASSO, RF/XGB importance
+- **Models** — XGBoost, RandomForest, LinearRegression, plus `tf.keras` RNN models (LSTM/GRU/BiLSTM/BiGRU) and Bahdanau attention variants
+- **XAI** — LIME, SHAP, and **Deep SHAP as a closed-loop meta-optimizer** for feature elimination
+- **Optuna** hyperparameter optimization with multi-objective TPE sampler
+- **Dual API** — all modules accept both `pandas` and `polars` DataFrames; internal logic uses `polars` for performance
+
+## Requirements
+
+- Python ≥3.11, <3.14 (TensorFlow requires ≤3.13)
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+```bash
+git clone https://github.com/felits/felits.git
+cd felits
+
+# Create venv and install with uv (recommended)
+uv venv --python 3.13
+uv pip install -e ".[all,dev]"
+```
+
+### Extra dependency groups
+
+| Extra | Includes |
+|---|---|
+| `[dl]` | TensorFlow for RNN/Attention models |
+| `[xgb]` | XGBoost |
+| `[wavelet]` | PyWavelets |
+| `[duckdb]` | DuckDB for SQL-style batch feature engineering |
+| `[all]` | Everything above |
+
+### Python version management
+
+uv handles Python downloads automatically. To switch Python versions:
+
+```bash
+uv python install 3.13       # download Python 3.13
+uv venv --python 3.13 .venv  # create a venv with it
+```
+
+## Quickstart
+
+```python
+import polars as pl
+from felits.preprocessing import HampelFilter, TimeSeriesScaler
+from felits.feature_extraction import cyclical_encode, rolling_statistics
+from felits.feature_selection import FeatureSelector
+from felits.models import XGBoostForecaster
+from felits import Metrics
+
+df = pl.read_csv("demand.csv", try_parse_dates=True)
+df = df.with_columns(
+    pl.Series("value_clean", HampelFilter(window_size=24).transform(df["value"]))
+)
+df = cyclical_encode(df, datetime_col="timestamp")
+df = rolling_statistics(df, columns=["value_clean"], windows=[24, 168], stats=["mean", "std"])
+
+model = XGBoostForecaster(n_estimators=500, max_depth=6)
+model.fit(X_train, y_train)
+preds = model.predict(X_test)
+
+m = Metrics(y_test, preds)
+print(m.dict_metrics())
+```
+
+## Project layout
+
+```
+felits/
+├── _compat.py               # pandas/polars compatibility layer
+├── preprocessing/           # outliers, decomposition, scaling, imputation, metrics
+├── feature_extraction/      # temporal, spectral, automated
+├── feature_selection/       # causal, information, regularization, ensemble, xai
+├── models/                  # base, sklearn, dl (separate modules)
+│   ├── base.py              #   _SklearnForecaster, TF detection
+│   ├── sklearn.py           #   XGBoost/RF/Linear wrappers
+│   └── dl.py                #   RNN/Attention models (requires TF)
+├── optimization.py          # Optuna wrappers
+├── xai.py                   # LIME, SHAP, deep SHAP closed-loop
+└── data.py                  # loaders and synthetic data
+examples/                    # Runnable .py example scripts
+notebooks/                   # Jupyter notebooks for each example
+tests/                       # pytest suite (79+ tests)
+```
+
+## Citation
+
+If you use FELITS in academic work, please cite the associated research article (see `research-docs/`).
+
+## License
+
+MIT — see `LICENSE`.

felits-0.1.0/examples/README.md

@@ -0,0 +1,23 @@
+# FELITS examples
+
+Each example is available as both a runnable Python script (`.py`) and a
+Jupyter notebook (`.ipynb`). The `.py` scripts are the canonical versions;
+the notebooks are generated from them.
+
+| # | Topic | Script | Notebook |
+|---|-------|--------|----------|
+| 01 | Preprocessing (outliers, STL, scaling) | [`01_preprocessing.py`](01_preprocessing.py) | [`notebooks/01_preprocessing.ipynb`](../notebooks/01_preprocessing.ipynb) |
+| 02 | Feature extraction (temporal, spectral, tsfresh) | [`02_feature_extraction.py`](02_feature_extraction.py) | [`notebooks/02_feature_extraction.ipynb`](../notebooks/02_feature_extraction.ipynb) |
+| 03 | Feature selection (Granger, MI, LASSO, SHAP) | [`03_feature_selection.py`](03_feature_selection.py) | [`notebooks/03_feature_selection.ipynb`](../notebooks/03_feature_selection.ipynb) |
+| 04 | Deep-learning models (LSTM, GRU, attention) | [`04_deep_learning_models.py`](04_deep_learning_models.py) | [`notebooks/04_deep_learning_models.ipynb`](../notebooks/04_deep_learning_models.ipynb) |
+| 05 | XAI explainability (SHAP, LIME, closed-loop) | [`05_xai_explainability.py`](05_xai_explainability.py) | [`notebooks/05_xai_explainability.ipynb`](../notebooks/05_xai_explainability.ipynb) |
+| 06 | Full STLF pipeline | [`06_full_pipeline.py`](06_full_pipeline.py) | [`notebooks/06_full_pipeline.ipynb`](../notebooks/06_full_pipeline.ipynb) |
+
+Run any script with:
+
+```bash
+uv run python examples/01_preprocessing.py
+```
+
+The deep-learning examples (#04, #06) require the optional `[dl]` extra
+and a working TensorFlow installation.

felits-0.1.0/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",
+]