Quickstart

Get started with TimeGPT’s historical anomaly detection capabilities.

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.

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_id	ds	y
0	0	2007-12-10	9.590761
1	0	2007-12-11	8.519590
2	0	2007-12-12	8.183677
3	0	2007-12-13	8.072467
4	0	2007-12-14	7.893572

Step 3: Visualize the Data

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.

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_id	ds	y	TimeGPT	TimeGPT-hi-99	TimeGPT-lo-99	anomaly
0	0	2008-01-10	8.281724	8.224187	9.503586	6.944788	False
1	0	2008-01-11	8.292799	8.151533	9.430932	6.872135	False
2	0	2008-01-12	8.199189	8.127243	9.406642	6.847845	False
3	0	2008-01-13	9.996522	8.917259	10.196658	7.637861	False
4	0	2008-01-14	10.127071	9.002326	10.281725	7.722928	False

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

Step 5: Review Anomalies

nixtla_client.plot(df, anomalies_df)

Figure 2. Anomalies detected in the Peyton Manning dataset.

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.