https://github.com/stateful-y/yohou
A time series forecasting package based on Scikit-Learn and Polars
https://github.com/stateful-y/yohou
forecasting ml scikit-learn time-series
Last synced: 2 months ago
JSON representation
A time series forecasting package based on Scikit-Learn and Polars
- Host: GitHub
- URL: https://github.com/stateful-y/yohou
- Owner: stateful-y
- License: apache-2.0
- Created: 2026-02-07T22:21:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T19:49:22.000Z (2 months ago)
- Last Synced: 2026-04-11T22:58:24.012Z (2 months ago)
- Topics: forecasting, ml, scikit-learn, time-series
- Language: Python
- Homepage: https://yohou.readthedocs.io/en/latest/
- Size: 2.35 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://pypi.org/project/yohou/)
[](https://github.com/stateful-y/yohou/blob/main/LICENSE)
[](https://pypi.org/project/yohou/)
[](https://anaconda.org/conda-forge/yohou)
[](https://codecov.io/gh/stateful-y/yohou)
## What is Yohou?
Yohou is a Scikit-Learn-compatible time series forecasting framework built on [Polars](https://pola.rs/). It treats forecasting as a supervised learning reduction problem: wrap any sklearn regressor and Yohou handles windowing, tabularization, and recursive prediction while preserving temporal structure. It supports both point and interval forecasting with native panel data capabilities.
Yohou extends sklearn's API with time series-specific operations (`observe`, `rewind`, `observe_predict`) so fitted forecasters can ingest new data incrementally without retraining. After fitting, every forecaster exposes the same `predict` / `predict_interval` / `observe_predict` interface whether it wraps a simple baseline or a full decomposition pipeline.
Currently, Yohou supports Python 3.11+.
## What are the features of Yohou?
- **Reduction forecasting**: Wrap any Scikit-Learn regressor (`Ridge`, `XGBRegressor`, ...) and Yohou tabularizes, fits, and predicts recursively via `PointReductionForecaster` and `IntervalReductionForecaster`.
- **Incremental observation**: Call `observe()` to feed new data, `rewind()` to roll back state, and `observe_predict()` to fast-forward and forecast in one step, no refitting required.
- **Composable pipelines**: Chain trend, seasonality, and residual forecasters with `DecompositionPipeline`, or build feature pipelines with `FeaturePipeline`, `FeatureUnion`, and `ColumnTransformer`.
- **Preprocessing & stationarity**: Lag, rolling, and EMA window transforms, signal filters, sklearn scaler wrappers, imputation, outlier handling, and stationarity transforms like `SeasonalDifferencing`, `BoxCoxTransformer`, and Fourier seasonality estimation.
- **Panel data support**: Prefix columns with `group__` and forecasters, transformers, and metrics operate across all groups automatically. Use `ColumnForecaster` or `LocalPanelForecaster` for per-group models.
- **Interval forecasting**: Get calibrated prediction intervals via `SplitConformalForecaster`, `IntervalReductionForecaster` with `DistanceSimilarity`, and conformity scorers.
- **Time-weighted training**: Weight recent or seasonal observations with `exponential_decay_weight`, `linear_decay_weight`, `seasonal_emphasis_weight`, and `compose_weights`, propagated via sklearn metadata routing.
- **Cross-validation & tuning**: Temporal splitters (`ExpandingWindowSplitter`, `SlidingWindowSplitter`) and `GridSearchCV` / `RandomizedSearchCV` designed for time series with no data leakage across time.
- **Metrics & visualization**: Point and interval scorers with timewise, componentwise, and groupwise aggregation. Plotly-based plotting functions for exploration, diagnostics, forecasting, and evaluation.
- **Remote datasets**: Eight `fetch_*` functions download Monash/Zenodo time series on demand (`tourism_monthly`, `sunspot`, `tourism_quarterly`, `electricity_demand`, `dominick`, `pedestrian_counts`, `hospital`, `kdd_cup`) with local Parquet caching.
## How to install Yohou?
Install the Yohou package using `pip`:
```bash
pip install yohou
```
or using `uv`:
```bash
uv pip install yohou
```
or using `conda`:
```bash
conda install -c conda-forge yohou
```
or using `mamba`:
```bash
mamba install -c conda-forge yohou
```
or alternatively, add `yohou` to your `requirements.txt` or `pyproject.toml` file.
## How to get started with Yohou?
### 1. Load data and split
Yohou datasets are fetched from [Monash/Zenodo](https://forecastingdata.org) and return a `Bunch` with a `.frame` attribute (a Polars DataFrame with a `"time"` column).
```python
from yohou.datasets import fetch_tourism_monthly
bunch = fetch_tourism_monthly()
y = bunch.frame.select("time", "T1__tourists").rename({"T1__tourists": "tourists"})
y_train, y_test = y[:280], y[280:]
```
### 2. Fit a forecaster
Wrap an sklearn regressor in a `PointReductionForecaster` with preprocessing pipelines.
```python
from sklearn.linear_model import Ridge
from yohou.compose import FeaturePipeline
from yohou.point import PointReductionForecaster
from yohou.preprocessing import LagTransformer
from yohou.stationarity import LogTransformer, SeasonalDifferencing
forecaster = PointReductionForecaster(
estimator=Ridge(alpha=10),
target_transformer=FeaturePipeline([
("log", LogTransformer(offset=1.0)),
("diff", SeasonalDifferencing(seasonality=12)),
]),
feature_transformer=FeaturePipeline([
("lag", LagTransformer(lag=[1, 2, 3])),
]),
)
forecaster.fit(y_train, X=None, forecasting_horizon=len(y_test))
```
### 3. Predict and evaluate
After fitting, call `predict` and score against the held-out data.
```python
from yohou.metrics import MeanAbsoluteError
from yohou.plotting import plot_forecast
y_pred = forecaster.predict(forecasting_horizon=len(y_test))
scorer = MeanAbsoluteError()
scorer.fit(y_train)
scorer.score(y_test, y_pred)
plot_forecast(y_test, y_pred, y_train=y_train)
```
## How do I use Yohou?
Full documentation is available at [https://yohou.readthedocs.io/](https://yohou.readthedocs.io/).
Interactive examples are available in the `examples/` directory:
- **Online**: [https://yohou.readthedocs.io/en/latest/pages/examples/](https://yohou.readthedocs.io/en/latest/pages/examples/)
- **Locally**: Run `marimo edit examples/quickstart.py` to open an interactive notebook
## Can I contribute?
We welcome contributions, feedback, and questions:
- **Report issues or request features**: [GitHub Issues](https://github.com/stateful-y/yohou/issues)
- **Join the discussion**: [GitHub Discussions](https://github.com/stateful-y/yohou/discussions)
- **Contributing Guide**: [CONTRIBUTING.md](https://github.com/stateful-y/yohou/blob/main/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](https://github.com/stateful-y/yohou/discussions).
## Where can I learn more?
Here are the main Yohou resources:
- Full documentation: [https://yohou.readthedocs.io/](https://yohou.readthedocs.io/)
- GitHub Discussions: [https://github.com/stateful-y/yohou/discussions](https://github.com/stateful-y/yohou/discussions)
- Interactive Examples: [https://yohou.readthedocs.io/en/latest/pages/examples/](https://yohou.readthedocs.io/en/latest/pages/examples/)
For questions and discussions, you can also open a [discussion](https://github.com/stateful-y/yohou/discussions).
## License
This project is licensed under the terms of the [Apache-2.0 License](https://github.com/stateful-y/yohou/blob/main/LICENSE).
