Bi Attribution Analysis

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 | 输出结果文件路径（可选） |

调用示例：

# 单维度 - 量值指标标准法
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

方式二：自行实现

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

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.