spotforecast2 2.2.2__tar.gz → 2.2.3__tar.gz

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: spotforecast2
-Version: 2.2.2
+Version: 2.2.3
 Summary: Forecasting with spot
 Author: bartzbeielstein
 Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spotforecast2"
-version = "2.2.2"
+version = "2.2.3"
 description = "Forecasting with spot"
 readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/src/spotforecast2/model_selection/random_search.py

@@ -85,50 +85,44 @@ def random_search_forecaster(
         param=value pairs.
 
     Examples:
-        Basic random search with continuous parameter distributions:
-
-        >>> import pandas as pd
-        >>> import numpy as np
-        >>> from sklearn.linear_model import Ridge
-        >>> from scipy.stats import uniform
-        >>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
-        >>> from spotforecast2_safe.splitter import TimeSeriesFold
-        >>> from spotforecast2.model_selection.random_search import random_search_forecaster
-        >>>
-        >>> # Create sample data
-        >>> np.random.seed(123)
-        >>> y = pd.Series(np.random.randn(50), name='y')
-        >>>
-        >>> # Set up forecaster and cross-validation
-        >>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
-        >>> cv = TimeSeriesFold(steps=3, initial_train_size=20, refit=False)
-        >>>
-        >>> # Define parameter distributions with scipy.stats
-        >>> param_distributions = {
-        ...     'estimator__alpha': uniform(0.1, 10.0)  # Uniform between 0.1 and 10.1
-        ... }
-        >>>
-        >>> # Run random search
-        >>> results = random_search_forecaster(
-        ...     forecaster=forecaster,
-        ...     y=y,
-        ...     cv=cv,
-        ...     param_distributions=param_distributions,
-        ...     metric='mean_squared_error',
-        ...     n_iter=5,
-        ...     random_state=42,
-        ...     return_best=False,
-        ...     verbose=False,
-        ...     show_progress=False
-        ... )
-        >>>
-        >>> # Check results
-        >>> print(results.shape[0])
-        5
-        >>> print('estimator__alpha' in results.columns)
-        True
-        >>> print('mean_squared_error' in results.columns)
-        True
+        ```{python}
+        import numpy as np
+        import pandas as pd
+        from sklearn.linear_model import Ridge
+        from scipy.stats import uniform
+        from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
+        from spotforecast2_safe.splitter import TimeSeriesFold
+        from spotforecast2.model_selection.random_search import random_search_forecaster
+
+        rng = np.random.default_rng(1234)
+        y = pd.Series(rng.standard_normal(30), name="y")
+
+        forecaster = ForecasterRecursive(estimator=Ridge(), lags=2)
+        cv = TimeSeriesFold(steps=2, initial_train_size=20, refit=False)
+
+        param_distributions = {
+            "estimator__alpha": uniform(0.1, 10.0),
+        }
+
+        results = random_search_forecaster(
+            forecaster=forecaster,
+            y=y,
+            cv=cv,
+            param_distributions=param_distributions,
+            metric="mean_squared_error",
+            n_iter=2,
+            random_state=1234,
+            return_best=False,
+            verbose=False,
+            show_progress=False,
+        )
+
+        print(results.shape)
+        print(results.columns.tolist())
+        assert results.shape[0] == 2
+        assert "estimator__alpha" in results.columns
+        assert "mean_squared_error" in results.columns
+        ```
     """
 
     param_grid = list(

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/src/spotforecast2/model_selection/spotoptim_search.py

@@ -7,7 +7,7 @@ Hyperparameter search functions for forecasters using SpotOptim.
 This module provides an alternative to Bayesian (Optuna-based) search
 by leveraging the SpotOptim surrogate-model-based optimizer.  It
 follows the same interface as
-:func:`spotforecast2.model_selection.bayesian_search_forecaster`, so the
+`spotforecast2.model_selection.bayesian_search_forecaster()`, so the
 two can be used interchangeably.
 """
 
@@ -21,6 +21,7 @@ from typing import Any, Callable, Dict
 
 import numpy as np
 import pandas as pd
+from tqdm.auto import tqdm
 
 try:
     from spotoptim import SpotOptim
@@ -66,33 +67,22 @@ def parse_lags_from_strings(lags_str: str | int | list) -> int | list:
         Either an integer or a list of integers representing lags.
 
     Examples:
-        Basic parsing:
-
-        >>> from spotforecast2.model_selection.spotoptim_search import (
-        ...     parse_lags_from_strings,
-        ... )
-        >>> parse_lags_from_strings(24)
-        24
-        >>> parse_lags_from_strings("[1, 2, 3]")
-        [1, 2, 3]
-
-        Visualizing the safety threshold (Example of dynamic documentation):
-
         ```{python}
-        import matplotlib.pyplot as plt
-        import numpy as np
+        from spotforecast2.model_selection.spotoptim_search import (
+            parse_lags_from_strings,
+        )
 
-        def check_safety_threshold(val, threshold):
-            return 1 if val >= threshold else 0
+        result_int = parse_lags_from_strings(24)
+        print(result_int)
+        assert result_int == 24
 
-        threshold = 0.95
-        x = np.linspace(0.8, 1.0, 50)
-        y = [check_safety_threshold(val, threshold) for val in x]
+        result_list = parse_lags_from_strings("[1, 2, 3]")
+        print(result_list)
+        assert result_list == [1, 2, 3]
 
-        plt.step(x, y, where='post')
-        plt.axvline(threshold, color='red', linestyle='--')
-        plt.title("Safety Status Transition")
-        # plt.show()  # Commented for non-interactive environments
+        result_passthrough = parse_lags_from_strings([4, 8, 12])
+        print(result_passthrough)
+        assert result_passthrough == [4, 8, 12]
         ```
     """
     if isinstance(lags_str, (int, list)):
@@ -129,7 +119,7 @@ def spotoptim_search_forecaster(
     """Hyperparameter optimisation for a Forecaster using SpotOptim.
 
     Drop-in alternative to
-    :func:`~spotforecast2.model_selection.bayesian_search_forecaster`
+    `bayesian_search_forecaster()`
     that uses the SpotOptim surrogate-model-based optimizer instead of
     Optuna's TPE sampler.
 
@@ -139,7 +129,7 @@ def spotoptim_search_forecaster(
         cv: Cross-validation strategy — ``TimeSeriesFold`` or
             ``OneStepAheadFold``.
         search_space: Hyperparameter search space.  Either a
-            :class:`~spotoptim.hyperparameters.ParameterSet` or a plain
+            `ParameterSet` or a plain
             ``dict`` (see examples below).
         metric: Metric name, callable, or list thereof.
         exog: Optional exogenous variable(s).
@@ -165,9 +155,8 @@ def spotoptim_search_forecaster(
             ``OneStepAheadFold``.
 
     Examples:
-        **1 — Dict-based search space (no ParameterSet needed):**
-
         ```{python}
+        # 1 — Dict-based search space (no ParameterSet needed):
         import numpy as np
         import pandas as pd
         from sklearn.linear_model import Ridge
@@ -209,10 +198,23 @@ def spotoptim_search_forecaster(
         print(f"Contains 'alpha': {'alpha' in results.columns}")
         ```
 
-        **2 — ParameterSet-based search space:**
-
         ```{python}
+        # 2 — ParameterSet-based search space:
+        import numpy as np
+        import pandas as pd
+        from sklearn.linear_model import Ridge
         from spotoptim.hyperparameters import ParameterSet
+        from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
+        from spotforecast2_safe.splitter import TimeSeriesFold
+        from spotforecast2.model_selection import spotoptim_search_forecaster
+
+        np.random.seed(42)
+        y = pd.Series(
+            np.random.randn(200).cumsum(),
+            index=pd.date_range("2022-01-01", periods=200, freq="h"),
+            name="load",
+        )
+        cv = TimeSeriesFold(steps=5, initial_train_size=150, refit=False)
 
         ps = ParameterSet()
         _ = ps.add_float("alpha", low=0.01, high=10.0)
@@ -309,9 +311,8 @@ def spotoptim_objective(
         np.ndarray: 1D array of results for the primary metric.
 
     Examples:
-        Generating textual output of parameter evaluation:
-
         ```{python}
+        # Demonstrate the call structure of spotoptim_objective.
         import numpy as np
         import pandas as pd
         from spotforecast2_safe.splitter import TimeSeriesFold
@@ -550,9 +551,23 @@ def spotoptim_search(
     all_lags: list = []
     all_params: list[dict] = []
 
+    # Single trial-level progress bar. Each entry in ``X`` is one trial
+    # (initial design point or sequential proposal), so we advance by
+    # ``len(X)`` per objective call. ``n_trials`` (== SpotOptim's
+    # ``max_iter``) is the total budget — it already includes the
+    # ``n_initial`` design points, so the total bar length is ``n_trials``.
+    # The inner backtesting fold loop is forced silent below to avoid the
+    # per-trial bar spam that used to stack dozens of fast "100% 35/35"
+    # bars in notebook output.
+    trial_bar = (
+        tqdm(total=n_trials, desc="SpotOptim trials", leave=True)
+        if show_progress
+        else None
+    )
+
     # --- Objective function -----------------------------------------------
     def _objective_wrapper(X: np.ndarray) -> np.ndarray:
-        return spotoptim_objective(
+        result = spotoptim_objective(
             X=X,
             forecaster_search=forecaster_search,
             cv_name=cv_name,
@@ -562,7 +577,7 @@ def spotoptim_search(
             exog=exog,
             n_jobs=n_jobs,
             verbose=verbose,
-            show_progress=show_progress,
+            show_progress=False,
             suppress_warnings=suppress_warnings,
             var_name=var_name,
             var_type=var_type,
@@ -571,6 +586,9 @@ def spotoptim_search(
             all_lags=all_lags,
             all_params=all_params,
         )
+        if trial_bar is not None:
+            trial_bar.update(len(X))
+        return result
 
     # --- Run SpotOptim ----------------------------------------------------
     optimizer = SpotOptim(
@@ -586,7 +604,11 @@ def spotoptim_search(
         **kwargs_spotoptim_,
     )
 
-    optimizer.optimize()
+    try:
+        optimizer.optimize()
+    finally:
+        if trial_bar is not None:
+            trial_bar.close()
 
     # --- Build results DataFrame ------------------------------------------
     lags_list = [
@@ -652,21 +674,20 @@ def convert_search_space(
         - var_trans: List of transformation functions (e.g., log10) or None.
 
     Examples:
-        Basic usage:
-
-        >>> from spotoptim.hyperparameters import ParameterSet
-        >>> from spotforecast2.model_selection.spotoptim_search import (
-        ...     convert_search_space,
-        ... )
-        >>> ps = ParameterSet()
-        >>> _ = ps.add_float("alpha", 0.01, 10.0)
-        >>> b, t, n, tr = convert_search_space(ps)
-        >>> b
-        [(0.01, 10.0)]
-        >>> t
-        ['float']
-
-        Converting a complex dictionary search space:
+        ```{python}
+        from spotoptim.hyperparameters import ParameterSet
+        from spotforecast2.model_selection.spotoptim_search import (
+            convert_search_space,
+        )
+
+        ps = ParameterSet()
+        _ = ps.add_float("alpha", 0.01, 10.0)
+        b, t, n, tr = convert_search_space(ps)
+        print(b)
+        assert b == [(0.01, 10.0)]
+        print(t)
+        assert t == ["float"]
+        ```
 
         ```{python}
         from spotforecast2.model_selection.spotoptim_search import convert_search_space
@@ -674,7 +695,7 @@ def convert_search_space(
         search_space = {
             "learning_rate": (0.001, 0.1, "log10"),
             "max_depth": (2, 10),
-            "model_type": ["RandomForest", "XGBoost"]
+            "model_type": ["RandomForest", "XGBoost"],
         }
 
         bounds, vt, vn, vtr = convert_search_space(search_space)
@@ -764,21 +785,21 @@ def array_to_params(
         Dictionary mapping parameter names to typed values.
 
     Examples:
-        Basic usage:
-
-        >>> import numpy as np
-        >>> from spotforecast2.model_selection.spotoptim_search import (
-        ...     array_to_params,
-        ... )
-        >>> array_to_params(
-        ...     np.array([100.0, 0.05]),
-        ...     var_name=["n_estimators", "lr"],
-        ...     var_type=["int", "float"],
-        ...     bounds=[(50, 200), (0.01, 0.3)],
-        ... )
-        {'n_estimators': 100, 'lr': 0.05}
-
-        Generating textual output of parameter mapping:
+        ```{python}
+        import numpy as np
+        from spotforecast2.model_selection.spotoptim_search import (
+            array_to_params,
+        )
+
+        result = array_to_params(
+            np.array([100.0, 0.05]),
+            var_name=["n_estimators", "lr"],
+            var_type=["int", "float"],
+            bounds=[(50, 200), (0.01, 0.3)],
+        )
+        print(result)
+        assert result == {"n_estimators": 100, "lr": 0.05}
+        ```
 
         ```{python}
         import numpy as np

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/src/spotforecast2/model_selection/utils_metrics.py

@@ -38,34 +38,40 @@ def _calculate_metrics_one_step_ahead(
         rolling features.
 
     Examples:
-        >>> import pandas as pd
-        >>> import numpy as np
-        >>> from sklearn.linear_model import LinearRegression
-        >>> from sklearn.metrics import mean_squared_error
-        >>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
-        >>> from spotforecast2.model_selection.utils_metrics import _calculate_metrics_one_step_ahead
-        >>>
-        >>> forecaster = ForecasterRecursive(LinearRegression(), lags=2)
-        >>>
-        >>> # Mock training data (already transformed into predictors/target)
-        >>> X_train = pd.DataFrame(np.array([[1, 2], [2, 3], [3, 4]]), columns=['lag_2', 'lag_1'])
-        >>> y_train = pd.Series(np.array([3, 4, 5]), name='y')
-        >>>
-        >>> # Mock test data
-        >>> X_test = pd.DataFrame(np.array([[4, 5]]), columns=['lag_2', 'lag_1'])
-        >>> y_test = pd.Series(np.array([6]), name='y')
-        >>>
-        >>> metrics = [mean_squared_error]
-        >>> result = _calculate_metrics_one_step_ahead(
-        ...     forecaster=forecaster,
-        ...     metrics=metrics,
-        ...     X_train=X_train,
-        ...     y_train=y_train,
-        ...     X_test=X_test,
-        ...     y_test=y_test
-        ... )
-        >>> print(result)
-        [0.0]
+        ```{python}
+        import numpy as np
+        import pandas as pd
+        from sklearn.linear_model import LinearRegression
+        from sklearn.metrics import mean_absolute_error
+        from spotforecast2_safe.forecaster.metrics import add_y_train_argument
+        from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
+        from spotforecast2.model_selection.utils_metrics import (
+            _calculate_metrics_one_step_ahead,
+        )
+
+        # Predictors are already extracted lag features; y = x+1 (linear).
+        X_train = pd.DataFrame(
+            {"lag_2": [1.0, 2.0, 3.0, 4.0, 5.0], "lag_1": [2.0, 3.0, 4.0, 5.0, 6.0]}
+        )
+        y_train = pd.Series([3.0, 4.0, 5.0, 6.0, 7.0], name="y")
+        X_test = pd.DataFrame({"lag_2": [5.0], "lag_1": [6.0]})
+        # Deliberately set y_test=9.0 (model predicts 7.0) to get MAE=2.0.
+        y_test = pd.Series([9.0], name="y")
+
+        forecaster = ForecasterRecursive(LinearRegression(), lags=2)
+        # Metrics must accept y_train; use add_y_train_argument to wrap sklearn metrics.
+        metrics = [add_y_train_argument(mean_absolute_error)]
+        result = _calculate_metrics_one_step_ahead(
+            forecaster=forecaster,
+            metrics=metrics,
+            X_train=X_train,
+            y_train=y_train,
+            X_test=X_test,
+            y_test=y_test,
+        )
+        print(f"MAE: {result[0]:.4f}")
+        assert result[0] == 2.0
+        ```
     """
 
     if type(forecaster).__name__ == "ForecasterDirect":

{spotforecast2-2.2.2 → spotforecast2-2.2.3}/src/spotforecast2/models/forecaster_recursive_lgbm_full.py

@@ -3,20 +3,21 @@
 
 """LGBM forecaster with real Bayesian tuning and SHAP.
 
-This module provides :class:`ForecasterRecursiveLGBMFull`, which combines
+This module provides `ForecasterRecursiveLGBMFull`, which combines
 the LightGBM forecaster from ``spotforecast2-safe`` with Bayesian
 hyperparameter optimisation (Optuna) and SHAP-based feature importance
-from :class:`~spotforecast2.models.ForecasterRecursiveModelFull`.
+from `ForecasterRecursiveModelFull`.
 
 Examples:
-    >>> from spotforecast2.models import ForecasterRecursiveLGBMFull
-    >>> model = ForecasterRecursiveLGBMFull(iteration=0)
-    >>> model.name
-    'lgbm'
-    >>> model.forecaster is not None
-    True
-    >>> model.n_trials
-    10
+    ```{python}
+    from spotforecast2.models import ForecasterRecursiveLGBMFull
+
+    model = ForecasterRecursiveLGBMFull(iteration=0)
+    assert model.name == "lgbm"
+    assert model.forecaster is not None
+    assert model.n_trials == 10
+    print(f"name={model.name}, n_trials={model.n_trials}, iteration={model.iteration}")
+    ```
 """
 
 from __future__ import annotations
@@ -35,12 +36,12 @@ class ForecasterRecursiveLGBMFull(
     """LGBM forecaster with real Bayesian tuning and SHAP.
 
     Inherits the LightGBM forecaster initialisation from
-    :class:`~spotforecast2_safe.forecaster.wrappers.lgbm.ForecasterRecursiveLGBM`
-    (``spotforecast2-safe``) and adds the real :meth:`tune` and
-    :meth:`get_global_shap_feature_importance` from
-    :class:`~spotforecast2.models.ForecasterRecursiveModelFull`.
+    `ForecasterRecursiveLGBM`
+    (``spotforecast2-safe``) and adds the real `tune()` and
+    `get_global_shap_feature_importance()` from
+    `ForecasterRecursiveModelFull`.
 
-    The MRO ensures that :meth:`tune` and SHAP methods resolve from
+    The MRO ensures that `tune()` and SHAP methods resolve from
     ``ForecasterRecursiveModelFull``, while the LightGBM-specific
     ``__init__`` (estimator wiring) comes from ``ForecasterRecursiveLGBM``.
 
@@ -51,25 +52,18 @@ class ForecasterRecursiveLGBMFull(
             ``predict_size``, ``train_size``).
 
     Examples:
-        >>> from spotforecast2.models import ForecasterRecursiveLGBMFull
-        >>> model = ForecasterRecursiveLGBMFull(iteration=0)
-        >>> model.name
-        'lgbm'
-        >>> model.forecaster is not None
-        True
-        >>> model.n_trials
-        10
-        >>> model.iteration
-        0
+        ```{python}
+        from spotforecast2.models import ForecasterRecursiveLGBMFull
 
-    ```{python}
-    from spotforecast2.models import ForecasterRecursiveLGBMFull
-    model = ForecasterRecursiveLGBMFull(iteration=0)
-    print(f"Model name: {model.name}")
-    print(f"Trials: {model.n_trials}")
-    print(f"Has tune: {callable(model.tune)}")
-    print(f"Has SHAP: {callable(model.get_global_shap_feature_importance)}")
-    ```
+        model = ForecasterRecursiveLGBMFull(iteration=0)
+        assert model.name == "lgbm"
+        assert model.forecaster is not None
+        assert model.n_trials == 10
+        assert model.iteration == 0
+        print(f"name={model.name}, n_trials={model.n_trials}, iteration={model.iteration}")
+        print(f"tune callable: {callable(model.tune)}")
+        print(f"shap callable: {callable(model.get_global_shap_feature_importance)}")
+        ```
     """
 
     def __init__(self, iteration: int, lags: int = 12, **kwargs: Any):