bi-anomaly-detection

name	bi-anomaly-detection
description	基于阈值检测时间序列中的显著异常波动点。当需要找出指标异常波动日期、识别数据异动时调用。

bi-anomaly-detection

基于阈值识别时间序列中的显著异常波动点，常见场景：

• 日常分析：在指标分析流程中，对北极星指标进行异常波动点识别
• 监控告警：对实时/定时指标数据进行异常检测，触发告警

执行步骤

1：数据准备

包含时间序列数据的 CSV 文件，至少包含以下两列：

列	说明	示例
日期列	时间标识	日期
指标列	需要检测的指标值	访问用户数

示例：

日期,访问用户数
2025-01-01,10000
2025-01-02,10500
2025-01-03,9800

若上游步骤已产出可用数据文件则直接使用，否则自行取数。

2：选择对比逻辑

根据业务场景按需选择对比逻辑：

对比逻辑	适用场景
日环比	日异常检测，反应灵敏，适合实时监控和日报
周同比	日异常检测，稳定性好，消除周末效应
周环比	周异常检测
月环比	月异常检测

日异常检测场景建议同时检查日环比和周同比

3：确定阈值

针对每种对比逻辑，确定异常判定阈值：

• 已有阈值：若外部已提供阈值，按以下优先级取值，命中即停：

  优先级	来源	示例
  1	用户显式指定	用户要求"日环比阈值设为 15%"
  2	域知识包（若存在）	域知识包指定量值指标默认 10%
  3	语义层接口（若可用）	通过接口查询到的指标阈值配置

• 未提供阈值：若没有任何外部来源提供阈值，尝试从历史数据中自适应计算阈值

4：异常点判断

按以下优先级选择计算方式，命中即停：

方式一：使用脚本

路径：scripts/anomaly_detection.py

原理：根据传入的阈值参数计算对应的变化率，将变化率绝对值与阈值对比，超过阈值的数据点标记为异常。传入多个阈值时，异常点取交集。

若脚本适用于当前场景，按以下方式调用：

参数：

参数	说明
--input-file	输入数据文件路径（必填）
--date-col	日期列名（必填）
--metric-col	指标列名（必填）
--threshold-dod	日环比阈值，传入则检查日环比
--threshold-wow	周同比阈值，传入则检查周同比（日数据）
--threshold-woq	周环比阈值，传入则检查周环比（周数据）
--threshold-mom	月环比阈值，传入则检查月环比（月数据）
--output-file	异常波动点输出路径（可选）

至少传入一个阈值参数。传入多个时，异常点为各检查项的交集。

调用示例：

# 只检查日环比
python scripts/anomaly_detection.py \
  --input-file data.csv \
  --date-col "日期" \
  --metric-col "访问用户数" \
  --threshold-dod 0.10

# 同时检查日环比和周同比（异常点取交集）
python scripts/anomaly_detection.py \
  --input-file data.csv \
  --date-col "日期" \
  --metric-col "访问用户数" \
  --threshold-dod 0.10 \
  --threshold-wow 0.15

输出格式：

检查项: 日环比阈值: 10%, 周同比阈值: 15%
数据行数: 90
异常波动点数: 3

异常波动点:
       日期  访问用户数   日环比     周同比
2025-01-15     12000    +20.00%   +18.00%
2025-02-01      8500    -15.00%   -12.00%
2025-02-14     15000    +25.00%   +22.00%

方式二：自行实现

若脚本不适用于当前场景，参考上述原理自行实现异常检测。