ProtoX-AD: Self-Explainable Time Series Anomaly Detection and Characterization

This is the official code for a PyTorch implementation of the paper ProtoX-AD: Self-Explainable Time Series Anomaly Detection and Characterization, available at:

https://arxiv.org/abs/2606.13277

ProtoX-AD is a self-supervised framework for time series anomaly detection that combines transformation-based representation learning with prototype-based characterization. The method is designed not only to detect anomalous time series, but also to provide insight into the types of anomaly patterns captured by the model through learned prototypes.

The code allows users to reproduce our experiments and easily apply ProtoX-AD to their own time series datasets. A step-by-step tutorial is provided in src/Tutorial.ipynb, where we show how to use the different components of the method, including data loading, transformation generation, model construction, training, anomaly detection, prototype-based characterization, and explanation analysis.

ProtoX-AD is designed to be easily adapted to different datasets. Users can define their own transformation module to generate dataset-specific augmented views and plug it directly into the ProtoX-AD pipeline. This plug-and-play design makes it simple to incorporate prior knowledge about the target problem while keeping the rest of the workflow unchanged.

Installation

The recommended Python version is Python 3.12.

Create and activate a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate

Then install the required dependencies:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

The main dependencies include PyTorch, Aeon, NumPy, pandas, scikit-learn, and Matplotlib.

Data

The UMD dataset is loaded automatically through Aeon when the corresponding experiment is executed.

The GTA and Yorkshire experiments require two additional datasets:

• GTA: Global temperature anomaly data containing the GISTEMP and gcag sources. The dataset can be obtained from the Global Temperature Time Series dataset.
• Yorkshire: Yorkshire Water 15-minute leakage data for the E1 area during 2016/2017. The dataset can be downloaded from the Yorkshire Water Leakage DMA 15-Minute Data repository.

After downloading the files, place them in the data/ directory using the following filenames:

data/temperatures_global.csv
data/E1 2016_2017.csv

The provided implementation does not apply additional normalization, standardization, or scaling to the input data.

Running the experiments

Experiments are launched using the generic runner in the src/ folder:

python src/run_protoxad.py --config configs/umd_manual.json

The runner receives a JSON configuration file through the --config argument. The configuration specifies the dataset, random seed, number of prototypes, transformation type, and dataset-specific parameters.

The available configurations are:

configs/
├── umd_manual.json
├── umd_neural.json
├── gta_manual.json
├── gta_neural.json
├── yorkshire_manual.json
└── yorkshire_neural.json

For example:

python src/run_protoxad.py --config configs/umd_manual.json
python src/run_protoxad.py --config configs/umd_neural.json
python src/run_protoxad.py --config configs/gta_manual.json
python src/run_protoxad.py --config configs/gta_neural.json
python src/run_protoxad.py --config configs/yorkshire_manual.json
python src/run_protoxad.py --config configs/yorkshire_neural.json

The default configurations use three prototypes per transformation class and up to 1,000 training epochs. The model uses early stopping and learning-rate scheduling during training.

Each experiment creates a separate directory under results/, containing:

config.json
results.json
prototypes.png
explanations.png

The results.json file contains the anomaly detection and characterization results, including AUROC, AUPR, Macro-F1, MAE, and runtime.

Transformation types

ProtoX-AD supports manually designed and neural transformation modules.

The manually designed transformations incorporate prior knowledge about the anomaly patterns in each dataset:

• UMD: bell-shaped patterns;
• GTA: warm and cold temperature shifts;
• Yorkshire: multiplicative increases associated with water leaks.

The neural transformation module learns a transformation network for each non-identity transformation class.

The transformation type is selected in the configuration file using:

"transformation_type": "manual"

or:

"transformation_type": "neural"

The transformation modules provide a common generate() interface, allowing users to define custom transformations and use them with the rest of the ProtoX-AD pipeline.

Dataset-specific parameters

For UMD, the normal class is specified using:

"dataset": "UMD",
"normal_class": "2"

For GTA, the data source is specified using:

"dataset": "GTA",
"source": "GISTEMP"

The available GTA sources are GISTEMP and gcag. To run the experiment on the gcag source, change the corresponding value to:

"source": "gcag"

For Yorkshire, the DMA, weekday, and percentile threshold are specified using:

"dataset": "Yorkshire",
"dma": 1,
"day": 0,
"percentile": 0.95

These parameters can be modified to run the experiment for different DMAs, weekdays, and percentile thresholds.

Reproducibility

Each configuration file contains a random seed:

"seed": 0

To run an experiment with a different seed, change this value before launching the runner. The complete configuration used for each experiment is saved in its output directory.

Citation

If you use ProtoX-AD in your research, please cite:

@article{sanchez2026protox,
  title={ProtoX-AD: Self-Explainable Time Series Anomaly Detection and Characterization},
  author={S{\'a}nchez-Ferrera, Aitor and Wetzer, Elisabeth and Wickstr{\o}m, Kristoffer and Kampffmeyer, Michael and Jenssen, Robert},
  journal={arXiv preprint arXiv:2606.13277},
  year={2026}
}