{"id":2519,"library":"gluonts","title":"GluonTS","description":"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.","status":"active","version":"0.16.2","language":"en","source_language":"en","source_url":"https://github.com/awslabs/gluonts/","tags":["time series","forecasting","deep learning","probabilistic","pytorch","machine learning"],"install":[{"cmd":"pip install gluonts[torch]","lang":"bash","label":"Recommended installation with PyTorch backend"},{"cmd":"pip install gluonts[mxnet]","lang":"bash","label":"Installation with MXNet backend (less actively maintained)"}],"dependencies":[{"reason":"Required for the recommended PyTorch backend.","package":"torch","optional":false},{"reason":"Required for the recommended PyTorch backend, often needs specific version alignment.","package":"pytorch-lightning","optional":false},{"reason":"Required for the MXNet backend.","package":"mxnet","optional":true},{"reason":"Required for R-based models. Version capped in 0.16.2.","package":"rpy2","optional":true}],"imports":[{"symbol":"ListDataset","correct":"from gluonts.dataset.common import ListDataset"},{"symbol":"SimpleFeedForwardEstimator","correct":"from gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator"},{"note":"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.","wrong":"from gluonts.torch.model.predictor import Trainer","symbol":"Trainer","correct":"from pytorch_lightning import Trainer"},{"symbol":"make_evaluation_predictions","correct":"from gluonts.evaluation import make_evaluation_predictions"},{"note":"Metrics like MSE are typically accessed via `backtest_metrics` after evaluation, not imported directly as a class.","symbol":"MSE","correct":"from gluonts.evaluation.backtest import make_evaluation_predictions, backtest_metrics"},{"note":"Useful for understanding time frequency strings.","symbol":"freqstr_to_timedelta","correct":"from gluonts.time_feature.util import freqstr_to_timedelta"}],"quickstart":{"code":"from gluonts.dataset.common import ListDataset\nfrom gluonts.torch.model.simple_feedforward import SimpleFeedForwardEstimator\nfrom pytorch_lightning import Trainer\nfrom gluonts.evaluation import make_evaluation_predictions, Evaluator\nimport pandas as pd\nimport numpy as np\n\n# 1. Prepare Data\ntarget_data = np.random.rand(100) # Dummy time series data\nstart_date = pd.Timestamp(\"2023-01-01\", freq=\"H\")\n\ndata_entry = {\n    \"start\": start_date,\n    \"target\": target_data,\n    \"item_id\": \"item_A\"\n}\n\ntraining_data = ListDataset([data_entry],\n                            freq=\"H\")\n\n# For evaluation, we need to split data into past and future\n# In a real scenario, you'd have separate test data or perform backtesting\nprediction_length = 24\nfull_data_entry = {\n    \"start\": pd.Timestamp(\"2023-01-01\", freq=\"H\"),\n    \"target\": np.concatenate([np.random.rand(80), np.random.rand(24)]), # 80 for training, 24 for future\n    \"item_id\": \"item_B\"\n}\n\n# Simulate a test dataset by cutting off the prediction_length from the full series\ntest_data = ListDataset([{\n    \"start\": full_data_entry[\"start\"],\n    \"target\": full_data_entry[\"target\"][:-prediction_length],\n    \"feat_static_cat\": [0],\n    \"item_id\": full_data_entry[\"item_id\"]\n}], freq=\"H\")\n\n# 2. Define Estimator\nestimator = SimpleFeedForwardEstimator(\n    prediction_length=prediction_length,\n    context_length=prediction_length * 2,\n    trainer=Trainer(max_epochs=5, enable_checkpointing=False, enable_progress_bar=False, logger=False),\n    num_hidden_dimensions=[10, 10]\n)\n\n# 3. Train the model\npredictor = estimator.train(training_data=training_data)\n\n# 4. Make Predictions\nforecast_it, ts_it = make_evaluation_predictions(\n    dataset=test_data,\n    predictor=predictor,\n    num_samples=100\n)\n\nforecasts = list(forecast_it)\nts = list(ts_it)\n\n# 5. Evaluate\nevaluator = Evaluator(quantiles=[0.1, 0.5, 0.9])\nagg_metrics, item_metrics = evaluator(ts, forecasts, num_series=len(test_data))\n\nprint(\"Aggregated metrics:\", agg_metrics)\nprint(\"First forecast (mean):\")\nprint(forecasts[0].mean)","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.10.x onwards, especially across minor GluonTS versions"},{"fix":"For new projects or when seeking the latest features and best support, strongly consider using `gluonts[torch]` and its associated models and utilities.","message":"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.","severity":"deprecated","affected_versions":"0.15.x onwards"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.16.0"},{"fix":"If using older versions or encountering this warning, explicitly pass `observed=True` to `DataFrame.groupby()` calls when preparing data for `PandasDataset`.","message":"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.","severity":"gotcha","affected_versions":"<0.16.1"},{"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]`.","message":"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.","severity":"gotcha","affected_versions":"0.16.2 onwards"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}