bi-attribution-analysis

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

调用示例：

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

方式二：自行实现

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