Quickstart

​

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

​

Step 3: Visualize the Data

You can visualize the time series with the following command:

nixtla_client.plot(df, max_insample_length=365)

​

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

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

​

Step 5: Review Anomalies

nixtla_client.plot(df, anomalies_df)

​

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.