Bi Time Impact Attribution

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%

方式二：自行实现

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentscope-ai
• Source: agentscope-ai/QwenPaw-Data
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.