---
name: bi-adaptive-threshold
description: 通过量化历史数据的自然波动幅度，自适应计算判定阈值。当需要从数据本身确定阈值（如波动阈值、影响度阈值等）、而非使用固定值时调用。仅适用于日/周粒度阈值确定。
---
# bi-adaptive-threshold

基于标准差衡量数据的自然波动幅度，从数值序列中自适应计算阈值，常见场景：

- **异常检测**：确定指标波动率的异常阈值
- **影响度判定**：确定事件影响度的显著性阈值
- **其他需要从数据分布中推导合理边界的场景**

> **适用范围**：仅适用于日粒度和周粒度的阈值计算。

## 执行步骤

### 1：数据准备

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

| 列     | 说明                       | 示例       |
| ------ | -------------------------- | ---------- |
| 日期列 | 时间标识                   | 日期       |
| 数值列 | 需要计算阈值的目标数值序列 | 访问用户数 |

示例：

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

若上游步骤已产出可用数据文件则直接使用，否则自行取数。默认取近 90 天数据，若可用数据不足 90 天则取全部。

### 2：执行阈值计算

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

#### 方式一：使用脚本

路径： `scripts/adaptive_threshold.py`

原理：

1. 检查数据量是否充足（即：数据行数 < `最少数据行数`），不足则直接返回 `默认阈值`
2. 计算变化率序列，用 IQR 围栏法（四分位距 × `IQR 倍数`）剔除极端异常值
3. 通过 ruptures 库检测结构性变化点，将数据划分为若干分段
4. 取最后一段平稳区间：
   * 若最后一段不足 `最少数据行数`，说明稳定数据不够，可能处于业务初期，返回 `默认阈值`；
   * 计算该段数据标准差，若标准差 ≥ `阈值上限`，说明当前仍处于剧烈波动期，返回 `默认阈值`
5. 最终阈值 = 标准差 × `标准差倍数`，并限制在 [`阈值下限`, `阈值上限`] 范围内，避免阈值过于敏感或过于迟钝

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

**参数**：

| 参数                | 说明                                              | 默认值              |
| ------------------- | ------------------------------------------------- | ------------------- |
| --input-file        | 输入数据文件路径                                  | （必填）            |
| --date-col          | 日期列名                                          | （必填）            |
| --metric-col        | 数值列名                                          | （必填）            |
| --default-threshold | 默认阈值，按指标类型区分，详见下方说明            | （必填）            |
| --min-periods       | 最少数据行数                                      | 30                  |
| --iqr-multiplier    | IQR 倍数                                          | 1.5                 |
| --std-multiplier    | 标准差倍数                                        | 3.0                 |
| --threshold-min     | 阈值下限                                          | 0.05                |
| --threshold-max     | 阈值上限                                          | 0.20                |
| --ruptures-method   | ruptures 库的变化点检测算法（pelt/binseg/window） | pelt                |
| --ruptures-penalty  | ruptures 库的变化点检测的惩罚系数，值越大分段越少 | None (自动计算)     |

> `--default-threshold` 是数据不足或波动剧烈时的兜底值，调用时应根据指标类型传入不同的值：
>
> - **量值指标**：默认 10%（即 `--default-threshold 0.10`）
> - **率值指标**：根据率值所在区间差异化设置：
>   - 率值在 [40%, 60%]：±5%（即 `--default-threshold 0.05`）
>   - 率值在 [20%, 40%) 或 (60%, 80%]：±3%（即 `--default-threshold 0.03`）
>   - 率值在 [0%, 20%) 或 (80%, 100%]：±2%（即 `--default-threshold 0.02`）

**调用示例**：

```bash
python scripts/adaptive_threshold.py \
  --input-file data.csv \
  --date-col "日期" \
  --metric-col "访问用户数"
```

**输出格式**：

```
# 正常
threshold: 0.14

# 数据不足
threshold: 0.10 (数据不足，使用默认阈值)

# 波动剧烈
threshold: 0.10 (波动剧烈，使用默认阈值)
```

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

若脚本不适用于当前场景（如数据结构不匹配、场景特殊、用户有自定义需求等），基于上述核心思想自行实现阈值计算。