[ENH] skforecast integration for time series hyperparameter tuning

docs/source/examples.rst

@@ -19,6 +19,7 @@ on GitHub.
    examples/sequential_model_based
    examples/optuna_backend
    examples/sklearn_backend
+    examples/skforecast_integration
    examples/integrations
    examples/other
    examples/interactive_tutorial
@@ -72,6 +73,10 @@ Integration Examples
 :ref:`examples_integrations`
     Time series optimization with sktime and other framework integrations.
 
+:ref:`examples_skforecast_integration`
+    Forecasting hyperparameter tuning with ``SkforecastOptCV`` and
+    ``ForecasterRecursive``.
+
 
 Advanced Topics
 ^^^^^^^^^^^^^^^

docs/source/examples/integrations.rst

@@ -24,6 +24,21 @@ For time series forecasting and classification with sktime:
    * - Time Series Classification
      - `sktime_tsc_example.py <https://github.com/SimonBlanke/Hyperactive/blob/master/examples/integrations/sktime_tsc_example.py>`_
 
+
+Skforecast Integration
+----------------------
+
+For direct ``skforecast`` forecasting optimization:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Use Case
+     - Example
+   * - Recursive forecasting with ``SkforecastOptCV``
+     - `skforecast_example.py <https://github.com/SimonBlanke/Hyperactive/blob/master/examples/skforecast/skforecast_example.py>`_
+
 .. note::
 
    Sktime integration requires additional dependencies:
@@ -43,6 +58,9 @@ Install integration extras as needed:
     # Sktime/skpro for time series
     pip install hyperactive[sktime-integration]
 
+    # Skforecast integration
+    pip install hyperactive[skforecast-integration]
+
     # All extras including PyTorch Lightning
     pip install hyperactive[all_extras]
 

docs/source/examples/skforecast_integration.rst

@@ -0,0 +1,48 @@
+.. _examples_skforecast_integration:
+
+=====================
+Skforecast Integration
+=====================
+
+Hyperactive integrates with ``skforecast`` to tune forecasting models with any
+Hyperactive optimizer.
+
+
+Example File
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Use Case
+     - Example
+   * - Forecasting with ``SkforecastOptCV``
+     - `skforecast_example.py <https://github.com/SimonBlanke/Hyperactive/blob/master/examples/skforecast/skforecast_example.py>`_
+
+
+Installation
+------------
+
+Install the optional integration dependency:
+
+.. code-block:: bash
+
+    pip install hyperactive[skforecast-integration]
+
+.. note::
+
+   ``skforecast`` currently requires Python < 3.14.
+
+
+Usage Overview
+--------------
+
+The example below shows the sklearn-like ``fit``/``predict`` workflow with
+``SkforecastOptCV``:
+
+.. literalinclude:: ../../../examples/skforecast/skforecast_example.py
+   :language: python
+
+
+See :ref:`user_guide_integrations` for the full integration overview.

docs/source/user_guide.rst

@@ -91,7 +91,7 @@ Guide Contents
     Includes custom functions and built-in ML experiments.
 
 :ref:`user_guide_integrations`
-    Framework integrations for scikit-learn, sktime, skpro, and PyTorch.
+    Framework integrations for scikit-learn, sktime, skforecast, skpro, and PyTorch.
     Drop-in replacements for GridSearchCV and similar tools.
 
 :ref:`user_guide_migration`

docs/source/user_guide/integrations.rst

@@ -78,6 +78,23 @@ Use ``TSCOptCV`` for time series classification:
    :end-before: # [end:tsc_optcv]
 
 
+Time Series with Skforecast
+---------------------------
+
+Hyperactive also integrates with ``skforecast`` for recursive forecasting
+workflows.
+
+.. note::
+
+   Requires ``pip install hyperactive[skforecast-integration]``
+
+The following example shows ``SkforecastOptCV`` with
+``ForecasterRecursive``:
+
+.. literalinclude:: ../../../examples/skforecast/skforecast_example.py
+   :language: python
+
+
 Probabilistic Prediction with Skpro
 -----------------------------------
 
@@ -123,6 +140,9 @@ Choosing the Right Integration
    * - sktime
      - ``TSCOptCV``
      - Time series classification
+    * - skforecast
+       - ``SkforecastOptCV``
+       - Recursive time series forecasting
    * - skpro
      - ``SkproProbaRegExperiment``
      - Probabilistic regression

examples/skforecast/skforecast_example.py

@@ -0,0 +1,63 @@
+"""
+Skforecast Integration Example - Hyperparameter Tuning for Time Series Forecasting
+
+This example demonstrates how to use Hyperactive to tune hyperparameters of a
+skforecast ForecasterRecursive model. It uses the SkforecastOptCV class which
+provides a familiar sklearn-like API for integrating skforecast models with
+Hyperactive's optimization algorithms.
+
+Characteristics:
+- Integration with skforecast's backtesting functionality
+- Tuning of regressor hyperparameters (e.g., RandomForestRegressor)
+- Uses HillClimbing optimizer (can be swapped for any Hyperactive optimizer)
+- Time series cross-validation via backtesting
+"""
+
+import numpy as np
+import pandas as pd
+from skforecast.recursive import ForecasterRecursive
+from sklearn.ensemble import RandomForestRegressor
+from hyperactive.opt import HillClimbing
+from hyperactive.integrations.skforecast import SkforecastOptCV
+
+# Generate synthetic data
+data = pd.Series(
+    np.random.randn(100),
+    index=pd.date_range(start="2020-01-01", periods=100, freq="D"),
+    name="y",
+)
+
+# Define forecaster
+forecaster = ForecasterRecursive(
+    regressor=RandomForestRegressor(random_state=123), lags=5
+)
+
+# Define optimizer
+optimizer = HillClimbing(
+    search_space={
+        "n_estimators": list(range(10, 100, 10)),
+        "max_depth": list(range(2, 10)),
+    },
+    n_iter=10,
+)
+
+# Define SkforecastOptCV
+opt_cv = SkforecastOptCV(
+    forecaster=forecaster,
+    optimizer=optimizer,
+    steps=5,
+    metric="mean_squared_error",
+    initial_train_size=50,
+    verbose=True,
+)
+
+# Fit
+print("Fitting...")
+opt_cv.fit(y=data)
+
+# Predict
+print("Predicting...")
+predictions = opt_cv.predict(steps=5)
+print("Predictions:")
+print(predictions)
+print("Best params:", opt_cv.best_params_)

pyproject.toml

@@ -52,6 +52,16 @@ sklearn-integration = [
 sktime-integration = [
   "skpro",
   'sktime; python_version < "3.14"',
+  'skforecast; python_version < "3.14"',
+]
+skforecast-integration = [
+  'skforecast; python_version < "3.14"',
+]
+integrations = [
+  "scikit-learn <1.8.0",
+  "skpro",
+  'sktime; python_version < "3.14"',
+  'skforecast; python_version < "3.14"',
 ]
 build = [
   "setuptools",
@@ -87,7 +97,6 @@ all_extras = [
   "lightning",
 ]
 
-
 [project.urls]
 "Homepage" = "https://github.com/SimonBlanke/Hyperactive"
 "Bug Reports" = "https://github.com/SimonBlanke/Hyperactive/issues"

src/hyperactive/experiment/integrations/__init__.py

@@ -1,6 +1,9 @@
 """Integrations with packages for tuning."""
 # copyright: hyperactive developers, MIT License (see LICENSE file)
 
+from hyperactive.experiment.integrations.skforecast_forecasting import (
+    SkforecastExperiment,
+)
 from hyperactive.experiment.integrations.sklearn_cv import SklearnCvExperiment
 from hyperactive.experiment.integrations.skpro_probareg import (
     SkproProbaRegExperiment,
@@ -20,5 +23,6 @@
     "SkproProbaRegExperiment",
     "SktimeClassificationExperiment",
     "SktimeForecastingExperiment",
+    "SkforecastExperiment",
     "TorchExperiment",
 ]