---
name: bi-time-impact-attribution
description: 将累加型量值指标的周期波动拆解为结构变动、趋势变动和事件影响。当需要量化时间因素对指标变动的影响时调用。
---
# bi-time-impact-attribution

将指标周期波动拆解为结构变动、趋势变动和事件影响，量化各时间因素对指标变化的贡献。典型场景：拆解本周期 vs 上周期的指标变动来源，量化节假日、营销活动、产品发布等事件对指标的影响度。

适用范围：

- **仅适用于累加型量值指标**：各时间点的值可直接求和得到周期总量，如 DAU、访问量、GMV、订单量。率值指标（留存率、转化率等）不适用
- **时间粒度**：通常适用于周度或月度对比

## 执行步骤

### 1：数据准备

需要两份数据：

**指标数据**：包含**本周期和上周期日粒度**数据的 CSV 文件，至少包含以下两列：

| 列     | 说明     | 示例       |
| ------ | -------- | ---------- |
| 日期列 | 时间标识 | 日期       |
| 指标列 | 指标值   | 访问用户数 |

示例：

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

**事件信息**（可选）：本周期和上周期内发生的事件列表（CSV），包含事件名称和起止日期。不提供则只拆解结构变动和趋势变动，不计算事件影响：

| 列       | 说明     | 示例       |
| -------- | -------- | ---------- |
| 事件名称 | 事件描述 | 春节       |
| 开始日期 | 事件起始 | 2025-01-28 |
| 结束日期 | 事件结束 | 2025-02-04 |

示例：

```csv
事件名称,开始日期,结束日期
春节,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       | 波动拆解结果输出路径（可选）                     |

**调用示例**：

```bash
# 有事件信息
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%
```

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

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