Twiga Forecast

Point & probabilistic time series forecasting — one interface, every model.

"Twiga" means giraffe in Swahili 🦒

Documentation · Tutorials · API Reference · PyPI

Most forecasting libraries force a choice — ML or deep learning, point forecasts or probabilistic ones, flexibility or production readiness. Twiga removes that trade-off.

A single TwigaForecaster trains, tunes, evaluates and backtests gradient-boosted trees, neural networks, quantile regression, parametric distributions and conformal prediction through one consistent, config-driven API.

Installation

# Core (tree models + lets-plot + great-tables)
pip install twiga

# + Matplotlib, Plotly, SciencePlots
pip install "twiga[plots]"

# + Neural networks (PyTorch Lightning)
pip install "twiga[nn]"

# Everything
pip install "twiga[all]"

Batteries included — XGBoost, LightGBM, CatBoost, NGBoost, lets-plot and Great Tables ship with the base install.

GPU (CUDA) support for neural networks

The default twiga[nn] install pulls the CPU-only PyTorch wheel from PyPI. To use a GPU, point your installer at the PyTorch CUDA index instead:

# pip
pip install "twiga[nn]" --extra-index-url https://download.pytorch.org/whl/cu124

# uv  (--index-strategy required so uv falls back to PyPI for non-torch packages)
uv pip install "twiga[nn]" \
  --extra-index-url https://download.pytorch.org/whl/cu124 \
  --index-strategy unsafe-best-match

Replace cu124 with the suffix that matches your driver:

Run nvidia-smi to check your CUDA version.

What Twiga offers

Quick start

import pandas as pd
from twiga.forecaster.core import TwigaForecaster
from twiga.core.config import DataPipelineConfig, ForecasterConfig
from twiga.models.ml.lightgbm_model import LIGHTGBMConfig

# train_df / test_df are pandas DataFrames with a DatetimeIndex
forecaster = TwigaForecaster(
    data_params=DataPipelineConfig(target_feature="load_mw", forecast_horizon=48),
    model_params=[LIGHTGBMConfig()],
    train_params=ForecasterConfig(split_freq="days", train_size=14, test_size=7),
)
forecaster.fit(train_df=train_df)
predictions_df, metrics_df = forecaster.evaluate_point_forecast(test_df=test_df)

Switch to a neural network by swapping one config:

from twiga.models.nn.mlpgam_model import MLPGAMConfig

forecaster = TwigaForecaster(
    data_params=DataPipelineConfig(target_feature="load_mw", forecast_horizon=48),
    model_params=[MLPGAMConfig()],
    train_params=ForecasterConfig(split_freq="days", train_size=14, test_size=7),
)

See the tutorials for probabilistic forecasting, conformal prediction, backtesting, HPO, and MLOps examples.

Documentation

Contributing

Bug reports and feature requests are welcome — please open an issue. Pull requests should target the main branch and pass the pre-commit checks (uv run pre-commit run --all-files).

Contributors

Thanks goes to these wonderful people:

Anthony Faustine

Frederick Apina

Lucas Pereira

References

1. A. Faustine, N. J. Nunes and L. Pereira, "Efficiency through Simplicity: MLP-based Approach for Net-Load Forecasting with Uncertainty Estimates," IEEE Transactions on Power Systems, doi: 10.1109/TPWRS.2024.3400123.
2. A. Faustine and L. Pereira, "FPSeq2Q: Fully Parameterized Sequence to Quantile Regression for Net-Load Forecasting With Uncertainty Estimates," IEEE Transactions on Smart Grid, vol. 13, no. 3, pp. 2440-2451, May 2022, doi: 10.1109/TSG.2022.3148699.
3. A. Faustine and L. Pereira, "Conformal Multilayer Perceptron-Based Probabilistic Net-Load Forecasting for Low-Voltage Distribution Systems with Photovoltaic Generation," 2024 IEEE International Conference on Communications, Control, and Computing Technologies for Smart Grids (SmartGridComm), Oslo, Norway, 2024, pp. 59-64, doi: 10.1109/SmartGridComm60555.2024.10738106.
4. A. Faustine and L. Pereira, "Enhancing LV System Resilience through Probabilistic Forecasting of Interdependent Variables: Voltage, Reactive and Active Power," CIRED Chicago Workshop 2024: Resilience of Electric Distribution Systems, Chicago, USA, 2025, pp. 27-31, doi: 10.1049/icp.2024.2555.

Apache 2.0 License · Built with ❤️ for energy & power systems forecasting