forecastbox 0.1.0__tar.gz

forecastbox-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Verify version matches release tag
+      run: |
+        VERSION=$(python -c "import sys; sys.path.insert(0, 'forecastbox'); from __version__ import __version__; print(__version__)")
+        TAG=${GITHUB_REF#refs/tags/v}
+        echo "Package version: $VERSION"
+        echo "Release tag: $TAG"
+        if [ "$VERSION" != "$TAG" ]; then
+          echo "Error: Version mismatch!"
+          exit 1
+        fi
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        skip-existing: false
+        verbose: true
+
+    - name: Upload release assets
+      uses: softprops/action-gh-release@v2
+      with:
+        files: |
+          dist/*.tar.gz
+          dist/*.whl
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

forecastbox-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+.mutmut-cache
+mutants/
+
+# IDE
+.vscode/
+.idea/
+
+# Docs
+site/
+
+# Logs
+logs/
+
+# OS
+.DS_Store
+Thumbs.db

forecastbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-17
+
+### Added
+
+- **Core**: Forecast container, ForecastResults, ForecastHorizon, DataVintage
+- **Auto-Forecasting**: AutoARIMA, AutoETS, Theta, AutoVAR, AutoSelect
+- **Combination**: 7 methods (mean, median, inverse_mse, ols, bma, stacking, optimal)
+- **Evaluation**: Diebold-Mariano, MCS, Giacomini-White, Mincer-Zarnowitz, Encompassing
+- **Metrics**: MAE, RMSE, MAPE, MASE, CRPS, coverage
+- **Scenarios**: Conditional forecasts, stress testing, fan charts
+- **Nowcasting**: DFM, bridge equations, MIDAS, news decomposition
+- **Pipeline**: ForecastPipeline, ForecastMonitor with alerts
+- **Visualization**: Forecast plots, comparison plots, fan charts
+- **Reports**: HTML/Markdown/JSON report generation
+- **CLI**: 5 commands (forecast, evaluate, nowcast, monitor, combine)
+- **Datasets**: 20 built-in datasets
+- **ForecastExperiment**: High-level workflow API
+- **Cross-Validation**: Expanding and sliding window
+- **Documentation**: MkDocs with ~37 pages

forecastbox-0.1.0/LICENSE

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

forecastbox-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: forecastbox
+Version: 0.1.0
+Summary: Forecast containers, evaluation metrics, and cross-validation for time series
+Author: NodesEcon
+License: MIT
+License-File: LICENSE
+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: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# forecastbox
+
+Forecast containers, evaluation metrics, and cross-validation for time series.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import numpy as np
+import pandas as pd
+from forecastbox import Forecast
+from forecastbox.metrics import mae, rmse
+from forecastbox.datasets import load_dataset
+
+# Create a forecast
+fc = Forecast(
+    point=np.array([100.5, 101.2, 102.0]),
+    index=pd.date_range('2024-01', periods=3, freq='MS'),
+    model_name='MyModel',
+    horizon=3
+)
+
+# Evaluate
+actual = np.array([100.8, 100.9, 103.1])
+print(f"MAE: {mae(actual, fc.point):.2f}")
+print(f"RMSE: {rmse(actual, fc.point):.2f}")
+
+# Load dataset
+data = load_dataset('macro_brazil')
+print(data['ipca'].head())
+```
+
+## License
+
+MIT

forecastbox-0.1.0/README.md

@@ -0,0 +1,40 @@
+# forecastbox
+
+Forecast containers, evaluation metrics, and cross-validation for time series.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import numpy as np
+import pandas as pd
+from forecastbox import Forecast
+from forecastbox.metrics import mae, rmse
+from forecastbox.datasets import load_dataset
+
+# Create a forecast
+fc = Forecast(
+    point=np.array([100.5, 101.2, 102.0]),
+    index=pd.date_range('2024-01', periods=3, freq='MS'),
+    model_name='MyModel',
+    horizon=3
+)
+
+# Evaluate
+actual = np.array([100.8, 100.9, 103.1])
+print(f"MAE: {mae(actual, fc.point):.2f}")
+print(f"RMSE: {rmse(actual, fc.point):.2f}")
+
+# Load dataset
+data = load_dataset('macro_brazil')
+print(data['ipca'].head())
+```
+
+## License
+
+MIT

forecastbox-0.1.0/benchmarks/bench_auto_arima.py

@@ -0,0 +1,89 @@
+"""Benchmark: AutoARIMA fit time.
+
+Target: < 2s for 300 observations.
+
+Usage:
+    python benchmarks/bench_auto_arima.py
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+
+
+def bench_auto_arima() -> dict[str, float]:
+    """Benchmark AutoARIMA fit time.
+
+    Returns
+    -------
+    dict[str, float]
+        Benchmark results with keys: n_obs, fit_time, forecast_time, total_time.
+    """
+    print("=" * 60)
+    print("Benchmark: AutoARIMA")
+    print("=" * 60)
+
+    # Load data
+    try:
+        from forecastbox.datasets import load_dataset
+
+        data = load_dataset("macro_brazil")
+        series = data["ipca"]
+    except ImportError:
+        rng = np.random.default_rng(42)
+        dates = pd.date_range("2000-01-01", periods=300, freq="MS")
+        series = pd.Series(
+            0.5 + rng.normal(0, 0.3, 300), index=dates, name="ipca"
+        )
+
+    n_obs = len(series)
+    print(f"Data: {n_obs} observations")
+
+    try:
+        from forecastbox.auto.arima import AutoARIMA
+
+        # Fit
+        model = AutoARIMA(seasonal=True, m=12)
+        start = time.time()
+        result = model.fit(series)
+        fit_time = time.time() - start
+
+        # Forecast
+        start = time.time()
+        fc = result.forecast(h=12)
+        forecast_time = time.time() - start
+
+        total_time = fit_time + forecast_time
+
+        print("\nResults:")
+        print(
+            f"  Fit time:      {fit_time:.3f}s "
+            f"{'PASS' if fit_time < 2.0 else 'FAIL'} (target: <2s)"
+        )
+        print(f"  Forecast time: {forecast_time:.3f}s")
+        print(f"  Total time:    {total_time:.3f}s")
+        print(f"  Model:         {fc.model_name}")
+
+        return {
+            "n_obs": n_obs,
+            "fit_time": fit_time,
+            "forecast_time": forecast_time,
+            "total_time": total_time,
+        }
+
+    except ImportError:
+        print("SKIP: AutoARIMA not available")
+        return {"n_obs": n_obs, "fit_time": 0, "forecast_time": 0, "total_time": 0}
+    except Exception as e:
+        print(f"FAIL: {e}")
+        return {"n_obs": n_obs, "fit_time": -1, "forecast_time": -1, "total_time": -1}
+
+
+if __name__ == "__main__":
+    results = bench_auto_arima()
+    passed = results.get("fit_time", -1) < 2.0 or results.get("fit_time", -1) == 0
+    sys.exit(0 if passed else 1)

forecastbox-0.1.0/benchmarks/bench_combination.py

@@ -0,0 +1,113 @@
+"""Benchmark: Forecast combination methods.
+
+Target: < 1s for 7 methods, 12-step ahead.
+
+Usage:
+    python benchmarks/bench_combination.py
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+
+
+def bench_combination() -> dict[str, float]:
+    """Benchmark combination methods.
+
+    Returns
+    -------
+    dict[str, float]
+        Time per method.
+    """
+    print("=" * 60)
+    print("Benchmark: Forecast Combination")
+    print("=" * 60)
+
+    from forecastbox.core.forecast import Forecast
+
+    # Create 5 synthetic forecasts
+    rng = np.random.default_rng(42)
+    forecasts: list[Forecast] = []
+    for i in range(5):
+        fc = Forecast(
+            point=100 + rng.normal(0, 5, 12),
+            lower_80=100 + rng.normal(0, 5, 12) - 5,
+            upper_80=100 + rng.normal(0, 5, 12) + 5,
+            model_name=f"Model_{i + 1}",
+        )
+        forecasts.append(fc)
+
+    actual = 100 + rng.normal(0, 3, 12)
+
+    results: dict[str, float] = {}
+
+    # Simple methods (always available via Forecast.combine)
+    for method in ["mean", "median"]:
+        start = time.time()
+        Forecast.combine(forecasts, method=method)
+        elapsed = time.time() - start
+        results[method] = elapsed
+        print(f"  {method}: {elapsed:.4f}s")
+
+    # Advanced methods via combination module
+    combiner_map = {
+        "inverse_mse": "forecastbox.combination.weighted",
+        "ols": "forecastbox.combination.ols",
+        "bma": "forecastbox.combination.bma",
+        "stacking": "forecastbox.combination.stacking",
+        "optimal": "forecastbox.combination.optimal",
+    }
+
+    # Extract point arrays for training
+    fc_arrays = [fc.point for fc in forecasts]
+
+    for method, module_path in combiner_map.items():
+        try:
+            import importlib
+
+            mod = importlib.import_module(module_path)
+            # Get the combiner class (first class that ends with Combiner)
+            combiner_cls = None
+            for attr_name in dir(mod):
+                attr = getattr(mod, attr_name)
+                if (
+                    isinstance(attr, type)
+                    and attr_name.endswith("Combiner")
+                    and attr_name != "BaseCombiner"
+                ):
+                    combiner_cls = attr
+                    break
+
+            if combiner_cls is None:
+                print(f"  {method}: SKIP (no combiner class found)")
+                continue
+
+            start = time.time()
+            combiner = combiner_cls()
+            combiner.fit(fc_arrays, actual)
+            combiner.combine(forecasts)
+            elapsed = time.time() - start
+            results[method] = elapsed
+            print(f"  {method}: {elapsed:.4f}s")
+        except ImportError:
+            print(f"  {method}: SKIP (module not available)")
+        except Exception as e:
+            print(f"  {method}: FAIL ({e})")
+            results[method] = -1
+
+    total = sum(v for v in results.values() if v > 0)
+    print(
+        f"\nTotal time: {total:.4f}s "
+        f"{'PASS' if total < 1.0 else 'FAIL'} (target: <1s)"
+    )
+
+    return results
+
+
+if __name__ == "__main__":
+    results = bench_combination()
+    total = sum(v for v in results.values() if v > 0)
+    sys.exit(0 if total < 1.0 else 1)

forecastbox-0.1.0/benchmarks/bench_nowcast.py

@@ -0,0 +1,93 @@
+"""Benchmark: DFM nowcast.
+
+Target: < 5s for 10 series.
+
+Usage:
+    python benchmarks/bench_nowcast.py
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+
+
+def bench_nowcast() -> dict[str, float]:
+    """Benchmark DFM nowcast.
+
+    Returns
+    -------
+    dict[str, float]
+        Benchmark results.
+    """
+    print("=" * 60)
+    print("Benchmark: DFM Nowcast")
+    print("=" * 60)
+
+    # Load simulated DFM data
+    try:
+        from forecastbox.datasets import load_dataset
+
+        data = load_dataset("simulated_dfm")
+        df = pd.DataFrame(data)
+    except (ImportError, KeyError):
+        rng = np.random.default_rng(42)
+        dates = pd.date_range("2000-01-01", periods=300, freq="MS")
+        df = pd.DataFrame(
+            {f"series_{i + 1}": rng.normal(0, 1, 300) for i in range(10)},
+            index=dates,
+        )
+
+    n_series = len(df.columns)
+    n_obs = len(df)
+    print(f"Data: {n_series} series, {n_obs} observations")
+
+    try:
+        from forecastbox.nowcasting.dfm import DFMNowcaster
+
+        # Build frequency map (all monthly for synthetic data)
+        freq_map = {col: "M" for col in df.columns}
+
+        # Fit
+        start = time.time()
+        nowcaster = DFMNowcaster(n_factors=2, frequency_map=freq_map)
+        nowcaster.fit(df)
+        fit_time = time.time() - start
+
+        # Nowcast
+        start = time.time()
+        nowcaster.nowcast(target=df.columns[0])
+        nowcast_time = time.time() - start
+
+        total_time = fit_time + nowcast_time
+
+        print("\nResults:")
+        print(f"  Fit time:     {fit_time:.3f}s")
+        print(f"  Nowcast time: {nowcast_time:.3f}s")
+        print(
+            f"  Total time:   {total_time:.3f}s "
+            f"{'PASS' if total_time < 5.0 else 'FAIL'} (target: <5s)"
+        )
+
+        return {
+            "n_series": float(n_series),
+            "n_obs": float(n_obs),
+            "fit_time": fit_time,
+            "nowcast_time": nowcast_time,
+            "total_time": total_time,
+        }
+
+    except ImportError:
+        print("SKIP: DFM module not available")
+        return {"n_series": float(n_series), "n_obs": float(n_obs), "total_time": 0}
+    except Exception as e:
+        print(f"FAIL: {e}")
+        return {"n_series": float(n_series), "n_obs": float(n_obs), "total_time": -1}
+
+
+if __name__ == "__main__":
+    results = bench_nowcast()
+    sys.exit(0 if results.get("total_time", -1) < 5.0 else 1)

forecastbox-0.1.0/benchmarks/bench_pipeline.py

@@ -0,0 +1,96 @@
+"""Benchmark: Full pipeline.
+
+Target: < 60s for 3 models, 300 observations.
+
+Usage:
+    python benchmarks/bench_pipeline.py
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+
+
+def bench_pipeline() -> dict[str, float]:
+    """Benchmark full forecast pipeline.
+
+    Returns
+    -------
+    dict[str, float]
+        Benchmark results.
+    """
+    print("=" * 60)
+    print("Benchmark: Full Pipeline")
+    print("=" * 60)
+
+    # Load data
+    try:
+        from forecastbox.datasets import load_dataset
+
+        data = load_dataset("macro_brazil")
+        df = pd.DataFrame(data)
+    except ImportError:
+        rng = np.random.default_rng(42)
+        dates = pd.date_range("2000-01-01", periods=300, freq="MS")
+        df = pd.DataFrame(
+            {
+                "ipca": 0.5 + rng.normal(0, 0.3, 300),
+                "selic": 10 + np.cumsum(rng.normal(0, 0.5, 300)),
+                "cambio": 3 + np.cumsum(rng.normal(0, 0.1, 300)),
+            },
+            index=dates,
+        )
+
+    n_obs = len(df)
+    print(f"Data: {n_obs} observations, {len(df.columns)} variables")
+
+    try:
+        from forecastbox.experiment import ForecastExperiment
+
+        models = ["auto_arima", "auto_ets", "theta"]
+        print(f"Models: {models}")
+
+        start = time.time()
+        exp = ForecastExperiment(
+            data=df,
+            target="ipca",
+            models=models,
+            combination="mean",
+            horizon=12,
+            cv_type="expanding",
+        )
+        results = exp.run()
+        total_time = time.time() - start
+
+        n_forecasts = len(results.forecasts)
+
+        print("\nResults:")
+        print(f"  Models fitted: {n_forecasts}/{len(models)}")
+        print(f"  Combination: {'Yes' if results.combination else 'No'}")
+        print(
+            f"  Total time:  {total_time:.2f}s "
+            f"{'PASS' if total_time < 60.0 else 'FAIL'} (target: <60s)"
+        )
+
+        return {
+            "n_obs": float(n_obs),
+            "n_models": float(n_forecasts),
+            "total_time": total_time,
+        }
+
+    except ImportError:
+        print("SKIP: Required modules not available")
+        return {"n_obs": float(n_obs), "n_models": 0, "total_time": 0}
+    except Exception as e:
+        print(f"FAIL: {e}")
+        return {"n_obs": float(n_obs), "n_models": 0, "total_time": -1}
+
+
+if __name__ == "__main__":
+    results = bench_pipeline()
+    t = results.get("total_time", -1)
+    sys.exit(0 if t < 60.0 or t == 0 else 1)

forecastbox-0.1.0/forecastbox/__init__.py

@@ -0,0 +1,12 @@
+"""forecastbox - Forecast containers, evaluation metrics, and cross-validation for time series."""
+
+from forecastbox.__version__ import __version__
+from forecastbox.core.forecast import Forecast
+from forecastbox.experiment import ExperimentResults, ForecastExperiment
+
+__all__ = [
+    "__version__",
+    "Forecast",
+    "ForecastExperiment",
+    "ExperimentResults",
+]

forecastbox-0.1.0/forecastbox/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

forecastbox-0.1.0/forecastbox/_logging.py

@@ -0,0 +1,16 @@
+"""Logging configuration for forecastbox."""
+
+import logging
+
+_LOG_FORMAT = "%(asctime)s [%(name)s] %(levelname)s: %(message)s"
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the forecastbox namespace."""
+    logger = logging.getLogger(f"forecastbox.{name}")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+        logger.addHandler(handler)
+        logger.setLevel(logging.WARNING)
+    return logger