twiga 1.0.0

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

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.

Extra	What it adds
plots	Matplotlib, Plotly, SciencePlots (publication-quality & interactive charts)
nn	PyTorch, Lightning, TorchMetrics, TensorBoard
explain	SHAP feature attribution
mlops	MLflow, FastAPI, Evidently, Prefect
all	Everything above

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:

CUDA version	Suffix
11.8	cu118
12.1	cu121
12.4	cu124
12.6	cu126

Run nvidia-smi to check your CUDA version.

---

What Twiga offers

Feature	Description
🔀 One interface, every model	Swap a gradient-boosted tree for a neural network by changing one config object, not rewriting code
📊 Probabilistic forecasting	Quantile regression, parametric distributions (Normal, Laplace, LogNormal, Gamma, Beta, Student-t) and conformal prediction, all composable with any backbone
🎯 Calibrated uncertainty	Conformal prediction wraps any trained model with finite-sample coverage guarantees, no retraining required
⚙️ Experiment-ready	Pydantic configs wired directly to Optuna search spaces; time-based backtesting and checkpoint-based resume are first-class features
🔍 Feature intelligence	Eight association measures fused with Borda-count rank aggregation; stationarity tests, entropy and residual diagnostics in one call
🚀 Production MLOps	Optional stack with experiment tracking, versioned checkpoints, drift monitoring, REST API and automated retraining

---

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

Section	Description
Get Started	Install, key concepts, and your first forecast
User Guide	Forecaster API, data pipeline, metrics, backtesting
Models	ML tree models, neural networks, HPO
Probabilistic	Distributions, quantile regression, conformal prediction
Tutorials	End-to-end Jupyter notebooks
MLOps	Tracking, serving, monitoring, orchestration
API Reference	Full API reference

---

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