Skip to main content

What you'll learn

  • Understand how TimeGPT detects anomalies in historical time series.
  • How to setup and detect anomalies with TimeGPT.
  • How to plot and interpret identified anomalies.

Key benefits

  • Quickly identify outliers in large time series.
  • Improve decision-making by focusing on unusual data points.
  • Automate anomaly alerts to save time and resources.

​
What Is Historical Anomaly Detection?

Historical anomaly detection is a technique that identifies data points that significantly deviate from expected patterns in a time series. This technique is useful for uncovering potential fraud, security breaches, or other unusual events.

​
Overview of TimeGPT’s Historical Anomaly Detection

TimeGPT’s historical anomaly detection works by:
  1. Generating predictions for future values (or reconstructing missing values) within your historical time series.
  2. Constructing a confidence interval based on the model’s predictions.
  3. Flagging any historical data point that falls outside your chosen confidence interval as an anomaly.

​
Quickstart Example

You’ll learn how historical anomaly detection works—illustrated through an example analyzing daily visits to the Wikipedia page of Peyton Manning. Open In Colab

​
Step 1: Import Packages and Create a NixtlaClient Instance

We’ll start by importing required packages and setting up our API key. 
import pandas as pd
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'  # Defaults to os.environ.get("NIXTLA_API_KEY")
)

​
Step 2: Load the Dataset

This dataset tracks the daily visits to the Wikipedia page of Peyton Manning. 
df = pd.read_csv('https://datasets-nixtla.s3.amazonaws.com/peyton-manning.csv')
df.head()
unique_iddsy
002007-12-109.590761
102007-12-118.519590
202007-12-128.183677
302007-12-138.072467
402007-12-147.893572

​
Step 3: Visualize the Data

You can visualize the time series with the following command: 
nixtla_client.plot(df, max_insample_length=365)
Data plot

​
Step 4: Perform Anomaly Detection

By default, TimeGPT uses a 99% confidence interval. Points outside this interval are flagged as anomalies. 
anomalies_df = nixtla_client.detect_anomalies(df, freq='D')
anomalies_df.head()
unique_iddsyTimeGPTTimeGPT-hi-99TimeGPT-lo-99anomaly
002008-01-108.2817248.2241879.5035866.944788False
102008-01-118.2927998.1515339.4309326.872135False
202008-01-128.1991898.1272439.4066426.847845False
302008-01-139.9965228.91725910.1966587.637861False
402008-01-1410.1270719.00232610.2817257.722928False
A False anomaly value indicates a normal data point; True identifies an outlier.

​
Step 5: Review Anomalies

nixtla_client.plot(df, anomalies_df)
Anomalies plot

​
Step 6: Inspect and Iterate

Inspect the anomalies flagged by the model. These points are potential indicators of significant deviations in your data.If you find that the model is overly sensitive or missing critical outliers, adjust the confidence interval or include additional features (e.g., exogenous data, date features) to improve detection accuracy.
Congratulations! You’ve successfully performed anomaly detection using TimeGPT. You can now start experimenting with this example or apply it to your own data. For advanced tips on improving detection performance, explore the following sections on using exogenous variables and adjusting confidence intervals.