haomingz anomaly-detector
多方法异常检测工具，支持 Z-score、IQR（四分位距）、移动平均偏离三种检测方法，对检测到的异常自动分类标注为「可解释」或「需关注」。
能力概览
| 能力 | 说明 |
|---|---|
| Z-score 检测 | 基于标准差偏离程度识别异常，适合近似正态分布数据 |
| IQR 检测 | 基于四分位距识别异常，对偏态分布更稳健 |
| 移动平均偏离 | 基于滑动窗口均值偏离识别异常，适合时序数据 |
| 异常分类 | 综合多方法结果，将异常标注为「可解释」或「需关注」 |
Quick Start
# 使用全部方法检测
python3 scripts/anomaly_detector.py data.csv
# 指定方法和列
python3 scripts/anomaly_detector.py data.csv --methods z-score,iqr --columns price,volume
# 自定义阈值，输出到文件
python3 scripts/anomaly_detector.py data.csv --z-threshold 2.5 --window 7 --output result.json
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
csv_file |
位置参数 | (必填) | 输入 CSV 文件路径 |
--methods |
字符串 | z-score,iqr,moving-avg |
逗号分隔的检测方法 |
--columns |
字符串 | 全部数值列 | 逗号分隔的目标列名 |
--z-threshold |
浮点数 | 3.0 |
Z-score 判定阈值 |
--iqr-multiplier |
浮点数 | 1.5 |
IQR 倍数（1.5=普通异常, 3.0=极端异常） |
--window |
整数 | 5 |
移动平均窗口大小 |
--ma-threshold |
浮点数 | 2.0 |
移动平均偏离阈值（标准差倍数） |
--output |
字符串 | stdout | 输出文件路径（JSON 格式） |
异常分类规则
脚本会综合所有方法的检测结果，对每个异常点进行分类：
需关注（needs_attention）：满足以下任一条件
- 被 2 种及以上方法同时检出
- Z-score 绝对值 > 阈值 × 1.5（极端偏离）
- IQR 偏离超过 3 倍 IQR（极端离群）
可解释（explainable）：不满足上述条件的异常
- 仅被 1 种方法检出
- 偏离程度温和，可能是正常波动
输出结构
{
"summary": {
"total_rows": 100,
"columns_analyzed": ["price", "volume"],
"methods_used": ["z-score", "iqr", "moving-avg"],
"total_anomalies": 8,
"needs_attention": 3,
"explainable": 5
},
"anomalies": [
{
"row": 42,
"column": "price",
"value": 999.9,
"methods_detected": ["z-score", "iqr"],
"details": {
"z_score": 4.2,
"iqr_bounds": [10.0, 50.0]
},
"classification": "needs_attention",
"reason": "被 2 种方法同时检出，Z-score=4.2 远超阈值"
}
],
"column_stats": {
"price": {
"mean": 25.3,
"std": 5.1,
"q1": 21.0,
"q3": 29.5,
"iqr": 8.5,
"anomaly_count": 5
}
}
}
使用指南
- 准备数据：CSV 文件需包含表头行，数值列会被自动识别
- 选择方法：
- 数据近似正态分布 → 优先使用
z-score - 数据有偏态或不确定分布 → 优先使用
iqr - 时序数据关注趋势偏离 → 使用
moving-avg - 不确定时使用全部方法（默认），综合判断更可靠
- 数据近似正态分布 → 优先使用
- 解读结果：优先关注
needs_attention类异常，explainable类可作为参考
依赖
仅使用 Python 标准库，无需额外安装：
csv— CSV 文件读取json— JSON 输出math— 数学计算statistics— 统计函数