outlier-scan

# anomaly-detector 多方法异常检测工具，支持 Z-score、IQR（四分位距）、移动平均偏离三种检测方法，对检测到的异常自动分类标注为「可解释」或「需关注」。 ## 能力概览 | 能力 | 说明 | |------|------| | Z-score 检测 | 基于标准差偏离程度识别异常，适合近似正态分布数据 | | IQR 检测 | 基于四分位距识别异常，对偏态分布更稳健 | | 移动平均偏离 | 基于滑动窗口均值偏离识别异常，适合时序数据 | | 异常分类 | 综合多方法结果，将异常标注为「可解释」或「需关注」 | ## Quick Start ```bash # 使用全部方法检测 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 种方法检出 - 偏离程度温和，可能是正常波动 ## 输出结构 ```json { "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 } } } ``` ## 使用指南 1. **准备数据**：CSV 文件需包含表头行，数值列会被自动识别 2. **选择方法**： - 数据近似正态分布 → 优先使用 `z-score` - 数据有偏态或不确定分布 → 优先使用 `iqr` - 时序数据关注趋势偏离 → 使用 `moving-avg` - 不确定时使用全部方法（默认），综合判断更可靠 3. **解读结果**：优先关注 `needs_attention` 类异常，`explainable` 类可作为参考 ## 依赖 仅使用 Python 标准库，无需额外安装： - `csv` — CSV 文件读取 - `json` — JSON 输出 - `math` — 数学计算 - `statistics` — 统计函数