yohou 0.1.0a4

A time series forecasting package based on Scikit-Learn and Polars

What is Yohou?

Yohou is a Scikit-Learn-compatible time series forecasting framework built on Polars. 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 stepwise, vintagewise, 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:

pip install yohou

or using uv:

uv pip install yohou

or using conda:

conda install -c conda-forge yohou

or using mamba:

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 and return a Bunch with a .frame attribute (a Polars DataFrame with a "time" column).

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.

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.

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/.

Interactive examples are available in the examples/ directory:

• Online: 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
• 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 resources:

• Full documentation: https://yohou.readthedocs.io/
• GitHub Discussions: https://github.com/stateful-y/yohou/discussions
• Interactive Examples: https://yohou.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.