bi-adaptive-threshold

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

bi-adaptive-threshold

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

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

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

执行步骤

1：数据准备

包含时间序列数据的 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）

调用示例：

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

输出格式：

# 正常
threshold: 0.14

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

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

方式二：自行实现

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