bi-time-impact-attribution

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

原理：先排除事件干扰建立纯净指标基线，再将总变动拆解为结构变动、趋势和事件影响三部分：

1. 动态基线构建：先计算非事件日的“初始基线”作为裁判，评估各事件偏离度；剔除影响度超过阈值的大事件后，重算得到反映业务自然水平的最终基线
2. 基于最终基线拆解总变动：
   • 结构变动：用上周期基线衡量两个周期工作日/非工作日天数分布差异带来的变动
   • 趋势变动：用当周期天数结构衡量基线本身的升降（当周期基线 - 上周期基线），反映业务自然增长
   • 事件影响（有事件信息时）：分别计算双向影响。当周期事件计算其相对于基线的正向/负向冲击；上周期事件计算其消除效应（基数回落带来的同比影响）

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

参数：

参数	说明
--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%

方式二：自行实现

若脚本不适用于当前场景，参考上述原理自行实现时间归因计算。