| 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
方式二：自行实现
若脚本不适用于当前场景，参考上述原理自行实现贡献度计算。
