| name | bi-time-impact-attribution |
| description | 将累加型量值指标的周期波动拆解为结构变动、趋势变动和事件影响。当需要量化时间因素对指标变动的影响时调用。 |
bi-time-impact-attribution
将指标周期波动拆解为结构变动、趋势变动和事件影响，量化各时间因素对指标变化的贡献。典型场景：拆解本周期 vs 上周期的指标变动来源，量化节假日、营销活动、产品发布等事件对指标的影响度。
适用范围：
- 仅适用于累加型量值指标：各时间点的值可直接求和得到周期总量，如 DAU、访问量、GMV、订单量。率值指标（留存率、转化率等）不适用
- 时间粒度：通常适用于周度或月度对比
执行步骤
1：数据准备
需要两份数据：
指标数据：包含本周期和上周期日粒度数据的 CSV 文件，至少包含以下两列：
| 列 | 说明 | 示例 |
|---|
| 日期列 | 时间标识 | 日期 |
| 指标列 | 指标值 | 访问用户数 |
示例：
日期,访问用户数
2025-01-01,10000
2025-01-02,10500
...
事件信息（可选）：本周期和上周期内发生的事件列表（CSV），包含事件名称和起止日期。不提供则只拆解结构变动和趋势变动，不计算事件影响：
| 列 | 说明 | 示例 |
|---|
| 事件名称 | 事件描述 | 春节 |
| 开始日期 | 事件起始 | 2025-01-28 |
| 结束日期 | 事件结束 | 2025-02-04 |
示例：
事件名称,开始日期,结束日期
春节,2025-01-28,2025-02-04
元旦,2025-01-01,2025-01-01
若上游步骤已产出可用数据文件则直接使用，否则自行取数并按上述格式组织。若未提供事件信息，跳过步骤 2 和 3，直接进入步骤 4。
2：确定事件影响时间区间
每个事件需确定其影响的时间区间：
- 已指定：若外部已提供事件影响区间，按以下优先级取值，命中即停：
| 优先级 | 来源 | 示例 |
|---|
| 1 | 用户显式指定 | 用户要求"春节影响区间为 1.25-2.05" |
| 2 | 域知识包（若存在） | 域知识包指定各事件的影响区间 |
| 3 | 语义层接口（若可用） | 通过接口查询到的事件影响区间配置 |
- 未指定：若没有外部来源提供，按以下默认规则推断：
| 事件类型 | 时间区间范围 | 默认值 |
|---|
| 节假日 | 假期开始前 N 天 ~ 假期结束 | N=1 |
| 事件波动 | 事件开始当天 ~ 事件开始后 M 天 | M=2 |
3：确定事件影响度阈值
事件影响度阈值用于计算指标基线：影响度超过阈值的事件视为"大事件"，其事件日将被剔除后计算基线，以获得更准确的非事件日基线水平。低于阈值的"小事件"不剔除。
- 已有阈值：若外部已提供阈值，按以下优先级取值，命中即停：
| 优先级 | 来源 | 示例 |
|---|
| 1 | 用户显式指定 | 用户要求"影响度阈值设为 5%" |
| 2 | 域知识包（若存在） | 域知识包指定事件影响度阈值为 10% |
| 3 | 语义层接口（若可用） | 通过接口查询到的阈值配置 |
- 未提供阈值：若没有任何外部来源提供阈值，尝试从历史事件影响度数据中自适应计算阈值
4：执行时间归因
按以下优先级选择计算方式，命中即停：
方式一：使用脚本
路径：scripts/time_impact_attribution.py
原理：先排除事件干扰建立纯净指标基线，再将总变动拆解为结构变动、趋势和事件影响三部分：
- 动态基线构建：先计算非事件日的“初始基线”作为裁判，评估各事件偏离度；剔除影响度超过阈值的大事件后，重算得到反映业务自然水平的最终基线
- 基于最终基线拆解总变动：
- 结构变动：用上周期基线衡量两个周期工作日/非工作日天数分布差异带来的变动
- 趋势变动：用当周期天数结构衡量基线本身的升降（当周期基线 - 上周期基线），反映业务自然增长
- 事件影响（有事件信息时）：分别计算双向影响。当周期事件计算其相对于基线的正向/负向冲击；上周期事件计算其消除效应（基数回落带来的同比影响）
若脚本适用于当前场景，按以下方式调用：
参数：
| 参数 | 说明 |
|---|
| --input-file | 日粒度指标数据文件路径（必填） |
| --date-col | 日期列名（必填） |
| --metric-col | 指标列名（必填） |
| --events-file | 事件信息文件路径（可选，不提供则不计算事件影响） |
| --current-month | 当前周期，格式 YYYY-MM 或 YYYY-WXX（必填） |
| --prev-month | 上周期，格式同上（必填） |
| --impact-threshold | 事件影响度阈值，超过则剔除该事件日重算基线 |
| --holiday-lead-days | 节假日前置天数 |
| --event-lag-days | 事件后置天数 |
| --output-file | 波动拆解结果输出路径（可选） |
调用示例：
python scripts/time_impact_attribution.py \
--input-file data.csv \
--date-col "日期" \
--metric-col "访问用户数" \
--events-file events.csv \
--current-month 2025-02 \
--prev-month 2025-01
python scripts/time_impact_attribution.py \
--input-file data.csv \
--date-col "日期" \
--metric-col "访问用户数" \
--current-month 2025-02 \
--prev-month 2025-01
输出格式：
同时输出绝对影响值与相对占比（占比 = 单项影响 / 总变动量）：
有事件时：
影响因素 绝对值 占比
总变动 +15000 100.0%
结构变动 +3000 20.0%
趋势变动 +8000 53.3%
事件影响 +4000 26.7%
春节 +5000 33.3%
元旦 -1000 -6.7%
无事件时：
影响因素 绝对值 占比
总变动 +11000 100.0%
结构变动 +3000 27.3%
趋势变动 +8000 72.7%
方式二：自行实现
若脚本不适用于当前场景，参考上述原理自行实现时间归因计算。
