GluonTS

0.16.2 · active · verified Fri Apr 10

GluonTS is a Python toolkit for probabilistic time series modeling, providing facilities for loading datasets, defining models, training them, and making predictions. It supports various deep learning backends, with PyTorch being the currently recommended and most actively developed one. The library is actively maintained with frequent minor releases, currently at version 0.16.2.

Warnings

breaking The `pytorch-lightning` dependency often requires specific version alignment with GluonTS releases. Mismatched versions can lead to runtime errors, especially during training. For example, v0.16.0 included a `pytorch lightning compat` update.
Fix: Always check the official `pyproject.toml` or `setup.py` for the recommended `pytorch-lightning` version for your GluonTS installation. If issues arise, try downgrading or upgrading `pytorch-lightning` to the version specified by GluonTS.
deprecated The MXNet backend (`gluonts.mx`) is less actively maintained and developed compared to the PyTorch backend (`gluonts.torch`). New models and features are primarily added to the PyTorch ecosystem.
Fix: For new projects or when seeking the latest features and best support, strongly consider using `gluonts[torch]` and its associated models and utilities.
gotcha In older versions, `freq` string parsing could be inconsistent, leading to errors with certain frequency specifications or custom datasets. While fixed in v0.16.0, this was a common source of data loading issues.
Fix: Ensure `freq` strings conform to pandas frequency aliases (e.g., 'H', 'D', 'W', 'M', 'min'). For custom frequencies, verify against pandas documentation. Upgrade to 0.16.0 or later to benefit from fixes.
gotcha When constructing `PandasDataset` from `pandas.DataFrame.groupby` operations, a `FutureWarning` could be raised if `observed=True` was not explicitly passed to `groupby`. This was fixed in v0.16.1.
Fix: If using older versions or encountering this warning, explicitly pass `observed=True` to `DataFrame.groupby()` calls when preparing data for `PandasDataset`.
gotcha The `rpy2` dependency, used for R-based models, was capped at a specific version in v0.16.2 (`rpy2<3.5.11,>=3.4.5`). Mismatched `rpy2` versions can lead to installation failures or runtime errors when using R models.
Fix: If you install `gluonts[r]`, ensure `rpy2` adheres to the specified version range. If encountering issues, try installing `rpy2` explicitly to the compatible version before installing `gluonts[r]`.

Install

pip install gluonts[torch] Recommended installation with PyTorch backend
pip install gluonts[mxnet] Installation with MXNet backend (less actively maintained)

Imports

ListDataset

from gluonts.dataset.common import ListDataset

SimpleFeedForwardEstimator

from gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator

Trainer
```
from pytorch_lightning import Trainer
```
Since GluonTS v0.10.x, the Trainer is often imported directly from `pytorch_lightning` when using PyTorch models, rather than from GluonTS's internal wrappers. Ensure `pytorch-lightning` is installed and compatible.

make_evaluation_predictions

from gluonts.evaluation import make_evaluation_predictions

MSE
```
from gluonts.evaluation.backtest import make_evaluation_predictions, backtest_metrics
```
Metrics like MSE are typically accessed via `backtest_metrics` after evaluation, not imported directly as a class.
freqstr_to_timedelta
```
from gluonts.time_feature.util import freqstr_to_timedelta
```
Useful for understanding time frequency strings.

Quickstart

This quickstart demonstrates how to create a simple dataset, define and train a `SimpleFeedForwardEstimator` using the PyTorch backend, make predictions, and evaluate the model using `gluonts.evaluation`.

from gluonts.dataset.common import ListDataset
from gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator
from pytorch_lightning import Trainer
from gluonts.evaluation import make_evaluation_predictions, Evaluator
import pandas as pd
import numpy as np

# 1. Prepare Data
target_data = np.random.rand(100) # Dummy time series data
start_date = pd.Timestamp("2023-01-01", freq="H")

data_entry = {
    "start": start_date,
    "target": target_data,
    "item_id": "item_A"
}

training_data = ListDataset([data_entry],
                            freq="H")

# For evaluation, we need to split data into past and future
# In a real scenario, you'd have separate test data or perform backtesting
prediction_length = 24
full_data_entry = {
    "start": pd.Timestamp("2023-01-01", freq="H"),
    "target": np.concatenate([np.random.rand(80), np.random.rand(24)]), # 80 for training, 24 for future
    "item_id": "item_B"
}

# Simulate a test dataset by cutting off the prediction_length from the full series
test_data = ListDataset([{
    "start": full_data_entry["start"],
    "target": full_data_entry["target"][:-prediction_length],
    "feat_static_cat": [0],
    "item_id": full_data_entry["item_id"]
}], freq="H")

# 2. Define Estimator
estimator = SimpleFeedForwardEstimator(
    prediction_length=prediction_length,
    context_length=prediction_length * 2,
    trainer=Trainer(max_epochs=5, enable_checkpointing=False, enable_progress_bar=False, logger=False),
    num_hidden_dimensions=[10, 10]
)

# 3. Train the model
predictor = estimator.train(training_data=training_data)

# 4. Make Predictions
forecast_it, ts_it = make_evaluation_predictions(
    dataset=test_data,
    predictor=predictor,
    num_samples=100
)

forecasts = list(forecast_it)
ts = list(ts_it)

# 5. Evaluate
evaluator = Evaluator(quantiles=[0.1, 0.5, 0.9])
agg_metrics, item_metrics = evaluator(ts, forecasts, num_series=len(test_data))

print("Aggregated metrics:", agg_metrics)
print("First forecast (mean):")
print(forecasts[0].mean)

view raw JSON →