moeforecast 0.1.0__tar.gz

moeforecast-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,77 @@
+name: PyPI release
+
+on:
+  push:
+    branches: [master, main]
+    paths:
+      - "pyproject.toml"
+      - "src/moeforecast/**"
+      - "README.md"
+      - "LICENSE"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test release candidate
+    runs-on: ubuntu-latest
+    outputs:
+      stable: ${{ steps.version.outputs.stable }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and development dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Lint and test
+        run: |
+          ruff check .
+          ruff format --check .
+          pytest -p no:warnings
+      - name: Check whether this is a stable release
+        id: version
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          from packaging.version import Version
+          import re
+
+          source = Path("src/moeforecast/__init__.py").read_text()
+          match = re.search(r'__version__ = "([^"]+)"', source)
+          if not match:
+              raise SystemExit("Could not read moeforecast.__version__")
+          version = Version(match.group(1))
+          stable = not version.is_prerelease and not version.is_devrelease
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              output.write(f"stable={str(stable).lower()}\n")
+          if not stable:
+              print(f"{version} is a development/pre-release version; skipping PyPI publication.")
+          else:
+              print(f"Stable version {version} is eligible for PyPI publication.")
+          PY
+
+  publish:
+    name: Publish stable package to PyPI
+    needs: test
+    if: needs.test.outputs.stable == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/moeforecast
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

moeforecast-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,71 @@
+name: TestPyPI
+
+on:
+  push:
+    branches: [release]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: testpypi-release-branch
+  cancel-in-progress: false
+
+jobs:
+  test:
+    name: Test release branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and development dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Lint and test
+        run: |
+          ruff check .
+          ruff format --check .
+          pytest -p no:warnings
+
+  publish:
+    name: Publish a development build to TestPyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/moeforecast
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Set a unique TestPyPI version
+        env:
+          RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          path = Path("src/moeforecast/__init__.py")
+          source = path.read_text()
+          match = re.search(r'__version__ = "(\d+\.\d+\.\d+)(?:\.dev\d+)?"', source)
+          if not match:
+              raise SystemExit("Expected __version__ in X.Y.Z or X.Y.Z.devN format")
+          version = f"{match.group(1)}.dev{os.environ['RUN_NUMBER']}"
+          path.write_text(re.sub(r'__version__ = "[^"]+"', f'__version__ = "{version}"', source, count=1))
+          print(f"Building TestPyPI version {version}")
+          PY
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

moeforecast-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: tests
+
+on:
+  push:
+    branches: [release, master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check . && ruff format --check .
+      - name: Test
+        run: pytest -p no:warnings

moeforecast-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+.DS_Store
+*.joblib

moeforecast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastián Torres
+
+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.

moeforecast-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.5
+Name: moeforecast
+Version: 0.1.0
+Summary: Mixture-of-Experts time series forecasting with regime clustering and adaptive gating, with a scikit-learn style API.
+Project-URL: Homepage, https://github.com/astorress/moeforecast
+Project-URL: Issues, https://github.com/astorress/moeforecast/issues
+Author-email: Sebastián Torres <sebastiantorres8800@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clustering,forecasting,load forecasting,mixture of experts,scikit-learn,time series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: statsmodels>=0.14
+Provides-Extra: all
+Requires-Dist: holidays>=0.40; extra == 'all'
+Requires-Dist: lightgbm>=4.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: holidays>=0.40; extra == 'dev'
+Requires-Dist: lightgbm>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: dtw
+Requires-Dist: tslearn>=0.6.3; extra == 'dtw'
+Provides-Extra: holidays
+Requires-Dist: holidays>=0.40; extra == 'holidays'
+Provides-Extra: lightgbm
+Requires-Dist: lightgbm>=4.0; extra == 'lightgbm'
+Description-Content-Type: text/markdown
+
+# moeforecast
+
+**Mixture-of-Experts time series forecasting with a scikit-learn style API.**
+
+`moeforecast` builds a forecaster that learns the *regimes* of a series and trains one specialised model (an *expert*) per regime. A regime is, for example, a type of day (working day, weekend, holiday) or a type of week. A gating network then combines the experts at prediction time. The method comes from hourly electricity demand forecasting, but it applies to any regularly sampled series with recurring seasonal profiles.
+
+> Status: pre-alpha (0.1.0.dev0). The API may change.
+
+```python
+import pandas as pd
+from moeforecast import prepare_series, temporal_train_test_split
+
+df = pd.read_csv("load.csv")  # your data
+y = prepare_series(df, target="load", time_col="timestamp")  # regular, sorted series
+
+train, test = temporal_train_test_split(y, test_size="2025-01-01")
+# Continue with the analysis and cluster-selection workflow below.
+```
+
+## What the library does (and does not do)
+
+`moeforecast` gives you the tools to **build** the model and to choose its configuration, like scikit-learn does. Benchmarking against other models, statistical comparison tests and robustness studies are left to the user.
+
+| Step | Tool | What it gives you |
+|---|---|---|
+| 1. Prepare the data | `prepare_series`, `fill_gaps` | Sorted series on a regular grid; warns about gaps and never imputes silently |
+| 2. Analyse the series | `SeriesAnalyzer` | Suggested seasonal periods and lags (ACF/PACF); ACF/PACF, seasonal-profile and MSTL plots |
+| 3. Build features | `FeatureBuilder` | Causal calendar, Fourier, holiday (any country), lag and rolling features. The same code serves training, prediction and forecasting |
+| 4. Rank features | `feature_relevance` | Mutual information or permutation importance |
+| 5. Find regimes | `ProfileClusterer` | Daily, weekly or monthly profile diagnostics, distance choice, silhouette plots and explicit selection of k |
+| 6. Predict regimes | `RegimeClassifier`, `compare_classifiers` | Regime probabilities for the gating; time-ordered comparison of classifiers |
+| 7. Train experts | `ExpertSelector` | Best candidate model per regime (forward-chaining CV); ten default regressors, user additions/removals and MAE/RMSE/MAPE selection |
+| 8. Combine experts | `HardGating`, `SoftGating`, `AdaptiveGating` | Expert weights per time step |
+| 9. All together | `MoEForecaster` | `fit`, `predict`, `predict_with_metadata`, `expert_weights`, `forecast` |
+| 10. Persist | `save`, `load` | Serialization with version check |
+| Metrics | `moeforecast.metrics` | MAE, RMSE, MAPE, MASE |
+
+## Installation
+
+```bash
+pip install "moeforecast[all]"          # with LightGBM and public holidays
+pip install "moeforecast[dtw]"          # optional DTW profile clustering
+pip install moeforecast                 # core only: numpy, pandas, scikit-learn, statsmodels, matplotlib
+```
+
+Not on PyPI yet. Install from source:
+
+```bash
+git clone https://github.com/astorress/moeforecast.git
+cd moeforecast
+pip install -e ".[dev]"
+pytest
+```
+
+## Step by step
+
+```python
+from moeforecast import (
+    SeriesAnalyzer,
+    FeatureBuilder,
+    feature_relevance,
+    ProfileClusterer,
+    compare_classifiers,
+    ExpertSelector,
+    AdaptiveGating,
+    MoEForecaster,
+)
+
+# 1. Which periods and lags matter?
+analysis = SeriesAnalyzer().fit(train)
+print(analysis.summary())  # e.g. periods [24, 168], lags [1, 2, 23, 24, 25, 167, 168, 169]
+analysis.plot_acf_pacf()
+
+# 2. Features and their relevance
+features = FeatureBuilder(lags=analysis.suggested_lags_, fourier_periods=(24, 168), holidays_country="CO")
+X = features.fit(train).transform(train)
+feature_relevance(X, train, method="permutation").head(15)
+
+# 3. Inspect cluster-validation metrics before choosing the cluster count.
+days = ProfileClusterer("D", name="day", k_range=range(2, 11))
+days.evaluate(train)
+days.plot_scores()
+days.plot_silhouette()  # inspect all candidate k values before deciding
+days.set_params(n_clusters=3).fit(train)  # choose k after reviewing the scores
+days.plot_profiles()
+
+weeks = ProfileClusterer("W", name="week", k_range=range(2, 11))
+weeks.evaluate(train)
+weeks.plot_scores()
+weeks.set_params(n_clusters=2).fit(train)
+
+# 4. Can the regimes be predicted from the features?
+compare_classifiers(X, days.labels_for(train.index))
+
+# 5. The full model with the chosen configuration
+model = MoEForecaster(
+    features=features,
+    clusterers=[days, weeks],
+    selector=ExpertSelector(metric="mae", search="random", n_iter=20),
+    gating=AdaptiveGating(threshold=0.75),
+).fit(train)
+
+model.selector_.results_  # every candidate's CV score per expert
+report = model.inspect()
+report["expert_hyperparameter_searches"]  # every tried parameter set and its CV score
+pred, meta = model.predict_with_metadata(y)
+meta["mode"].value_counts()  # hard vs. soft gating decisions
+
+# Tune experts and classifiers by forward-chaining CV ("grid" is also supported).
+# Override any named default with your own sklearn parameter distributions.
+selector = ExpertSelector(
+    search="random",
+    n_iter=30,
+    search_spaces={
+        "random_forest": {
+            "n_estimators": [100, 250, 500],
+            "max_depth": [None, 8, 16],
+            "min_samples_leaf": [1, 3, 5],
+        }
+    },
+)
+model = MoEForecaster(
+    features=features,
+    clusterers=[days, weeks],
+    selector=selector,
+    classifier_search="grid",
+).fit(train)
+
+# Optimize gating on data not used by fit; review scores before using the setting.
+gating_scores = model.tune_gating(validation, search="grid", metric="mae")
+gating_scores.head()
+
+# Export an image of the actual fitted architecture.
+model.plot_model("outputs/moe-architecture.png")
+```
+
+## Inspect every fitted component
+
+The fitted estimators are not hidden behind the forecaster. `inspect()` returns
+the actual scikit-learn objects together with copied diagnostic tables:
+
+```python
+report = model.inspect()
+
+# Cluster assignments, candidate-k scores, source profiles and cluster means
+report["clusters"]["day"]["summary"]
+report["clusters"]["day"]["scores"]
+report["clusters"]["day"]["assignments"]
+report["clusters"]["day"]["mean_profiles"]
+
+# Fitted classifier and its input features / class counts
+classifier = report["classifiers"]["day"]
+print(classifier["estimator"])
+classifier["features"], classifier["class_counts"]
+
+# Every candidate's time-series CV results and each final fitted expert
+report["expert_selection"]
+for expert_name, estimator in report["experts"].items():
+    print(expert_name, estimator)
+
+# Candidate model templates, fitted feature builder, and gating estimator
+report["candidate_experts"]
+report["configuration"]["features"].get_params()
+report["gating"].get_params()
+```
+
+`inspect()` also exposes the full `ProfileClusterer` objects and fitted k-means
+estimators. `RegimeClassifier.estimator_`, `ExpertSelector.experts_`,
+`ExpertSelector.candidate_estimators_`, `ProfileClusterer.labels_`,
+`ProfileClusterer.scores_`, and `ProfileClusterer.mean_profiles_` remain
+available directly for users who prefer to inspect individual components.
+
+See the [quickstart notebook](examples/quickstart.ipynb) for a complete,
+synthetic-data walkthrough of the public modeling API, including diagnostics,
+regime classifiers, all gating strategies, model inspection, forecasting and
+persistence.
+
+HPO uses forward-chaining folds. ``ExpertSelector(search="grid"|"random")``
+searches each candidate's parameter space independently inside each regime,
+then compares the tuned candidates and keeps the best estimator for that expert.
+Defaults are available for built-in model names through
+``default_search_spaces()``; pass ``search_spaces`` to replace or extend them.
+``MoEForecaster(classifier_search=...)`` tunes its regime classifiers.
+``tune_gating`` requires a later validation series that was not used for fitting;
+it searches adaptive-gating confidence thresholds, minimum expert weights and
+probability temperature. All fitted HPO objects and per-setting scores remain
+inspectable through ``inspect()`` and the component attributes.
+``plot_model(path)`` saves a diagram showing the fitted clusters, classifiers,
+experts and gating component.
+
+## Design
+
+These principles prevent the errors that are easy to make when a Mixture of Experts is built by hand:
+
+- **No look-ahead.** Every feature at time *t* uses only values before *t*. `fit` only sees the training series. The classifier comparison and the expert selection use forward-chaining (time-ordered) cross-validation.
+- **One feature function.** `FeatureBuilder.transform` is used for training, prediction and recursive forecasting, so there is no train/serve skew. Fourier terms are anchored to a fixed origin, not to where the data starts.
+- **Typed expert identifiers.** An expert is a tuple of regime labels, e.g. `(0, 1)`, used everywhere. `"day0-week1"` is only a display name.
+- **Deterministic choices.** Cluster labels are ordered by level and ties are broken by candidate order. Selections come from the stated metric.
+
+[docs/design.md](docs/design.md) explains each decision.
+
+## Release process
+
+Development builds are published to TestPyPI from the `release` branch. Stable
+versions are published to PyPI only after merging to `master` or `main`. See
+[the release guide](docs/release-process.md) for the full workflow and the
+one-time Trusted Publisher setup.
+
+## Roadmap
+
+- Deep-learning experts (LSTM/GRU) as an optional extra (`moeforecast[dl]`).
+- DTW and k-Shape clustering (optional `tslearn` extra).
+- HTML report of the analysis and the fitted model.
+
+## Citation
+
+If you use `moeforecast` in research, please cite the accompanying article (reference to be added).
+
+## License
+
+[MIT](LICENSE)