Darts

0.43.0 · active · verified Thu Apr 16

Darts is a Python library for user-friendly forecasting and anomaly detection on time series. It offers a unified API for a wide range of models, from classical statistical methods like ARIMA to advanced deep learning architectures such as LSTM and Transformers. The library also includes tools for model evaluation, backtesting, handling multiple time series, and incorporating external covariates. It is actively maintained with frequent minor releases, typically on a monthly basis. [1, 2, 4, 9, 11, 13, 16, 22]

Common errors

```
ValueError: Could not infer explicit frequency. Observed frequencies: {'D', 'B'}. Is Series too short (n=2)?
```
cause `TimeSeries.from_dataframe` or `TimeSeries` constructor detected multiple, inconsistent frequencies in the index, or the series was too short to infer a reliable frequency. [23]

fix Ensure your `pandas.DatetimeIndex` has a single, consistent frequency before creating the `TimeSeries` object. Manually specify the `freq` argument (e.g., `'D'`, `'MS'`) in `TimeSeries.from_dataframe()` if auto-inference fails, or resample/clean your data to a uniform frequency. [23]
```
ValueError: Unable to build any training samples of the target series and the corresponding covariate series; There is no time step for which all required lags are available and are not NaN values.
```
cause This error typically occurs when using covariates. The target and covariate series do not align correctly, or there are insufficient non-NaN data points to satisfy the model's lag requirements for training. This can also happen if future covariates do not extend far enough for the prediction horizon. [19, 21]

fix Pre-process your target and covariate series to ensure proper alignment and handle missing values (NaNs) before passing them to `fit()` and `predict()`. Ensure covariate series have sufficient historical data for past lags and extend far enough into the future for future covariates predictions. [18, 19, 20, 21]
```
ModuleNotFoundError: No module named 'u8darts'
```
cause Attempting to import from the deprecated `u8darts` package, which was replaced by `darts` in version 0.41.0. [1, 9]

fix Change all `from u8darts import ...` statements to `from darts import ...`. Ensure the `darts` package is installed (`pip install darts`). [1, 9]
```
Forecast contains NaNs.
```
cause The most common cause is the presence of `NaN` values within the training `TimeSeries` (either target or covariates). Less frequently, it can be due to numerical divergence when training deep learning models. [20]

fix Thoroughly check your input `TimeSeries` objects for `NaN`s before fitting. Use `series.fill_missing()` or `series.dropna()` or ensure your data loading and `freq` parameter are correct. If using neural networks and data is clean, try scaling your data (e.g., `Scaler`) and potentially reducing the learning rate. [20]

Warnings

breaking Darts version 0.41.0 and later removed support for Python 3.9. The new minimum Python version is 3.10. [9]
Fix: Upgrade your Python environment to 3.10 or higher.
breaking As of Darts version 0.41.0, the PyPI package name changed from `u8darts` to `darts`. The `u8darts` package is no longer maintained. [1, 9]
Fix: Use `pip install darts` for installation and `from darts import ...` for imports. Do not use `u8darts`.
gotcha Training or forecasting with `TimeSeries` objects containing `NaN` values will often lead to `NaN`s in forecasts or errors. [20]
Fix: Ensure your input `TimeSeries` objects (targets and covariates) are free of NaNs. This often involves properly handling missing dates and ensuring the `freq` argument is correctly set when creating a `TimeSeries` from a DataFrame. [20]
gotcha Installing Darts with all optional dependencies (`pip install "darts[all]"` or `pip install "darts[torch]"`) can be complex due to non-Python dependencies for libraries like Prophet and PyTorch. [1, 3, 5, 17]
Fix: Consider using a Conda environment for easier dependency management (`conda install -c conda-forge -c pytorch u8darts-all`) or install specific optional dependencies separately after the core Darts package, following their respective installation guides. [1, 3]

Install

pip install darts Basic Install

Imports

TimeSeries
```
from darts import TimeSeries
```
ARIMA
wrong:
```
from darts.models import AutoARIMA
```
correct:
```
from darts.models import ARIMA
```
AutoARIMA is part of pmdarima integration, ARIMA is a separate Darts model.

ExponentialSmoothing

from darts.models import ExponentialSmoothing

Quickstart

This quickstart demonstrates how to create a `TimeSeries` object from a Pandas DataFrame, split it into training and validation sets, fit an `ExponentialSmoothing` model, and generate a forecast. The example then plots the actual series against the predicted values. [4, 8, 11, 12, 13]

import pandas as pd
from darts import TimeSeries
from darts.models import ExponentialSmoothing
import matplotlib.pyplot as plt

# Create a sample DataFrame (replace with your data)
df = pd.DataFrame({
    'Month': pd.to_datetime(pd.date_range(start='2000-01-01', periods=120, freq='MS')),
    '#Passengers': [100 + i + (i**1.2) * 0.5 for i in range(120)] # Example data
})

# Create a TimeSeries object
series = TimeSeries.from_dataframe(df, 'Month', '#Passengers')

# Split data into training and validation sets
train, val = series[:-12], series[-12:]

# Initialize and fit a model
model = ExponentialSmoothing()
model.fit(train)

# Make a prediction
prediction = model.predict(len(val))

# Plot the results
series.plot(label='actual')
prediction.plot(label='forecast')
plt.title('Darts Quickstart Forecast')
plt.show()

view raw JSON →