
Python-библиотека для удобного прогнозирования и обнаружения аномалий на временных рядах.
# Простой анализ временных рядов на Python

---
[](https://badge.fury.io/py/darts)
[](https://anaconda.org/conda-forge/u8darts-all)

[](https://hub.docker.com/r/unit8/darts)


[](https://pepy.tech/project/darts)
[](https://pepy.tech/project/u8darts)
[](https://codecov.io/gh/unit8co/darts)
[](https://github.com/psf/black) [](https://gitter.im/u8darts/darts?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
**Darts** — это библиотека Python для удобного прогнозирования и обнаружения аномалий
во временных рядах. Она содержит множество моделей: от классических, таких как ARIMA, до
глубоких нейронных сетей. Все модели прогнозирования можно использовать одинаково,
с помощью функций `fit()` и `predict()`, аналогично scikit-learn.
Библиотека также упрощает бэктестинг моделей,
объединение прогнозов нескольких моделей и учёт внешних данных.
Darts поддерживает как одномерные, так и многомерные временные ряды и модели.
Модели на основе машинного обучения можно обучать на потенциально больших наборах данных, содержащих множество временных
рядов, а некоторые модели предлагают богатую поддержку вероятностного прогнозирования.
Darts также предлагает обширные возможности обнаружения аномалий.
Например, применить модели PyOD к временным рядам для получения оценок аномальности
или обернуть любую из моделей прогнозирования или фильтрации Darts, чтобы получить полноценные
модели обнаружения аномалий, — это тривиально.
## Документация
* [Быстрый старт](https://unit8co.github.io/darts/quickstart/00-quickstart.html)
* [Руководство пользователя](https://unit8co.github.io/darts/userguide.html)
* [Справочник API](https://unit8co.github.io/darts/generated_api/darts.html)
* [Примеры](https://unit8co.github.io/darts/examples.html)
### Вводные материалы
* [Вводная статья в блоге](https://medium.com/unit8-machine-learning-publication/darts-time-series-made-easy-in-python-5ac2947a8878)
* [Вводное видео (25 минут)](https://youtu.be/g6OXDnXEtFA)
### Статьи по отдельным темам
* [Обучение моделей на нескольких временных рядах](https://medium.com/unit8-machine-learning-publication/training-forecasting-models-on-multiple-time-series-with-darts-dc4be70b1844)
* [Использование прошлых и будущих ковариат](https://medium.com/unit8-machine-learning-publication/time-series-forecasting-using-past-and-future-external-data-with-darts-1f0539585993)
* [Временные свёрточные сети и прогнозирование](https://medium.com/unit8-machine-learning-publication/temporal-convolutional-networks-and-forecasting-5ce1b6e97ce4)
* [Вероятностное прогнозирование](https://medium.com/unit8-machine-learning-publication/probabilistic-forecasting-in-darts-e88fbe83344e)
* [Перенос обучения для прогнозирования временных рядов](https://medium.com/unit8-machine-learning-publication/transfer-learning-for-time-series-forecasting-87f39e375278)
* [Иерархическая согласованность прогнозов](https://medium.com/unit8-machine-learning-publication/hierarchical-forecast-reconciliation-with-darts-8b4b058bb543)
## Быстрая установка
Мы рекомендуем сначала настроить чистое окружение Python для вашего проекта с Python 3.11+, используя ваш любимый инструмент
([conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html "conda-env"),
[venv](https://docs.python.org/3/library/venv.html), [virtualenv](https://virtualenv.pypa.io/en/latest/) с
или без [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)).
После настройки окружения вы можете установить darts с помощью pip:
pip install darts
Для получения дополнительной информации обратитесь к нашим
[инструкциям по установке](https://github.com/unit8co/darts/blob/master/INSTALL.md).
## Пример использования
### Прогнозирование
Создайте объект `TimeSeries` из Pandas DataFrame и разделите его на обучающую и валидационную серии:
```python
import pandas as pd
from darts import TimeSeries
# Read a pandas DataFrame
df = pd.read_csv("AirPassengers.csv", delimiter=",")
# Create a TimeSeries, specifying the time and value columns
series = TimeSeries.from_dataframe(df, "Month", "#Passengers")
# Set aside the last 36 months as a validation series
train, val = series[:-36], series[-36:]
```
Подгоните модель экспоненциального сглаживания и сделайте (вероятностный) прогноз на продолжительность валидационного ряда:
```python
from darts.models import ExponentialSmoothing
model = ExponentialSmoothing()
model.fit(train)
prediction = model.predict(len(val), num_samples=1000)
```
Постройте график медианы, 5-го и 95-го процентилей:
```python
import matplotlib.pyplot as plt
series.plot()
prediction.plot(label="forecast", low_quantile=0.05, high_quantile=0.95)
plt.legend()
```
<div style="text-align:center;">
<img src="https://raw.githubusercontent.com/unit8co/darts/master/static/images/example.png" alt="пример прогноза darts" />
</div>
### Обнаружение аномалий
Загрузите многомерный ряд, обрежьте его, оставьте 2 компонента, разделите на обучающую и валидационную выборки:
```python
from darts.datasets import ETTh2Dataset
series = ETTh2Dataset().load()[:10000][["MUFL", "LULL"]]
train, val = series.split_before(0.6)
```
Постройте скорер аномалий на основе k-means, обучите его на обучающем наборе
и примените его к валидационному набору для получения оценок аномальности:
```python
from darts.ad import KMeansScorer
scorer = KMeansScorer(k=2, window=5)
scorer.fit(train)
anom_score = scorer.score(val)
```
Создайте бинарный детектор аномалий и обучите его на train-оценках,
затем примените его к validation-оценкам для получения бинарной классификации аномалий:
```python
from darts.ad import QuantileDetector
detector = QuantileDetector(high_quantile=0.99)
detector.fit(scorer.score(train))
binary_anom = detector.detect(anom_score)
```
Построение графика (сдвиг и масштабирование некоторых рядов,
чтобы всё отображалось на одном рисунке):
```python
import matplotlib.pyplot as plt
series.plot()
(anom_score / 2. - 100).plot(label="computed anomaly score", c="orangered", lw=3)
(binary_anom * 45 - 150).plot(label="detected binary anomaly", lw=4)
```
<div style="text-align:center;">
<img src="https://raw.githubusercontent.com/unit8co/darts/master/static/images/example_ad.png" alt="пример обнаружения аномалий в darts" />
</div>
## Возможности
* **Модели прогнозирования:** Большая коллекция моделей прогнозирования как для задач регрессии, так и для задач классификации; от статистических моделей (таких как
ARIMA) до моделей глубокого обучения (таких как N-BEATS). См. [модели прогнозирования](#forecasting-models) ниже.
* **Обнаружение аномалий** Модуль `darts.ad` содержит коллекцию скореров аномалий,
детекторов и агрегаторов, которые можно комбинировать для обнаружения аномалий во временных рядах.
Легко обернуть любую из моделей прогнозирования или фильтрации Darts, чтобы построить
полноценную модель обнаружения аномалий, сравнивающую прогнозы с фактическими значениями.
`PyODScorer` делает тривиальным использование детекторов PyOD для временных рядов.
* **Поддержка многомерности:** `TimeSeries` может быть многомерным — то есть содержать несколько изменяющихся во времени
измерений/столбцов вместо одного скалярного значения. Многие модели могут принимать и выдавать многомерные ряды.
* **Обучение на нескольких рядах (глобальные модели):** Все модели на основе машинного обучения (включая все нейронные сети)
поддерживают обучение на нескольких (потенциально многомерных) рядах. Это также масштабируется на большие наборы данных.
* **Вероятностная поддержка:** Объекты `TimeSeries` могут (опционально) представлять стохастические
временные ряды; это можно, например, использовать для получения доверительных интервалов, и многие модели поддерживают разные
варианты вероятностного прогнозирования (такие как оценка параметрических распределений или квантилей).
Некоторые скореры обнаружения аномалий также способны использовать эти прогнозные распределения.
* **Поддержка конформного прогнозирования:** Наши модели конформного прогнозирования позволяют генерировать вероятностные прогнозы с
калиброванными квантильными интервалами для любой предварительно обученной глобальной модели прогнозирования.
* **Поддержка прошлых и будущих ковариат:** Многие модели в Darts поддерживают временные ряды ковариат (внешних данных),
наблюдаемых в прошлом и/или известных в будущем, в качестве входных данных для построения прогнозов.
* **Поддержка статических ковариат:** В дополнение к зависящим от времени данным, `TimeSeries` может также содержать
статические данные для каждого измерения, которые могут использоваться некоторыми моделями.
* **Иерархическая согласованность:** Darts предлагает трансформеры для выполнения согласования.
Они позволяют сделать так, чтобы прогнозы суммировались с учётом лежащей в основе иерархии.
* **Модели регрессии:** Можно подключить любую модель, совместимую со scikit-learn,
чтобы получать прогнозы как функции лаговых значений целевого ряда и ковариат.
* **Обучение с весами выборок:** Все глобальные модели поддерживают обучение с весами выборок. Их можно
применять к каждому наблюдению, прогнозируемому временному шагу и целевому столбцу.
* **Сдвиг начала прогноза:** Все глобальные модели поддерживают обучение и прогнозирование на сдвинутом выходном окне.
Это полезно, например, для прогнозов рынка на сутки вперёд или когда ковариаты (или целевой ряд) сообщаются
с задержкой.
* **Объяснимость:** Darts умеет *объяснять* некоторые модели прогнозирования с помощью значений SHAP.
* **Обработка данных:** Инструменты для лёгкого применения (и отмены) распространённых преобразований
данных временных рядов (масштабирование, заполнение пропущенных значений, взятие разностей, boxcox, ...)
* **Метрики:** Разнообразие метрик для оценки качества соответствия временных рядов;
от R2-оценок до Mean Absolute Scaled Error.
* **Бэктестинг:** Утилиты для симуляции исторических прогнозов с использованием скользящих временных окон.
* **Поддержка PyTorch Lightning:** Все модели глубокого обучения реализованы с использованием PyTorch Lightning,
что поддерживает, среди прочего, пользовательские колбэки, обучение на GPU/TPU и пользовательские тренеры.
* **Интеграция с MLflow:** Интеграция с MLflow для автоматизированного отслеживания, сравнения и сохранения
экспериментов с моделями прогнозирования Darts. Примеры см. в [MLflow quickstart notebook](https://unit8co.github.io/darts/examples/29-MLflow-examples.html).
* **Модели фильтрации:** Darts предлагает три модели фильтрации: `KalmanFilter`, `GaussianProcessFilter`
и `MovingAverageFilter`, которые позволяют фильтровать временные ряды и в некоторых случаях получать вероятностные
выводы о лежащих в основе состояниях/значениях.
* **Наборы данных** Подмодуль `darts.datasets` содержит некоторые популярные наборы данных временных рядов для быстрого
и воспроизводимого экспериментирования.
* **Совместимость с несколькими бэкендами:** Объекты `TimeSeries` можно создавать из различных бэкендов и экспортировать в них, таких как pandas, polars, numpy, pyarrow, xarray и других, что обеспечивает бесшовную интеграцию с различными библиотеками обработки данных.
## Модели прогнозирования
Ниже приведён обзор моделей прогнозирования, в настоящее время реализованных в Darts. Наш набор включает как модели регрессии, так и модели классификации, каждая из которых адаптирована для конкретных задач прогнозирования. Мы стремимся расширять наши предложения новыми моделями и функциями, чтобы улучшить ваши возможности прогнозирования.
**Модели регрессии:** Наши модели регрессии предназначены для предсказания непрерывных числовых значений, что делает их идеальными для прогнозирования будущих тенденций и закономерностей во временных рядах. Используйте эти модели, чтобы получить представление о потенциальных будущих результатах на основе исторических данных.
| Модель | Источники | Поддержка целевых рядов:<br/><br/>Одномерные/<br/>Многомерные | Поддержка ковариат:<br/><br/>Наблюдаемые в прошлом/<br/>Известные в будущем/<br/>Статические | Вероятностное прогнозирование:<br/><br/>Выборки/<br/>Параметры распределения | Обучение и прогнозирование на нескольких рядах |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------|
| **Базовые модели**<br/>([LocalForecastingModel](https://unit8co.github.io/darts/userguide/covariates.html#local-forecasting-models-lfms)) | | | | | |
| [NaiveMean](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.baselines.html#darts.models.forecasting.baselines.NaiveMean) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [NaiveSeasonal](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.baselines.html#darts.models.forecasting.baselines.NaiveSeasonal) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [NaiveDrift](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.baselines.html#darts.models.forecasting.baselines.NaiveDrift) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [NaiveMovingAverage](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.baselines.html#darts.models.forecasting.baselines.NaiveMovingAverage) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| **Статистические / классические модели**<br/>([LocalForecastingModel](https://unit8co.github.io/darts/userguide/covariates.html#local-forecasting-models-lfms)) | | | | | |
| [ARIMA](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.arima.html#darts.models.forecasting.arima.ARIMA) | | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ 🔴 | 🔴 |
| [VARIMA](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.varima.html#darts.models.forecasting.varima.VARIMA) | | 🔴 ✅ | 🔴 ✅ 🔴 | ✅ 🔴 | 🔴 |
| [ExponentialSmoothing](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.exponential_smoothing.html#darts.models.forecasting.exponential_smoothing.ExponentialSmoothing) | | ✅ 🔴 | 🔴 🔴 🔴 | ✅ 🔴 | 🔴 |
| [Theta](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.theta.html#darts.models.forecasting.theta.Theta) и [FourTheta](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.theta.html#darts.models.forecasting.theta.FourTheta) | [Theta paper](https://robjhyndman.com/papers/Theta.pdf) & [4 Theta source](https://github.com/Mcompetitions/M4-methods/blob/master/4Theta%20method.R) | ✅ 🔴 | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [Prophet](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.prophet_model.html#darts.models.forecasting.prophet_model.Prophet) | [Prophet repo](https://github.com/facebook/prophet) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ 🔴 | 🔴 |
| [FFT](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.fft.html#darts.models.forecasting.fft.FFT) (быстрое преобразование Фурье) | | ✅ 🔴 | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [KalmanForecaster](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.kalman_forecaster.html#darts.models.forecasting.kalman_forecaster.KalmanForecaster) с использованием фильтра Калмана и N4SID для идентификации системы | [N4SID paper](https://people.duke.edu/~hpgavin/SystemID/References/VanOverschee-Automatica-1994.pdf) | ✅ ✅ | 🔴 ✅ 🔴 | ✅ 🔴 | 🔴 |
| [TBATS](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_tbats.html#darts.models.forecasting.sf_tbats.TBATS) | [TBATS paper](https://robjhyndman.com/papers/ComplexSeasonality.pdf) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
---
[Read more](https://github.com/unit8co/darts)