DOCSEARCHbyAlgolia
Submit Docs

Darts: User-Friendly Modern Machine Learning for Time Series

repository·master·Indexed 27 days ago

https://github.com/unit8co/darts

A Python library for the manipulation, forecasting, and anomaly detection of univariate and multivariate time series. Darts provides a unified scikit-learn-like interface for a wide range of models, including classical statistical methods (ARIMA, Exponential Smoothing), gradient boosting (XGBoost, LightGBM, CatBoost), and deep learning architectures (N-BEATS, TFT, TCN) via PyTorch Lightning. It supports probabilistic forecasting, covariates, hierarchical reconciliation, and integrates with StatsForecast and NeuralForecast.

Tokens
30.2K
Snippets
52
Records
144
Agent score
94%

What's inside Darts

  1. Overview of Darts Forecasting Models

    master

    Darts provides a suite of forecasting models categorized into regression and classification models.

    Regression Models are designed to predict continuous numerical values and are used for forecasting future trends and patterns in time series data based on historical observations.

  2. Overview of Darts Features

    master

    Darts is a comprehensive library for time series analysis with the following key capabilities:

    • Forecasting Models: Includes statistical models (e.g., ARIMA) and deep learning models (e.g., N-BEATS).
    • Anomaly Detection: The darts.ad module provides scorers, detectors, and aggregators. It also supports PyODScorer for using PyOD detectors.
    • Multivariate & Multiple Series Support: Supports multivariate TimeSeries and training on multiple series (Global Models).
    • Probabilistic Forecasting: Supports stochastic TimeSeries and various probabilistic forecasting methods (quantiles, parametric distributions).
    • Covariates: Supports both past-observed and future-known covariates.
    • Static Covariates: Allows including static data for each dimension.
    • Hierarchical Reconciliation: Transformers for reconciling hierarchical forecasts.
    • Data Processing & Metrics: Tools for transformations (scaling, filling missing values, etc.) and evaluation metrics (R2, MASE, etc.).
    • Backtesting: Utilities for simulating historical forecasts using moving time windows.
    • Integration: Built on PyTorch Lightning for deep learning and compatible with pandas, polars, numpy, pyarrow, and xarray.

  3. Implement Anomaly Detection and Explainability

    master

    Darts includes modules for detecting outliers and interpreting model decisions:

    • Anomaly Detection: Use the dedicated anomaly detection workflows to identify unusual patterns in your time series.
    • Explainability: The explainability module allows you to interpret both PyTorch-based and SKLearn-based models to understand the drivers behind forecasts.

  4. Understand Covariate Support in Darts Forecasting Models

    master

    Darts forecasting models support three types of covariates, which can be passed to the fit() and predict() methods. Note that models will raise an error if you provide a covariate type they do not support.

    • Past Covariates: Time series that provide information about the past to help predict the future.
    • Future Covariates: Time series that provide information about the future (e.g., known holidays or weather forecasts).
    • Static Covariates: Metadata or constant values embedded directly within the target series.

    Model Categories

    • Local Forecasting Models (LFMs): Trained on a single target series (e.g., ARIMA, ExponentialSmoothing). They typically train on the entire supplied series at once.
    • Global Forecasting Models (GFMs): Trained on multiple target and covariate series by training on fixed-length sub-samples (chunks) of the data (e.g., RNNModel, NBEATSModel, TFTModel).

  5. Understand the `TimeSeries` class

    master

    The TimeSeries class is the core data structure in Darts. It represents univariate or multivariate time series with a proper, complete, and time-sorted index. The index can be a pandas.DatetimeIndex (for specific timestamps) or a pandas.RangeIndex (for integer-based sequential data).

    Key characteristics:

    • Univariate vs. Multivariate: A univariate series has one component; a multivariate series has multiple components sharing the same time axis.
    • Deterministic vs. Probabilistic: A deterministic series contains a single sample, while a probabilistic (stochastic) series contains multiple Monte Carlo samples to represent distributions.
    • Consistency: All Darts models consume and produce TimeSeries objects, ensuring a consistent API for time series operations like splitting or concatenating.

  6. Use Regression and Classification models with Darts

    master

    Beyond standard forecasting, Darts provides interfaces for supervised learning tasks using SKLearn-style models:

    • Regression Models: For predicting continuous values.
    • Classification Models: For predicting discrete categories.

  7. Understand the types of covariates in Darts

    master

    Darts distinguishes between three types of covariates used to improve forecasting models. The target is the series you want to predict, while covariates are external inputs that are not predicted themselves.

    • past_covariates: Data known only up to the present (e.g., historical measurements like daily average measured temperatures).
    • future_covariates: Data known into the future (e.g., weather forecasts or temporal attributes like day of the week, month, or year).
    • static_covariates: Data that remains constant over time (e.g., product IDs, location, or population). Unlike past and future covariates, static covariates must be embedded directly within the target TimeSeries object.

  8. Classification Models in Darts

    master

    Darts provides classification models designed to predict categorical class labels. These models are used for time series labeling and predicting future states or categories over time.

    Supported models include wrappers for popular machine learning libraries, allowing you to use scikit-learn, CatBoost, LightGBM, or XGBoost for classification tasks within the Darts ecosystem.

  9. Use advanced forecasting techniques and models in Darts

    master

    Darts supports a variety of specialized forecasting approaches. You can find specific implementation examples for:

    • Neural Networks: RNN, TCN (Temporal Convolutional Networks), Transformer, N-BEATS, DeepAR, DeepTCN, TFT (Temporal Fusion Transformer), TiDE (TimeSeries Dense Encoder), and TSMixer (TimeSeries Mixer).
    • Statistical & Filter Models: Kalman Filter, Gaussian Process Filter, and Fast Fourier Transform (FFT).
    • Foundation & Pre-trained Models: Chronos-2, Foundation Models, and Transfer Learning techniques.
    • Advanced Workflows: Hierarchical Reconciliation, Conformal Prediction, Ensemble Models, and Hyperparameter Optimization (using Optuna).

  10. Use past and future covariates with forecasting models

    master

    To use covariates with Darts forecasting models, ensure all covariates are provided as TimeSeries objects. When training with fit(), you must supply the same types of covariates during predict() that were used during training. Darts can automatically slice covariates to match the target time axis if they contain sufficient time spans.

    Key Requirements:

    • past_covariates and future_covariates must be TimeSeries objects.
    • The types of covariates used in fit() must match those used in predict().
    • For Global Forecasting Models (GFMs), you must provide the series argument in predict() to specify which target series you are forecasting.
    # create one of Darts' forecasting model
model = SomeForecastingModel(...)

# fit the model
model.fit(target,
          past_covariates=past_covariate,
          future_covariates=future_covariates)

# make a prediction with the same covariate types
pred = model.predict(n=1,
                     series=target,  # this is only required for GFMs
                     past_covariates=past_covariates,
                     future_covariates=future_covariates)

  11. Enable automatic checkpointing for Torch Forecasting Models

    master

    Automatic checkpointing allows you to track the latest 5 epochs and the best performing epoch based on validation loss. It enables resuming interrupted training and loading the best model for inference.

    To use it, set save_checkpoints=True and provide a model_name during model creation. Use load_from_checkpoint to retrieve the best performing state.

    model = SomeTorchForecastingModel(..., model_name='my_model', save_checkpoints=True)

# checkpoints are saved automatically
model.fit(...)

# load the model state that performed best on validation set
best_model = model.load_from_checkpoint(model_name='my_model', best=True)

  12. Use past and future covariates in forecasting

    master

    Covariates are external time series used as inputs to a model that are not being forecasted themselves. Darts distinguishes between two types:

    1. Past Covariates: Values are only known up to the present. Models do not use future values of past_covariates when making forecasts.
    2. Future Covariates: Values are known into the future (e.g., holidays, weather forecasts). Models can consume these future values up to the forecast horizon.

    To use them, pass them to the past_covariates or future_covariates arguments in the fit() and predict() methods. Darts automatically handles the necessary slicing of the covariate time spans to match the target series.