---
name: bi-attribution-analysis
description: 计算各维度（组）值对指标变动的贡献度，支持可加型量值指标和加权平均型/率值指标。当需要计算贡献度、解释指标"为什么涨/跌"时调用。
---
# bi-attribution-analysis

计算各维度（组）值对指标变动的贡献度，量化每个维度值对整体变动的贡献大小，常见场景：

- **维度下拆归因**：指标异常后，逐维度下拆定位驱动变化的关键因素
- **交叉维度归因**：多维度组合下拆，定位高贡献的维度组合

适用指标：

- **维度间可加的量值指标**：各维度值可直接求和得到整体值，如访问用户数、GMV、订单量
- **率值指标**：整体值 = 分子总和 / 分母总和，如转化率、留存率
- **加权平均型指标**：整体值由各维度值按权重加权得到。如按渠道拆解客单价（= 各渠道总收入 / 各渠道订单数，各渠道客单价不可直接求和）、按客户群拆解人均收入（= 各群总收入 / 各群用户数）

## 执行步骤

### 1：数据准备

包含维度往期/当期指标数据的 CSV 文件，至少包含以下列：

**维度间可加的量值指标**：

| 列       | 说明       | 示例        |
| -------- | ---------- | ----------- |
| 维度列   | 维度名称   | 渠道        |
| 往期值列 | 往期指标值 | 销售额_往期 |
| 当期值列 | 当期指标值 | 销售额_当期 |

**率值指标**额外需包含分子和分母的往期/当期值：

| 列        | 说明       | 示例          |
| --------- | ---------- | ------------- |
| 分子_往期 | 往期分子值 | 转化人数_往期 |
| 分子_当期 | 当期分子值 | 转化人数_当期 |
| 分母_往期 | 往期分母值 | 访问人数_往期 |
| 分母_当期 | 当期分母值 | 访问人数_当期 |

**加权平均型指标**额外需包含指标的分子（被加权的总量）和分母（权重来源）的往期/当期值，示例同上。

若上游步骤已产出可用数据文件则直接使用，否则自行取数。

### 2：选择贡献度计算方法

根据指标类型选择计算方法：

**维度间可加的量值指标**：

| 方法                                      | 适用场景                                                                                                                   |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **quantity-standard**（标准法）     | 默认选择。按维度增量占总增量的比例计算贡献度                                                                               |
| **quantity-separate**（正负分离法） | 当正负变化相互抵消严重时使用（例如，某方向变动量超过整体变动的 30%），将正贡献和负贡献分别归一化，避免抵消掩盖真实驱动因素 |

**加权平均型指标和率值指标**：

| 方法                                       | 适用场景                                                                                                                           |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **ratio-cross-term**（保留交叉项法） | 默认选择。将变动拆解为三部分：结构效应（权重变化的影响）、水平效应（指标值本身变化的影响）和交互效应（两者同时变化产生的交叉影响） |
| **ratio-average**（平均权重法）      | 当不需要区分交互效应、希望结果更简洁时使用。用往期和当期的平均权重消除交互项，只输出结构效应和水平效应两项                         |

### 3：执行贡献度计算

按以下优先级选择计算方式，命中即停：

#### 方式一：使用脚本

路径：`scripts/contribution_calc.py`

原理：按上述方法计算各维度值的贡献度。支持传入多个维度列进行交叉分析。

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

**参数**：

| 参数                  | 说明                                                       |
| --------------------- | ---------------------------------------------------------- |
| --input-file          | 输入数据文件路径（必填）                                   |
| --dimension           | 维度列名，支持多个（必填，如 `--dimension 渠道 端类型`） |
| --history-col         | 往期值列名（必填）                                         |
| --current-col         | 当期值列名（必填）                                         |
| --method              | 归因方法（必填，见上方方法选择表）                         |
| --numerator-history   | 分子往期列名（率值/加权平均指标时必填）                    |
| --numerator-current   | 分子当期列名（率值/加权平均指标时必填）                    |
| --denominator-history | 分母往期列名（率值/加权平均指标时必填）                    |
| --denominator-current | 分母当期列名（率值/加权平均指标时必填）                    |
| --output-file         | 输出结果文件路径（可选）                                   |

**调用示例**：

```bash
# 单维度 - 量值指标标准法
python scripts/contribution_calc.py \
    --input-file data.csv \
    --dimension "渠道" \
    --history-col "销售额_往期" \
    --current-col "销售额_当期" \
    --method quantity-standard \
    --output-file contribution_result.csv

# 多维度交叉 - 量值指标标准法
python scripts/contribution_calc.py \
    --input-file data.csv \
    --dimension "渠道" "端类型" \
    --history-col "销售额_往期" \
    --current-col "销售额_当期" \
    --method quantity-standard \
    --output-file contribution_result.csv

# 率值指标 - 保留交叉项法
python scripts/contribution_calc.py \
    --input-file data.csv \
    --dimension "品类" \
    --history-col "转化率_往期" \
    --current-col "转化率_当期" \
    --numerator-history "转化人数_往期" \
    --numerator-current "转化人数_当期" \
    --denominator-history "访问人数_往期" \
    --denominator-current "访问人数_当期" \
    --method ratio-cross-term \
    --output-file contribution_result.csv

# 加权平均指标 - 按渠道拆客单价
python scripts/contribution_calc.py \
    --input-file data.csv \
    --dimension "渠道" \
    --history-col "客单价_往期" \
    --current-col "客单价_当期" \
    --numerator-history "总收入_往期" \
    --numerator-current "总收入_当期" \
    --denominator-history "订单数_往期" \
    --denominator-current "订单数_当期" \
    --method ratio-cross-term \
    --output-file contribution_result.csv
```

**输出格式**：

quantity-standard（标准法）：

```
 渠道  往期值  当期值  增量   贡献度
 华东    100    150   +50    83.3%
 华南     80    100   +20    33.3%
 华北     60     50   -10   -16.7%
```

ratio-cross-term（保留交叉项法）：

```
 品类  往期率值  当期率值  权重_往期  权重_当期  结构效应  水平效应  交互效应  总贡献
  A类    5.00pt    6.00pt    60.00%    55.00%   -0.25pt   +0.55pt   -0.05pt  +0.25pt
  B类    3.00pt    4.00pt    40.00%    45.00%   +0.15pt   +0.45pt   +0.05pt  +0.65pt
```

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

若脚本不适用于当前场景，参考上述原理自行实现贡献度计算。