TODS：自动化时间序列异常检测系统

中文文档

TODS 是一个用于多变量时间序列数据异常检测的全栈自动化机器学习系统。TODS 提供了构建基于机器学习的异常检测系统的完整模块，包括：数据处理、时间序列处理、特征分析（提取）、检测算法以及强化模块。这些模块提供的功能涵盖了通用的数据预处理、时间序列数据平滑/转换、从时域/频域提取特征、多种检测算法，以及通过引入人工专家知识来校准系统。TODS 可以处理时间序列数据中的三种常见异常检测场景：逐点检测（将时间点识别为异常）、模式级检测（将子序列识别为异常）和系统级检测（将一组时间序列识别为异常），并为此提供了广泛的相应算法。本软件包由 DATA Lab @ Rice University 开发。

TODS 的特点包括：

• 全栈机器学习系统，支持从预处理、特征提取到检测算法，以及人机交互界面等完整组件。
• 丰富的算法库，既包含 PyOD 支持的所有逐点检测算法，也包含最先进的模式级（集体）检测算法，如 DeepLog、Telemanon，同时还提供用于系统级检测的各种集成算法。
• 自动化机器学习，旨在实现无知识依赖的过程，通过自动搜索现有模块的最佳组合，根据给定数据构建最优的处理管道。

示例与教程

• 通用用法：在 Colab 中查看
• 欺诈检测：在 Colab 中查看
• 区块链：在 Colab 中查看

资源

• API 文档：http://tods-doc.github.io
• 论文：https://arxiv.org/abs/2009.09822
• 相关项目：AutoVideo：自动化视频动作识别系统
• :loudspeaker: 想了解更多关于数据流水线搜索的内容吗？请查阅我们的 以数据为中心的 AI 综述 和 以数据为中心的 AI 资源！

引用本工作：

如果您认为本工作有用，请引用如下：

@article{Lai_Zha_Wang_Xu_Zhao_Kumar_Chen_Zumkhawaka_Wan_Martinez_Hu_2021, 
	title={TODS: An Automated Time Series Outlier Detection System}, 
	volume={35}, 
	number={18}, 
	journal={Proceedings of the AAAI Conference on Artificial Intelligence}, 
	author={Lai, Kwei-Herng and Zha, Daochen and Wang, Guanchu and Xu, Junjie and Zhao, Yue and Kumar, Devesh and Chen, Yile and Zumkhawaka, Purav and Wan, Minyang and Martinez, Diego and Hu, Xia}, 
	year={2021}, month={May}, 
	pages={16060-16062} 
}

安装

本软件包适用于 Python 3.7+ 和 pip 19+。您需要在系统上安装以下软件包（适用于 Debian/Ubuntu）：

sudo apt-get install libssl-dev libcurl4-openssl-dev libyaml-dev build-essential libopenblas-dev libcap-dev ffmpeg

克隆仓库（如果您在中国且 GitHub 访问较慢，可以使用 Gitee 上的镜像）：

git clone https://github.com/datamllab/tods.git

使用 pip 在本地安装：

cd tods
pip install -e .

示例

示例位于 /examples 目录下。对于基本用法，您可以对给定的数据集评估一个处理管道。这里我们提供了一个加载默认管道并在 Yahoo 数据集的一个子集上进行评估的示例。

import pandas as pd

from tods import schemas as schemas_utils
from tods import generate_dataset, evaluate_pipeline

table_path = 'datasets/anomaly/raw_data/yahoo_sub_5.csv'
target_index = 6 # 目标列是哪一列
metric = 'F1_MACRO' # 对标签 0 和 1 的 F1 分数

# 读取数据并生成数据集
df = pd.read_csv(table_path)
dataset = generate_dataset(df, target_index)

# 加载默认管道
pipeline = schemas_utils.load_default_pipeline()

# 运行管道
pipeline_result = evaluate_pipeline(dataset, pipeline, metric)
print(pipeline_result)

我们还提供了 AutoML 支持，帮助您自动为您的数据找到合适的处理管道。

import pandas as pd

from axolotl.backend.simple import SimpleRunner

from tods import generate_dataset, generate_problem
from tods.searcher import BruteForceSearch

# 一些信息
table_path = 'datasets/yahoo_sub_5.csv'
target_index = 6 # 目标列是哪一列
time_limit = 30 # 搜索时长为多少秒
metric = 'F1_MACRO' # 对标签 0 和 1 的 F1 分数

# 读取数据并生成数据集和问题描述
df = pd.read_csv(table_path)
dataset = generate_dataset(df, target_index=target_index)
problem_description = generate_problem(dataset, metric)

# 启动后端
backend = SimpleRunner(random_seed=0)

# 启动搜索算法
search = BruteForceSearch(problem_description=problem_description,
                          backend=backend)

# 寻找最佳管道
best_runtime, best_pipeline_result = search.search_fit(input_data=[dataset], time_limit=time_limit)
best_pipeline = best_runtime.pipeline
best_output = best_pipeline_result.output

# 评估最佳管道
best_scores = search.evaluate(best_pipeline).scores

致谢

我们衷心感谢美国国防高级研究计划局（DARPA）的数据驱动模型发现计划（D3M）。

TODS 快速上手指南

TODS (Automated Time-series Outlier Detection System) 是一个用于多变量时间序列异常检测的全栈自动化机器学习系统。它支持从数据预处理、特征提取到检测算法及人工校准的完整流程，涵盖点级、模式级和系统级三种异常检测场景。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: 推荐 Debian/Ubuntu 系列 Linux 发行版。
• Python 版本: Python 3.7 或更高版本。
• 包管理器: pip 19 或更高版本。
• 系统依赖: 需要安装以下底层开发库：

sudo apt-get install libssl-dev libcurl4-openssl-dev libyaml-dev build-essential libopenblas-dev libcap-dev ffmpeg

安装步骤

1. 克隆代码仓库

国内用户若访问 GitHub 较慢，推荐使用 Gitee 镜像源加速下载：

# 使用 Gitee 镜像（推荐国内用户）
git clone https://gitee.com/daochenzha/tods.git

# 或者使用 GitHub 官方源
# git clone https://github.com/datamllab/tods.git

2. 本地安装

进入项目目录并使用 pip 进行可编辑安装：

cd tods
pip install -e .

基本使用

以下示例展示如何加载默认管道并在 Yahoo 数据集子集上评估异常检测效果。

示例：运行默认检测管道

import pandas as pd

from tods import schemas as schemas_utils
from tods import generate_dataset, evaluate_pipeline

# 配置参数
table_path = 'datasets/anomaly/raw_data/yahoo_sub_5.csv'
target_index = 6 # 目标列索引
metric = 'F1_MACRO' # 评估指标：标签 0 和 1 的宏平均 F1 分数

# 读取数据并生成数据集对象
df = pd.read_csv(table_path)
dataset = generate_dataset(df, target_index)

# 加载默认管道
pipeline = schemas_utils.load_default_pipeline()

# 运行管道并输出结果
pipeline_result = evaluate_pipeline(dataset, pipeline, metric)
print(pipeline_result)

进阶：自动搜索最优管道 (AutoML)

TODS 支持自动搜索最适合当前数据的管道组合：

import pandas as pd

from axolotl.backend.simple import SimpleRunner

from tods import generate_dataset, generate_problem
from tods.searcher import BruteForceSearch

# 配置参数
table_path = 'datasets/yahoo_sub_5.csv'
target_index = 6 
time_limit = 30 # 搜索时间限制（秒）
metric = 'F1_MACRO'

# 准备数据和问题描述
df = pd.read_csv(table_path)
dataset = generate_dataset(df, target_index=target_index)
problem_description = generate_problem(dataset, metric)

# 初始化后端和搜索算法
backend = SimpleRunner(random_seed=0)
search = BruteForceSearch(problem_description=problem_description,
                          backend=backend)

# 执行搜索以找到最佳管道
best_runtime, best_pipeline_result = search.search_fit(input_data=[dataset], time_limit=time_limit)
best_pipeline = best_runtime.pipeline

# 评估最佳管道性能
best_scores = search.evaluate(best_pipeline).scores