twiga 0.1.1

Twiga: A Python library for point and probabilistic forecasting, inspired by the majestic giraffes of Tanzania. Twiga helps you see the future with clarity and precision, offering powerful tools for time series forecasting using machine learning and neural network models.

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 (includes tree models + visualisation)
pip install twiga

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

# Everything
pip install "twiga[all]"

Batteries included - XGBoost, LightGBM, CatBoost, NGBoost, Matplotlib, lets-plot and Plotly ship with the base install.

Optional extras

Extra	What it adds
nn	PyTorch, Lightning, TorchMetrics, TensorBoard
explain	SHAP feature attribution
mlops	MLflow, FastAPI, Evidently, Prefect
all	Everything above

---

What Twiga offers

	Capability
	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) 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: experiment tracking, versioned checkpoints, drift monitoring, REST API and automated retraining

---

Quick start

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

data = pd.read_parquet("data/timeseries.parquet")

data_config = DataPipelineConfig(
    target_feature="load_mw",
    period="30min",
    lookback_window_size=48,
    forecast_horizon=48,
    calendar_features=["hour", "day_night"],
)

forecaster = TwigaForecaster(
    data_params=data_config,
    model_params=[LIGHTGBMConfig()],
    train_params=ForecasterConfig(split_freq="days", train_size=14, test_size=7),
)

forecaster.fit(train_df=train_df, val_df=val_df)
predictions_df, metrics_df = forecaster.evaluate_point_forecast(test_df=test_df)

📖 See the tutorials for probabilistic forecasting, 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

---

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