Darts Time Series Cheat Sheet

1Install & TimeSeries0.3x

pip install darts★
Full install includes torch models. Lighter options exist (u8darts[notorch]) if you only need local/regression models.
from darts import TimeSeries ts = TimeSeries.from_dataframe(df, time_col="date", value_cols="y")★
The core container. Multiple value_cols → a multivariate series (each column is a "component").
TimeSeries.from_series(s) · from_values(arr) · from_csv("f.csv", ...)
Build from a pandas Series, raw array, or CSV. from_group_dataframe makes a list of series (one per group).
ts.pd_dataframe() · ts.values() · ts.plot()
Back to pandas/numpy, or a quick matplotlib plot.

2TimeSeries operationsslice & combine

train, val = ts.split_after(0.8) # or split_before(timestamp)★
Chronological split for train/validation. ts[:100], ts.slice(start, end) for windows.
ts.univariate_component(0) · ts.stack(other) · ts.concatenate(...)
Pull one component, stack components side by side, or join along time.
from darts.utils.missing_values import fill_missing_values
Impute gaps. ts.has_datetime_index, ts.freq, ts.n_components for introspection.
ts.static_covariates · ts.with_static_covariates(df)
Attach per-series static features (e.g. store id, category) that global models can use.

3fit / predict & local modelsclassic

from darts.models import ExponentialSmoothing m = ExponentialSmoothing(); m.fit(train); pred = m.predict(n=12)★
Fit on a series, forecast n steps ahead — returns a TimeSeries. The universal Darts loop.
from darts.models import ARIMA, AutoARIMA, Theta, Prophet, FFT, KalmanForecaster
Classic statistical models. NaiveSeasonal/NaiveDrift are the baselines to beat.
from darts.models import RegressionModel, LinearRegressionModel, LightGBMModel, XGBModel LightGBMModel(lags=24, lags_future_covariates=[0])★
Wrap any sklearn-style regressor (or LGBM/XGB/CatBoost) as a lag-based forecaster — often the strong, fast default.
pred = m.predict(n=12, series=other_ts)
For fitted global/regression models, forecast a different series without refitting.

4Global & deep modelstrain on many series

from darts.models import TFTModel, NHiTSModel, NBEATSModel, TiDEModel, RNNModel, TCNModel★
PyTorch (Lightning) forecasters. input_chunk_length / output_chunk_length define the lookback/horizon windows.
m = NHiTSModel(input_chunk_length=48, output_chunk_length=12, n_epochs=50) m.fit([ts1, ts2, ts3]) # train once on MANY series★
Global models learn across a list of series — the key to forecasting thousands of related series with one model.
m.fit(ts, epochs=..., pl_trainer_kwargs={"accelerator":"gpu"})
Torch models accept Lightning trainer kwargs (GPU, precision, callbacks). m.save()/load() to persist.
m.predict(n=12, series=ts) · m.predict(n=12, series=[ts1, ts2])
Predict for one or many series after a single global fit.

5Covariatesextra signals

m.fit(target, past_covariates=pc, future_covariates=fc)★
past = known only up to now (e.g. sensor readings); future = known ahead (calendar, holidays, promotions).
m.predict(n=12, future_covariates=fc)
Future covariates must extend n steps beyond the target — that's what makes them "future known".
from darts.utils.timeseries_generation import datetime_attribute_timeseries fc = datetime_attribute_timeseries(ts, attribute="month", one_hot=True)★
Generate calendar covariates (month/dayofweek/holidays) to feed the model.
a model uses only the covariate types it supportscheck
Not every model accepts past/future/static covariates — check m.supports_future_covariates etc.

6Scaling & pipelinespreprocess

from darts.dataprocessing.transformers import Scaler sc = Scaler(); train_s = sc.fit_transform(train); pred = sc.inverse_transform(m.predict(n))★
Min-max/standard scaling on TimeSeries — essential for neural models. Remember to inverse-transform predictions.
from darts.dataprocessing import Pipeline Pipeline([Scaler(), BoxCox(), ...])
Chain transformers; the pipeline inverts them in the right order on inverse_transform.
MissingValuesFiller() · Diff() · StaticCovariatesTransformer()
Other built-in transformers for imputation, differencing, and encoding static covariates.

7Probabilistic forecastsuncertainty

pred = m.predict(n=12, num_samples=500)★
Monte-Carlo sample paths — the returned TimeSeries is stochastic. Requires a probabilistic model/likelihood.
TFTModel(..., likelihood=QuantileRegression([0.1,0.5,0.9]))
Torch models take a likelihood (Quantile, Gaussian, ...); regression models take likelihood="quantile".
pred.quantile_timeseries(0.9) · pred.quantile(0.5)
Extract quantiles/median from the sampled forecast; plot() shades the interval automatically.

8Backtesting & metricshonest evaluation

hist = m.historical_forecasts(ts, start=0.6, forecast_horizon=12, stride=1)★
Rolling-origin forecasts across the series — simulates how the model would have performed over time.
err = m.backtest(ts, start=0.6, forecast_horizon=12, metric=mape)★
Same, but returns the aggregated error. retrain=True/False/int controls refit frequency.
from darts.metrics import mape, smape, mae, rmse, mase, mql mape(val, pred)★
Standard metrics take (actual, forecast) TimeSeries. mql for quantile loss on probabilistic forecasts.

9Grid search & anomaly detectionextras

Model.gridsearch(parameters={...}, series=train, val_series=val, metric=mape)
Built-in hyperparameter search over a param grid — returns the best model & params.
from darts.ad import KMeansScorer, QuantileDetector, ForecastingAnomalyModel
The anomaly-detection module: score residuals or wrap a forecaster to flag outliers.
from darts.explainability import TFTExplainer, ShapExplainer
Explain global/torch model forecasts (feature/covariate importances).

!Common gotchasread before shipping

regular, gap-free index
TimeSeries assumes a fixed frequency — fill gaps with fill_missing_values or construct with an explicit freq.
scale before neural models
TFT/NHiTS/RNN need scaled inputs (Scaler) — and you must inverse_transform the prediction.
future covariates must extend n steps
Provide future covariates covering the whole forecast horizon, or predict fails.
local vs global
Local models (ARIMA/ETS) fit one series; global models (torch/regression) train across many. Only global models predict unseen series.

Darts cheat sheet