Metric Attribution

┌───────────────────────────────────────────────────────────────┐
│                     归因诊断全流程                              │
│                                                               │
│  Step 1  确认波动事实 → 变了多少？跟什么比？                     │
│     ↓                                                         │
│  Step 2  因子拆解 → 哪个业务环节出了问题？（定性）               │
│     ↓                                                         │
│  Step 3  维度归因 → 问题环节在哪些维度上集中？（定位）            │
│     ↓         ↘ 发现集中点 → 继续下钻到更细维度                  │
│  Step 4  外部事件关联 → 天气？节假日？竞对？行业政策？（找因）     │
│     ↓                                                         │
│  Step 5  综合诊断结论 → 汇总所有发现，输出归因报告                │
│                                                               │
│  * 并非每次都需走完全部步骤，根据复杂度灵活调整                    │
│  * 每步的发现逐步积累，最终在 Step 5 统一收口                    │
└───────────────────────────────────────────────────────────────┘

curl -X POST "https://gateway.can.aloudata.com/api/metrics/query" \
  -H "X-API-Key: $CAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{JSON请求体}
EOF

# 搜索指标
curl -H "X-API-Key: $CAN_API_KEY" "https://gateway.can.aloudata.com/api/metrics/search?pageSize=5" --data-urlencode "keyword=销售额" -G

# 查整体环比变化
curl -X POST "https://gateway.can.aloudata.com/api/metrics/query" \
  -H "X-API-Key: $CAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
    "metrics": ["retail_amt", "retail_amt__sameperiod__mom__value", "retail_amt__sameperiod__mom__growthvalue", "retail_amt__sameperiod__mom__growth"],
    "timeConstraint": "DateTrunc(['metric_time'], \"MONTH\") = DATEADD(DateTrunc(NOW(), \"MONTH\"), -1, \"MONTH\")"
}
EOF

{
    "metrics": ["retail_amt"],
    "dimensions": ["metric_time__month"],
    "timeConstraint": "DateTrunc(['metric_time'], \"MONTH\") >= DATEADD(DateTrunc(NOW(), \"MONTH\"), -6, \"MONTH\") AND DateTrunc(['metric_time'], \"MONTH\") < DateTrunc(NOW(), \"MONTH\")",
    "orders": [{"metric_time__month": "asc"}]
}

# 搜索相关因子指标
curl -H "X-API-Key: $CAN_API_KEY" "https://gateway.can.aloudata.com/api/metrics/search?pageSize=10" --data-urlencode "keyword=UV,转化率,客单价,购买人数" -G

{
    "metrics": ["visitor_cnt", "buyer_cnt", "AOV",
                "visitor_cnt__sameperiod__mom__value",
                "buyer_cnt__sameperiod__mom__value",
                "AOV__sameperiod__mom__value"],
    "timeConstraint": "DateTrunc(['metric_time'], \"MONTH\") = DATEADD(DateTrunc(NOW(), \"MONTH\"), -1, \"MONTH\")"
}

"metricDefinitions": {
    "cvr": { "expr": "[buyer_cnt]/[visitor_cnt]" }
}

ΔY% ≈ ΔA% + ΔB% + ΔC% + 交叉项
A 对 Y 的贡献 ≈ ΔA% / ΔY%

import itertools, math

def shapley_decomposition(factors_base, factors_current):
    """
    factors_base: dict, 如 {"UV": 10000, "CVR": 0.05, "AOV": 200}
    factors_current: dict, 如 {"UV": 12000, "CVR": 0.045, "AOV": 210}
    返回各因子对总变化量的 Shapley 贡献
    """
    factor_names = list(factors_base.keys())
    n = len(factor_names)

    contributions = {}
    for name in factor_names:
        shapley_val = 0
        others = [fn for fn in factor_names if fn != name]
        for subset_size in range(n):
            for subset in itertools.combinations(others, subset_size):
                subset_set = set(subset)
                val_with, val_without = 1, 1
                for fn in factor_names:
                    if fn == name:
                        val_with *= factors_current[fn]
                        val_without *= factors_base[fn]
                    elif fn in subset_set:
                        val_with *= factors_current[fn]
                        val_without *= factors_current[fn]
                    else:
                        val_with *= factors_base[fn]
                        val_without *= factors_base[fn]
                weight = math.factorial(subset_size) * math.factorial(n - subset_size - 1) / math.factorial(n)
                shapley_val += weight * (val_with - val_without)
        contributions[name] = shapley_val
    return contributions

import matplotlib.pyplot as plt
import matplotlib
matplotlib.rcParams['font.sans-serif'] = ['SimHei', 'DejaVu Sans']
matplotlib.rcParams['axes.unicode_minus'] = False

def waterfall_chart(factors, contributions, base_value, current_value, title, save_path):
    """
    factors: list, 因子名称列表，如 ["UV", "转化率", "客单价", "交叉项"]
    contributions: list, 各因子的贡献量（绝对值变化量，非百分比），如 [+20000, -15000, +5000, -500]
    base_value: float, 基准期总值
    current_value: float, 当期总值
    title: str, 图表标题
    save_path: str, 保存路径
    """
    labels = ["基准值"] + factors + ["当期值"]
    values = [base_value] + contributions + [current_value]

    # 计算瀑布图的底部位置和柱子高度
    bottoms = [0]
    heights = [base_value]
    running = base_value
    for c in contributions:
        if c >= 0:
            bottoms.append(running)
            heights.append(c)
        else:
            bottoms.append(running + c)
            heights.append(abs(c))
        running += c
    bottoms.append(0)
    heights.append(current_value)

    colors = ["#4472C4"]  # 基准值：蓝色
    for c in contributions:
        colors.append("#2E7D32" if c >= 0 else "#C62828")  # 正向绿，负向红
    colors.append("#4472C4")  # 当期值：蓝色

    fig, ax = plt.subplots(figsize=(10, 6))
    bars = ax.bar(labels, heights, bottom=bottoms, color=colors, width=0.6, edgecolor='white')

    # 在柱子上标注数值
    for i, (bar, val) in enumerate(zip(bars, values)):
        if i == 0 or i == len(values) - 1:
            text = f"{val:,.0f}"
            y_pos = bar.get_y() + bar.get_height() + base_value * 0.01
        else:
            text = f"{'+' if val >= 0 else ''}{val:,.0f}"
            y_pos = bar.get_y() + bar.get_height() + base_value * 0.01
        ax.text(bar.get_x() + bar.get_width()/2, y_pos, text,
                ha='center', va='bottom', fontsize=10, fontweight='bold')

    # 添加连接线
    for i in range(len(bars) - 1):
        x1 = bars[i].get_x() + bars[i].get_width()
        x2 = bars[i+1].get_x()
        y = bars[i].get_y() + bars[i].get_height() if i == 0 else bottoms[i] + heights[i]
        ax.plot([x1, x2], [y, y], color='gray', linewidth=0.8, linestyle='--')

    ax.set_title(title, fontsize=14, fontweight='bold', pad=15)
    ax.set_ylabel("指标值")
    ax.spines['top'].set_visible(False)
    ax.spines['right'].set_visible(False)
    plt.tight_layout()
    plt.savefig(save_path, dpi=150, bbox_inches='tight')
    plt.close()

curl -H "X-API-Key: $CAN_API_KEY" "https://gateway.can.aloudata.com/api/metrics/{metricName}/dimensions"

{
    "metrics": ["{指标}", "{指标}__sameperiod__mom__value", "{指标}__sameperiod__mom__growthvalue"],
    "dimensions": ["{维度名}"],
    "timeConstraint": "DateTrunc(['metric_time'], \"MONTH\") = DATEADD(DateTrunc(NOW(), \"MONTH\"), -1, \"MONTH\")",
    "orders": [{"{指标}__sameperiod__mom__growthvalue": "asc"}]
}

维度值变化量 = 当期值 - 基准值
总变化量 = Σ 所有维度值的变化量（应等于 Step 1 的总体变化量，作为校验）
贡献度 = 维度值变化量 / |总变化量| × 100%

一级渠道 → 二级渠道 → 地区 → 城市
品类大类 → 品类中类 → 品牌

{
    "metrics": ["{指标}", "{指标}__sameperiod__mom__value", "{指标}__sameperiod__mom__growthvalue"],
    "dimensions": ["{下一层维度}"],
    "filters": ["[{上层维度}]= \"{贡献最大的值}\""],
    "timeConstraint": "..."
}