Anomaly detection identifies abnormal data points that significantly deviate from typical behavior. This is beneficial for numerous applications, such as cybersecurity and equipment monitoring.

This tutorial demonstrates how to use TimeGPT to detect anomalies in time series data. As an example, we’ll analyze the daily page visits to the Wikipedia page of Peyton Manning.

What you’ll learn

  • How to set up and configure the NixtlaClient.
  • How to detect anomalies in time series data using TimeGPT.
  • How to plot and interpret identified anomalies.
  • How to leverage exogenous (external) features in anomaly detection.
  • How to adjust sensitivity by modifying confidence intervals.

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.
1

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")
)

If you’re using an Azure AI endpoint, specify base_url accordingly.

nixtla_client = NixtlaClient(
    base_url="your azure ai endpoint",
    api_key="your api_key"
)
2

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

You can visualize the time series with the following command:

nixtla_client.plot(df, max_insample_length=365)

Figure 1. Peyton Manning Wikipedia page visits over time.

3

Step 3: 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()

The logs below indicate the different stages in the anomaly detection process.

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

When using Azure AI endpoints, set model="azureai".

nixtla_client.detect_anomalies(df, freq='D', model="azureai")

For the public API, available models include timegpt-1 and timegpt-1-long-horizon. See this tutorial for more details.

A False anomaly value indicates a normal data point; True identifies an outlier.

Plot the anomalies:

nixtla_client.plot(df, anomalies_df)

Figure 2. Anomalies detected in the Peyton Manning dataset.

Congratulations! You’ve successfully performed anomaly detection using TimeGPT. You now know how to import data, visualize anomalies, and fine-tune your detection criteria with exogenous features and different confidence levels.