
Uma biblioteca python para previsão e detecção de anomalias em séries temporais, projetada para ser fácil de usar.
# Séries Temporais Descomplicadas em 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** é uma biblioteca Python para previsão e detecção de anomalias
em séries temporais de forma amigável ao usuário. Ela contém uma variedade de modelos, desde clássicos como ARIMA até
redes neurais profundas. Todos os modelos de previsão podem ser usados da mesma forma,
utilizando as funções `fit()` e `predict()`, de maneira semelhante ao scikit-learn.
A biblioteca também facilita o backtesting de modelos,
a combinação das previsões de vários modelos e a consideração de dados externos.
O Darts suporta tanto séries temporais e modelos univariados quanto multivariados.
Os modelos baseados em ML podem ser treinados em conjuntos de dados potencialmente grandes contendo múltiplas séries
temporais, e alguns dos modelos oferecem um rico suporte para previsão probabilística.
O Darts também oferece amplas capacidades de detecção de anomalias.
Por exemplo, é trivial aplicar modelos PyOD em séries temporais para obter pontuações de anomalia,
ou envolver qualquer um dos modelos de previsão ou filtragem do Darts para obter modelos
de detecção de anomalias completos.
## Documentação
* [Início Rápido](https://unit8co.github.io/darts/quickstart/00-quickstart.html)
* [Guia do Usuário](https://unit8co.github.io/darts/userguide.html)
* [Referência da API](https://unit8co.github.io/darts/generated_api/darts.html)
* [Exemplos](https://unit8co.github.io/darts/examples.html)
### Introduções de Alto Nível
* [Post de Blog Introdutório](https://medium.com/unit8-machine-learning-publication/darts-time-series-made-easy-in-python-5ac2947a8878)
* [Vídeo de introdução (25 minutos)](https://youtu.be/g6OXDnXEtFA)
### Artigos sobre Tópicos Selecionados
* [Treinando Modelos em Múltiplas Séries Temporais](https://medium.com/unit8-machine-learning-publication/training-forecasting-models-on-multiple-time-series-with-darts-dc4be70b1844)
* [Usando Covariáveis Passadas e Futuras](https://medium.com/unit8-machine-learning-publication/time-series-forecasting-using-past-and-future-external-data-with-darts-1f0539585993)
* [Redes Convolucionais Temporais e Previsão](https://medium.com/unit8-machine-learning-publication/temporal-convolutional-networks-and-forecasting-5ce1b6e97ce4)
* [Previsão Probabilística](https://medium.com/unit8-machine-learning-publication/probabilistic-forecasting-in-darts-e88fbe83344e)
* [Aprendizado por Transferência para Previsão de Séries Temporais](https://medium.com/unit8-machine-learning-publication/transfer-learning-for-time-series-forecasting-87f39e375278)
* [Reconciliação de Previsões Hierárquicas](https://medium.com/unit8-machine-learning-publication/hierarchical-forecast-reconciliation-with-darts-8b4b058bb543)
## Instalação Rápida
Recomendamos primeiro configurar um ambiente Python limpo para o seu projeto com Python 3.11+ usando sua ferramenta favorita
([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/) com
ou sem [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)).
Depois que seu ambiente estiver configurado, você pode instalar o darts usando pip:
pip install darts
Para mais detalhes, você pode consultar nossas
[instruções de instalação](https://github.com/unit8co/darts/blob/master/INSTALL.md).
## Exemplo de Uso
### Previsão
Crie um objeto `TimeSeries` a partir de um Pandas DataFrame e divida-o em séries de treino/validação:
```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:]
```
Ajuste um modelo de suavização exponencial e faça uma previsão (probabilística) sobre a duração da série de validação:
```python
from darts.models import ExponentialSmoothing
model = ExponentialSmoothing()
model.fit(train)
prediction = model.predict(len(val), num_samples=1000)
```
Plote a mediana, os percentis 5 e 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="exemplo de previsão do darts" />
</div>
### Detecção de Anomalias
Carregue uma série multivariada, faça o trim, mantenha 2 componentes, divida os conjuntos de treino e validação:
```python
from darts.datasets import ETTh2Dataset
series = ETTh2Dataset().load()[:10000][["MUFL", "LULL"]]
train, val = series.split_before(0.6)
```
Construa um scorer de anomalias k-means, treine-o no conjunto de treino
e use-o no conjunto de validação para obter pontuações de anomalia:
```python
from darts.ad import KMeansScorer
scorer = KMeansScorer(k=2, window=5)
scorer.fit(train)
anom_score = scorer.score(val)
```
Construa um detector de anomalias binário e treine-o sobre as pontuações de treino,
depois use-o sobre as pontuações de validação para obter a classificação binária de anomalias:
```python
from darts.ad import QuantileDetector
detector = QuantileDetector(high_quantile=0.99)
detector.fit(scorer.score(train))
binary_anom = detector.detect(anom_score)
```
Plot (deslocando e escalando algumas das séries
para fazer tudo aparecer na mesma figura):
```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="exemplo de detecção de anomalias do darts" />
</div>
## Funcionalidades
* **Modelos de Previsão:** Uma grande coleção de modelos de previsão para tarefas de regressão e classificação; desde modelos estatísticos (como
ARIMA) até modelos de aprendizado profundo (como N-BEATS). Veja os [modelos de previsão](#forecasting-models) abaixo.
* **Detecção de Anomalias** O módulo `darts.ad` contém uma coleção de pontuadores de anomalias,
detectores e agregadores, que podem ser combinados para detectar anomalias em séries temporais.
É fácil envolver qualquer um dos modelos de previsão ou filtragem do Darts para construir
um modelo completo de detecção de anomalias que compara previsões com valores reais.
O `PyODScorer` torna trivial o uso de detectores PyOD em séries temporais.
* **Suporte Multivariado:** `TimeSeries` pode ser multivariada - ou seja, conter múltiplas
dimensões/colunas variantes no tempo em vez de um único valor escalar. Muitos modelos podem consumir e produzir séries multivariadas.
* **Treinamento com Múltiplas Séries (Modelos Globais):** Todos os modelos baseados em aprendizado de máquina (incluindo todas as redes neurais)
suportam treinamento em múltiplas séries (potencialmente multivariadas). Isso também pode escalar para grandes conjuntos de dados.
* **Suporte Probabilístico:** Objetos `TimeSeries` podem (opcionalmente) representar séries temporais
estocásticas; isso pode, por exemplo, ser usado para obter intervalos de confiança, e muitos modelos suportam diferentes
tipos de previsão probabilística (como estimar distribuições paramétricas ou quantis).
Alguns pontuadores de detecção de anomalias também são capazes de explorar essas distribuições preditivas.
* **Suporte à Predição Conforme:** Nossos modelos de predição conforme permitem gerar previsões probabilísticas com
intervalos de quantis calibrados para qualquer modelo global de previsão pré-treinado.
* **Suporte a Covariáveis Passadas e Futuras:** Muitos modelos no Darts suportam séries temporais de covariáveis
observadas no passado e/ou conhecidas no futuro (dados externos) como entradas para produzir previsões.
* **Suporte a Covariáveis Estáticas:** Além de dados dependentes do tempo, `TimeSeries` também pode conter
dados estáticos para cada dimensão, que podem ser explorados por alguns modelos.
* **Reconciliação Hierárquica:** O Darts oferece transformadores para realizar reconciliação.
Estes podem fazer com que as previsões somem de forma que respeite a hierarquia subjacente.
* **Modelos de Regressão:** É possível plugar qualquer modelo compatível com scikit-learn
para obter previsões como funções de valores defasados da série alvo e covariáveis.
* **Treinamento com Pesos de Amostra:** Todos os modelos globais suportam treinamento com pesos de amostra. Eles podem ser
aplicados a cada observação, passo de tempo previsto e coluna alvo.
* **Deslocamento do Início da Previsão:** Todos os modelos globais suportam treinamento e predição em uma janela de saída deslocada.
Isso é útil, por exemplo, para previsões de Mercado Day-Ahead, ou quando as covariáveis (ou séries alvo) são reportadas
com atraso.
* **Explicabilidade:** O Darts tem a capacidade de *explicar* alguns modelos de previsão usando valores SHAP.
* **Processamento de Dados:** Ferramentas para aplicar (e reverter) facilmente transformações comuns em
dados de séries temporais (escalonamento, preenchimento de valores ausentes, diferenciação, boxcox, ...)
* **Métricas:** Uma variedade de métricas para avaliar a qualidade do ajuste de séries temporais;
desde pontuações R2 até Erro Absoluto Escalonado Médio.
* **Backtesting:** Utilitários para simular previsões históricas, usando janelas de tempo móveis.
* **Suporte ao PyTorch Lightning:** Todos os modelos de aprendizado profundo são implementados usando PyTorch Lightning,
suportando, entre outras coisas, callbacks personalizados, treinamento em GPUs/TPUs e treinadores personalizados.
* **Integração com MLflow:** Integração com MLflow para rastreamento automatizado, comparação e persistência
de experimentos de modelos de previsão do Darts. Veja o [notebook de início rápido do MLflow](https://unit8co.github.io/darts/examples/29-MLflow-examples.html) para exemplos.
* **Modelos de Filtragem:** O Darts oferece três modelos de filtragem: `KalmanFilter`, `GaussianProcessFilter`,
e `MovingAverageFilter`, que permitem filtrar séries temporais e, em alguns casos, obter inferências
probabilísticas dos estados/valores subjacentes.
* **Conjuntos de Dados** O submódulo `darts.datasets` contém alguns conjuntos de dados populares de séries temporais para experimentação
rápida e reproduzível.
* **Compatibilidade com Múltiplos Backends:** Objetos `TimeSeries` podem ser criados a partir de e exportados para vários backends como pandas, polars, numpy, pyarrow, xarray, e mais, facilitando a integração perfeita com diferentes bibliotecas de processamento de dados.
## Modelos de Previsão
Aqui está uma análise dos modelos de previsão atualmente implementados no Darts. Nossa suíte inclui modelos de regressão e classificação, cada um adaptado para tarefas específicas de previsão. Estamos comprometidos em expandir nossa oferta com novos modelos e funcionalidades para aprimorar suas capacidades de previsão.
**Modelos de Regressão:** Nossos modelos de regressão são projetados para prever valores numéricos contínuos, tornando-os ideais para prever tendências e padrões futuros em dados de séries temporais. Utilize estes modelos para obter insights sobre possíveis resultados futuros com base em dados históricos.
| Model | Sources | Target Series Support:<br/><br/>Univariate/<br/>Multivariate | Covariates Support:<br/><br/>Past-observed/<br/>Future-known/<br/>Static | Probabilistic Forecasting:<br/><br/>Sampled/<br/>Distribution Parameters | Training & Forecasting on Multiple Series |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------|
| **Modelos Baseline**<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) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| **Modelos Estatísticos / Clássicos**<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) e [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) (Fast Fourier Transform) | | ✅ 🔴 | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| [KalmanForecaster](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.kalman_forecaster.html#darts.models.forecasting.kalman_forecaster.KalmanForecaster) usando o filtro de Kalman e N4SID para identificação de sistemas | [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) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| método [Croston](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_croston.html#darts.models.forecasting.sf_croston.Croston) | | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [StatsForecastModel](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_model.html#darts.models.forecasting.sf_model.StatsForecastModel) wrapper em torno de qualquer modelo [StatsForecast](https://nixtlaverse.nixtla.io/statsforecast/index.html#models) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoARIMA](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_arima.html#darts.models.forecasting.sf_auto_arima.AutoARIMA) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoETS](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_ets.html#darts.models.forecasting.sf_auto_ets.AutoETS) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoCES](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_ces.html#darts.models.forecasting.sf_auto_ces.AutoCES) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoMFLES](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_mfles.html#darts.models.forecasting.sf_auto_mfles.AutoMFLES) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoTBATS](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_tbats.html#darts.models.forecasting.sf_auto_tbats.AutoTBATS) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| [AutoTheta](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.sf_auto_theta.html#darts.models.forecasting.sf_auto_theta.AutoTheta) | [Nixtla's statsforecast](https://github.com/Nixtla/statsforecast) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
---
[Read more](https://github.com/unit8co/darts)