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

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

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

## 执行步骤

### 1：数据准备

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

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

示例：

```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   | 异常波动点输出路径（可选）             |

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

**调用示例**：

```bash
# 只检查日环比
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%
```

#### 方式二：自行实现

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