
Una libreria Python per previsioni intuitive e rilevamento di anomalie su serie temporali.
# Serie Temporali Rese Semplici in 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** è una libreria Python per il forecasting e il rilevamento di anomalie
su serie temporali, pensata per essere facile da usare. Contiene una varietà di modelli, dai classici come ARIMA
alle reti neurali profonde. Tutti i modelli di forecasting possono essere utilizzati allo stesso modo,
tramite le funzioni `fit()` e `predict()`, in modo simile a scikit-learn.
La libreria semplifica inoltre il backtesting dei modelli,
la combinazione delle previsioni di più modelli e la considerazione di dati esterni.
Darts supporta sia serie temporali e modelli univariati che multivariati.
I modelli basati su ML possono essere addestrati su dataset potenzialmente grandi contenenti più serie
temporali, e alcuni dei modelli offrono un ricco supporto per il forecasting probabilistico.
Darts offre anche ampie capacità di rilevamento di anomalie.
Ad esempio, è banale applicare modelli PyOD su serie temporali per ottenere punteggi di anomalia,
oppure incapsulare qualsiasi modello di forecasting o filtraggio di Darts per ottenere modelli
di rilevamento di anomalie completi.
## Documentazione
* [Guida rapida](https://unit8co.github.io/darts/quickstart/00-quickstart.html)
* [Guida utente](https://unit8co.github.io/darts/userguide.html)
* [Riferimento API](https://unit8co.github.io/darts/generated_api/darts.html)
* [Esempi](https://unit8co.github.io/darts/examples.html)
### Introduzioni di alto livello
* [Post introduttivo sul blog](https://medium.com/unit8-machine-learning-publication/darts-time-series-made-easy-in-python-5ac2947a8878)
* [Video introduttivo (25 minuti)](https://youtu.be/g6OXDnXEtFA)
### Articoli su argomenti selezionati
* [Addestrare modelli su più serie temporali](https://medium.com/unit8-machine-learning-publication/training-forecasting-models-on-multiple-time-series-with-darts-dc4be70b1844)
* [Utilizzo di covariate passate e future](https://medium.com/unit8-machine-learning-publication/time-series-forecasting-using-past-and-future-external-data-with-darts-1f0539585993)
* [Reti convoluzionali temporali e forecasting](https://medium.com/unit8-machine-learning-publication/temporal-convolutional-networks-and-forecasting-5ce1b6e97ce4)
* [Forecasting probabilistico](https://medium.com/unit8-machine-learning-publication/probabilistic-forecasting-in-darts-e88fbe83344e)
* [Transfer learning per il forecasting di serie temporali](https://medium.com/unit8-machine-learning-publication/transfer-learning-for-time-series-forecasting-87f39e375278)
* [Riconciliazione di previsioni gerarchiche](https://medium.com/unit8-machine-learning-publication/hierarchical-forecast-reconciliation-with-darts-8b4b058bb543)
## Installazione rapida
Consigliamo di configurare innanzitutto un ambiente Python pulito per il vostro progetto con Python 3.11+ utilizzando il vostro strumento preferito
([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/) con
o senza [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)).
Una volta configurato l'ambiente, potete installare darts usando pip:
pip install darts
Per maggiori dettagli potete consultare le nostre
[istruzioni di installazione](https://github.com/unit8co/darts/blob/master/INSTALL.md).
## Esempio di utilizzo
### Forecasting
Create un oggetto `TimeSeries` da un Pandas DataFrame e dividetelo in serie di training/validation:
```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:]
```
Adatta un modello di smoothing esponenziale e fai una previsione (probabilistica) sulla durata della serie di validazione:
```python
from darts.models import ExponentialSmoothing
model = ExponentialSmoothing()
model.fit(train)
prediction = model.predict(len(val), num_samples=1000)
```
Traccia la mediana, il 5° e il 95° percentile:
```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="esempio di previsione darts" />
</div>
### Rilevamento delle anomalie
Carica una serie multivariata, ritagliala, mantieni 2 componenti, suddividi i set di addestramento e validazione:
```python
from darts.datasets import ETTh2Dataset
series = ETTh2Dataset().load()[:10000][["MUFL", "LULL"]]
train, val = series.split_before(0.6)
```
Costruisci uno scorer di anomalie k-means, addestralo sul set di addestramento
e usalo sul set di validazione per ottenere i punteggi di anomalia:
```python
from darts.ad import KMeansScorer
scorer = KMeansScorer(k=2, window=5)
scorer.fit(train)
anom_score = scorer.score(val)
```
Crea un rilevatore di anomalie binarie e addestralo sui punteggi di training,
poi usalo sui punteggi di validazione per ottenere una classificazione binaria delle anomalie:
```python
from darts.ad import QuantileDetector
detector = QuantileDetector(high_quantile=0.99)
detector.fit(scorer.score(train))
binary_anom = detector.detect(anom_score)
```
Traccia (spostando e scalando alcune delle serie
per far apparire tutto sulla stessa 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="esempio di rilevamento anomalie con darts" />
</div>
## Funzionalità
* **Modelli di Previsione:** Un'ampia collezione di modelli di previsione per attività di regressione e classificazione; dai modelli statistici (come
ARIMA) ai modelli di deep learning (come N-BEATS). Vedi i [modelli di previsione](#forecasting-models) di seguito.
* **Rilevamento delle Anomalie** Il modulo `darts.ad` contiene una collezione di scorer di anomalie,
rilevatori e aggregatori, che possono essere combinati per rilevare anomalie nelle serie temporali.
È facile avvolgere qualsiasi modello di previsione o filtraggio di Darts per costruire
un modello completo di rilevamento delle anomalie che confronta le previsioni con i valori effettivi.
Il `PyODScorer` rende banale l'uso dei rilevatori PyOD sulle serie temporali.
* **Supporto Multivariato:** `TimeSeries` può essere multivariata - cioè contenere più dimensioni/colonne
variabili nel tempo invece di un singolo valore scalare. Molti modelli possono consumare e produrre serie multivariate.
* **Addestramento su Serie Multiple (Modelli Globali):** Tutti i modelli basati su machine learning (incluse tutte le reti neurali)
supportano l'addestramento su più serie (potenzialmente multivariate). Questo può scalare anche su grandi dataset.
* **Supporto Probabilistico:** Gli oggetti `TimeSeries` possono (opzionalmente) rappresentare serie temporali
stocastiche; questo può essere utilizzato ad esempio per ottenere intervalli di confidenza, e molti modelli supportano diverse
varianti di previsione probabilistica (come la stima di distribuzioni parametriche o quantili).
Alcuni scorer di rilevamento delle anomalie sono anche in grado di sfruttare queste distribuzioni predittive.
* **Supporto alla Conformal Prediction:** I nostri modelli di conformal prediction permettono di generare previsioni probabilistiche con
intervalli quantilici calibrati per qualsiasi modello di previsione globale pre-addestrato.
* **Supporto alle Covariate Passate e Future:** Molti modelli in Darts supportano serie temporali di covariate (dati esterni)
osservate nel passato e/o note nel futuro come input per produrre previsioni.
* **Supporto alle Covariate Statiche:** Oltre ai dati dipendenti dal tempo, `TimeSeries` può anche contenere
dati statici per ciascuna dimensione, che possono essere sfruttati da alcuni modelli.
* **Riconciliazione Gerarchica:** Darts offre transformer per eseguire la riconciliazione.
Questi possono far quadrare le previsioni in modo che rispettino la gerarchia sottostante.
* **Modelli di Regressione:** È possibile inserire qualsiasi modello compatibile con scikit-learn
per ottenere previsioni come funzioni dei valori ritardati della serie target e delle covariate.
* **Addestramento con Pesi Campione:** Tutti i modelli globali supportano l'addestramento con pesi campione. Possono essere
applicati a ciascuna osservazione, passo temporale previsto e colonna target.
* **Spostamento dell'Inizio della Previsione:** Tutti i modelli globali supportano l'addestramento e la previsione su una finestra di output spostata.
Questo è utile ad esempio per le previsioni del mercato Day-Ahead, o quando le covariate (o le serie target) sono riportate
con un ritardo.
* **Spiegabilità:** Darts ha la capacità di *spiegare* alcuni modelli di previsione utilizzando i valori SHAP.
* **Elaborazione dei Dati:** Strumenti per applicare (e annullare) facilmente trasformazioni comuni sui
dati delle serie temporali (scaling, riempimento dei valori mancanti, differenziazione, boxcox, ...)
* **Metriche:** Una varietà di metriche per valutare la bontà di adattamento delle serie temporali;
dai punteggi R2 al Mean Absolute Scaled Error.
* **Backtesting:** Utilità per simulare previsioni storiche, utilizzando finestre temporali mobili.
* **Supporto a PyTorch Lightning:** Tutti i modelli di deep learning sono implementati utilizzando PyTorch Lightning,
supportando tra le altre cose callback personalizzate, addestramento su GPU/TPU e trainer personalizzati.
* **Integrazione con MLflow:** Integrazione con MLflow per il tracciamento automatizzato, il confronto e la persistenza
degli esperimenti sui modelli di previsione di Darts. Vedi il [notebook di avvio rapido MLflow](https://unit8co.github.io/darts/examples/29-MLflow-examples.html) per esempi.
* **Modelli di Filtraggio:** Darts offre tre modelli di filtraggio: `KalmanFilter`, `GaussianProcessFilter`,
e `MovingAverageFilter`, che permettono di filtrare le serie temporali, e in alcuni casi ottenere inferenze
probabilistiche degli stati/valori sottostanti.
* **Dataset** Il sottomodulo `darts.datasets` contiene alcuni popolari dataset di serie temporali per una sperimentazione
rapida e riproducibile.
* **Compatibilità con Molteplici Backend:** Gli oggetti `TimeSeries` possono essere creati da ed esportati verso vari backend come pandas, polars, numpy, pyarrow, xarray e altri, facilitando l'integrazione senza soluzione di continuità con diverse librerie di elaborazione dati.
## Modelli di Previsione
Ecco una panoramica dei modelli di previsione attualmente implementati in Darts. La nostra suite include sia modelli di regressione che di classificazione, ciascuno adattato a specifiche attività di previsione. Ci impegniamo ad ampliare la nostra offerta con nuovi modelli e funzionalità per migliorare le vostre capacità di previsione.
**Modelli di Regressione:** I nostri modelli di regressione sono progettati per prevedere valori numerici continui, rendendoli ideali per prevedere tendenze e pattern futuri nei dati delle serie temporali. Utilizza questi modelli per ottenere informazioni sui potenziali risultati futuri basati sui dati storici.
| 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 |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------|
| **Modelli 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) | | ✅ ✅ | 🔴 🔴 🔴 | 🔴 🔴 | 🔴 |
| **Modelli Statistici / Classici**<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) che utilizza il filtro di Kalman e N4SID per l'identificazione del sistema | [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) | ✅ 🔴 | 🔴 ✅ 🔴 | ✅ ✅ | 🔴 |
| Metodo [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 per qualsiasi modello [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)