Darts: User-Friendly Modern Machine Learning for Time Series

In plain words

Darts is a Python library for forecasting time series: predicting the next values of a sequence measured over time, such as sales or energy use. Its aim is to put classical statistical models and modern neural networks behind one simple interface. You create a model, call fit() on your data and predict() to get a forecast, much as you would with scikit-learn.

The library also settles several design questions. Each series lives in one container that keeps its time axis, its several components and, for probabilistic forecasts, a set of sampled outcomes together. A model can be trained on many series at once, can take extra inputs that are known only up to the present, or known into the future too, and can output a range of possible futures instead of a single value.

The card's example trains one temporal convolutional network on two series and forecasts one of them with an uncertainty band. The paper is mainly about the API. It reports no accuracy benchmarks.

TL;DR

• Darts is a time-series library whose models share fit() and predict(n), including classical, deep and probabilistic ones [abstract] §2.2.
• Series are stored in a TimeSeries container; probabilistic forecasts are Monte Carlo samples stored in that container §2.1 §2.5.
• The paper reports no benchmark results. Its one worked example is a TCN with a Laplace likelihood on two series §3.
• The code is Apache-2.0 at a commit (version 0.48.1) much later than the paper, so its API details differ from the paper's era.

Problem

Classical forecasting methods are usually fitted one model per series, while machine-learning models work best when trained across many series §1 §2.3. The paper says existing toolkits either focus on classical methods, lack deep learning or multi-series training, or expose lower-level APIs §1. It proposes a higher-level API that covers both classical and ML forecasters and handles multidimensional series, external covariates, ensembling and probabilistic output [abstract] §1.

Method

The "method" is a software design. The paper states six design points, which are the parts an implementer must reproduce to use the library as intended.

1. Series container. TimeSeries wraps a three-dimensional xarray DataArray with dimensions time, component and sample, in that order §2.1 timeseries.py. The time index is either a pandas DatetimeIndex or a RangeIndex §2.1. Components are the variables of a multivariate series; samples are Monte Carlo draws of a stochastic series §2.1 timeseries.py.
2. Common API. Every model supports fit(series) and predict(n), which forecasts n steps after the end of the series. Most models also accept a sequence of series in fit §2.2 torch_forecasting_model.py torch_forecasting_model.py. The paper says the interface is similar to scikit-learn's fit/predict [abstract].
3. Training on many series. Each model has a default way of slicing series into (input, output) training samples. Users can define their own slicing §2.3. Neural models use PyTorch and can run on GPUs §2.3. Large datasets that do not fit in memory are handled by a custom lazily loading Sequence §2.3. The code offers max_samples_per_ts to cap the training samples taken from each series, keeping the most recent ones torch_forecasting_model.py.
4. Covariates. Models take past_covariates (known only up to the present) and future_covariates (known into the future, such as forecasts). The separate arguments make it explicit whether future values are needed at prediction time §2.4 torch_forecasting_model.py torch_forecasting_model.py. Covariates need not share the target's time range; alignment is done on the time axes during slicing §2.4.
5. Probabilistic forecasts. Distributions are represented by stored Monte Carlo samples rather than a parametric form §2.5. Probabilistic deep models fit any likelihood whose negative log-likelihood is differentiable §2.5. The paper counts 17 built-in distributions and allows time-independent priors on distribution parameters §2.5. Example: the Laplace likelihood has location mu and scale b > 0, with optional priors prior_mu, prior_b and a prior_strength torch.py.
6. Other features. Backtesting through backtest() §2.6 forecasting_model.py; data transformers and pipelines; hyperparameter search; metrics; dynamic time warping; ensemble models, including one that learns the ensemble with a regression model §2.6 ensemble_model.py; Kalman filters and Gaussian processes §2.6; and a datasets module of public series §2.6.

The usage example in the paper (§3) runs the following steps. It is written in pseudocode, not as the paper's exact listing.

# Two-series TCN example  [§3]
# Input:  two series (air, milk)
# Output: 48-step forecast, 500 Monte Carlo samples

def run_example():
    # Load two datasets from darts.datasets as TimeSeries  [§3]
    air = load_air_passengers()
    milk = load_monthly_milk()

    # One scaler per series, each fitted on its own series  [§3]
    air_scaled = Scaler().fit_transform(air)
    milk_scaled = Scaler().fit_transform(milk)

    # Dilated TCN: 24 input steps, 12 output steps, Laplace output  [§3]
    model = TCNModel(
        input_chunk_length=24,
        output_chunk_length=12,
        likelihood=LaplaceLikelihood(),
    )

    # Train on both series together for 100 epochs  [§3]
    model.fit([air_scaled, milk_scaled], epochs=100)

    # Forecast 48 steps after the air series, 500 sample paths  [§3]
    return model.predict(
        n=48,
        series=air_scaled,
        num_samples=500,
    )

Key equations: none. The paper contains no equations, algorithms or tables.

Hyperparameters

The paper gives only the example's settings. Every other value below comes from the code at code_commit. The paper says "default hyper-parameters" for the TCN §3 without listing them.

Results

Author-reported. The paper reports no quantitative results: no benchmark, metric, baseline or accuracy figure. Its only empirical content is the usage example, which shows a forecast with a quantile band for the air series §3. That figure is uncaptioned and not numbered in the paper, so it is cited as §3 only.

Paper vs code

The code is the official Darts repository at commit 406ecda0ff7d6e20cf2e19effac5024308057c9f, version 0.48.1 pyproject.toml. It is much later than the paper, which describes the library as of 2021–2022. I did not execute the paper's example; the signatures it uses match this commit.

• Version. The paper's list of models and its "17 distributions" are a snapshot "at the time of writing" §2.2 §2.5. The code now ships further models, including foundation-model wrappers (for example chronos2_model.py, timesfm2p5_model.py and tirex_model.py). The likelihood classes are defined at torch.py. The code has 17 classes named *Likelihood plus QuantileRegression. The paper's count of 17 matches the class names, but the list is the current one, not the paper's.
• TCN defaults. The paper calls the example's TCN configuration "default hyper-parameters" §3 without giving them. The defaults are in the constructor tcn_model.py. Only input_chunk_length, output_chunk_length and likelihood are set in the example.
• Autoregression. The paper's example calls predict(n=48) on a model with output_chunk_length=12 §3, which requires autoregressive prediction. The code documents this: n greater than output_chunk_length forecasts autoregressively tcn_model.py. The paper does not say so.
• Epochs. The paper's fit(..., epochs=100) matches the signature torch_forecasting_model.py. The docstring says epochs trains that many additional epochs regardless of n_epochs torch_forecasting_model.py. Without it, n_epochs is used torch_forecasting_model.py.
• Quantile defaults. The paper passes quantiles 0.1 and 0.9 to plot §3. The code's defaults are 0.05 and 0.95 timeseries.py. The example's values are explicit, so it is unaffected.
• Immutability. The paper says TimeSeries objects are immutable §2.1. The word does not appear in darts/timeseries.py. I did not verify this guarantee in the code.
• Scaler range. The paper does not state the scaler's range. The code's default is (0, 1) scaler.py.

No other discrepancies found.

Pitfalls

• Paper vs current API. Code at this commit has moved on from the paper. Check the signatures in the commit before copying the paper's text. The paper's API names are still valid, but the model list and defaults are a later snapshot.
• Auto layer count. When num_layers is not set, the TCN's depth follows from input_chunk_length, kernel size and dilation base tcn_model.py. Changing the input length therefore changes the network's depth and receptive field silently.
• Autoregression. Forecasting n steps with output_chunk_length=12 runs autoregressive chunks tcn_model.py. The paper does not discuss this or any accuracy effect of it.
• Sample cost. Probabilistic output is stored as samples in the sample dimension §2.1 §2.5. The memory and time cost grows with n, components and num_samples. This is an inference from the representation; the paper gives no measurements.
• Dropout at inference. The TCN's dropout is documented as compatible with Monte Carlo dropout, enabled with mc_dropout=True at prediction time tcn_model.py. The paper does not mention this option.
• Learning rate. No learning rate is stated in the paper or the code default. It comes from torch's Adam default unless optimizer_kwargs is set tcn_model.py.
• Training cap. max_samples_per_ts limits the training samples from each series by keeping the most recent ones torch_forecasting_model.py. This is a cap on the data used, not a change to the model.

Lineage

• Builds on: the TCN architecture the example uses §3 (the paper cites it as [tcn18] in the text). Darts itself builds on PyTorch and xarray §2.1 §2.3.
• Compared against: the paper names existing toolkits, including R's forecast package, Kats, sktime, Greykite, Merlion, GluonTS and PyTorch Forecasting §1. It does not give comparative results.
• Superseded by: not stated in this wiki.