yohou-optuna 0.1.0a3

An Optuna integration for hyperparameter tuning in Yohou

What is Yohou-Optuna?

Yohou-Optuna brings Optuna's hyperparameter optimization to Yohou, providing a Yohou-compatible search class for time series forecasting.

This integration replaces grid and random search with adaptive sampling (TPE, CMA-ES, and more) while keeping Yohou's forecasting API intact. After fitting, OptunaSearchCV behaves like a Yohou forecaster, so you can call predict, observe, and observe_predict directly.

It integrates with Optuna's distributions, samplers, and storages, and wraps them for sklearn-style cloning and serialization.

What are the features of Yohou-Optuna?

• Adaptive optimization: Run Optuna studies over Yohou forecasters with TPE, CMA-ES, and other samplers to find better configurations in fewer trials.
• Forecaster-native API: OptunaSearchCV is a forecaster after fitting, so you can call predict, observe, observe_predict, and interval methods.
• Clone-safe wrappers: Sampler, Storage, and Callback wrappers ensure Optuna objects survive sklearn cloning and serialization.
• Time-series CV support: Works with Yohou splitters for proper temporal validation and scorer integration.
• Multi-metric evaluation: Evaluate multiple scorers and refit on the one that matters most for your use case.
• (Experimental) Persistence workflows: Resume studies with storage-backed optimization and continue tuning over time.

How to install Yohou-Optuna?

Install the Yohou-Optuna package using pip:

pip install yohou_optuna

or using uv:

uv pip install yohou_optuna

or using conda:

conda install -c conda-forge yohou_optuna

or using mamba:

mamba install -c conda-forge yohou_optuna

or alternatively, add yohou_optuna to your requirements.txt or pyproject.toml file.

How to get started with Yohou-Optuna?

1. Prepare a forecaster and search space

Define a Yohou forecaster and Optuna distributions for the parameters you want to tune.

from sklearn.linear_model import Ridge
from optuna.distributions import FloatDistribution, IntDistribution

from yohou.point import PointReductionForecaster
from yohou_optuna import OptunaSearchCV

forecaster = PointReductionForecaster(estimator=Ridge())
param_distributions = {
    "estimator__alpha": FloatDistribution(1e-4, 10.0, log=True),
    "observation_horizon": IntDistribution(3, 30),
}

search = OptunaSearchCV(
    forecaster=forecaster,
    param_distributions=param_distributions,
    n_trials=30,
)

2. Fit the searcher

Fit the searcher on your time series data (polars DataFrame with a time column).

search.fit(y_train, X_train, forecasting_horizon=12)

3. Predict with the best forecaster

After fitting, search behaves like a Yohou forecaster.

y_pred = search.predict(forecasting_horizon=12)
print(search.best_params_)

How do I use Yohou-Optuna?

Full documentation is available at https://yohou-optuna.readthedocs.io/.

Interactive examples are available in the examples/ directory:

• Online: https://yohou-optuna.readthedocs.io/en/latest/pages/examples/
• Locally: Run marimo edit examples/optuna_search.py to open an interactive notebook

Can I contribute?

We welcome contributions, feedback, and questions:

• Report issues or request features: GitHub Issues
• Join the discussion: GitHub Discussions
• Contributing Guide: CONTRIBUTING.md

If you are interested in becoming a maintainer or taking a more active role, please reach out to Guillaume Tauzin on GitHub Discussions.

Where can I learn more?

Here are the main Yohou-Optuna resources:

• Full documentation: https://yohou-optuna.readthedocs.io/
• GitHub Discussions: https://github.com/stateful-y/yohou-optuna/discussions
• Interactive Examples: https://yohou-optuna.readthedocs.io/en/latest/pages/examples/

For questions and discussions, you can also open a discussion.

License

This project is licensed under the terms of the Apache-2.0 License.

Acknowledgements

This project is maintained by stateful-y, an ML consultancy specializing in time series data science & engineering. If you're interested in collaborating or learning more about our services, please visit our website.