Environment:Sktime Pytorch forecasting Optuna Tuning Dependencies
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Hyperparameter_Optimization |
| Last Updated | 2026-02-08 08:00 GMT |
Overview
Optional dependency set providing Optuna >= 3.1.0, optuna-integration, and statsmodels for automated hyperparameter optimization of TFT models.
Description
This environment adds the packages required by the `optimize_hyperparameters` function in `pytorch_forecasting.models.temporal_fusion_transformer.tuning`. Optuna provides the Bayesian hyperparameter search framework, optuna-integration provides the `PyTorchLightningPruningCallback` for trial pruning, and statsmodels is used for statistical analysis of results. The module also includes a monkey-patch for scipy compatibility with statsmodels.
Usage
Required when calling optimize_hyperparameters() for automated TFT hyperparameter tuning. Not needed for manual model configuration or training. Install via `pip install pytorch-forecasting[tuning]`.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux or macOS | Hyperparameter tuning tests are skipped on Windows |
| Hardware | Same as core | No additional hardware requirements |
| Python | >= 3.10 | Same as core package |
Dependencies
Python Packages
- `optuna` >= 3.1.0, < 5.0.0
- `optuna-integration` (required from optuna 3.3.0+)
- `statsmodels` (no version constraint specified)
Credentials
No credentials are required.
Quick Install
# Install with tuning extras
pip install pytorch-forecasting[tuning]
# Or install individually
pip install optuna>=3.1.0 optuna-integration statsmodels
Code Evidence
Soft dependency check from `models/temporal_fusion_transformer/tuning.py:111-121`:
if not _check_soft_dependencies(["optuna", "statsmodels"], severity="none"):
raise ImportError(
"optimize_hyperparameters requires optuna and statsmodels. "
"Please install these packages with `pip install optuna statsmodels`. "
"From optuna 3.3.0, optuna-integration is also required."
)
import optuna
from optuna.integration import PyTorchLightningPruningCallback
import optuna.logging
import statsmodels.api as sm
Scipy compatibility monkey-patch from `tuning.py:26-43`:
# ToDo: remove this once statsmodels release a version compatible with latest
# scipy version
def _lazywhere(cond, arrays, f, fillvalue=np.nan, f2=None):
"""Backported lazywhere implementation (basic version)."""
...
scipy._lib._util._lazywhere = _lazywhere
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: optimize_hyperparameters requires optuna and statsmodels` | Missing optional dependencies | `pip install pytorch-forecasting[tuning]` |
| `ImportError: optuna.integration` | optuna >= 3.3.0 without optuna-integration | `pip install optuna-integration` |
| `AttributeError: scipy._lib._util._lazywhere` | statsmodels/scipy version mismatch | The library patches this automatically; ensure pytorch-forecasting is up to date |
Compatibility Notes
- Windows: Hyperparameter tuning tests are skipped on Windows due to DDP compatibility issues.
- scipy compatibility: The tuning module includes a monkey-patch for `scipy._lib._util._lazywhere` to work around a statsmodels/scipy version mismatch. This is applied at import time and should be transparent.