ClusterSC - 聚类合成控制法

1. 解决的问题

合成控制法（Synthetic Control, SC）通过为目标单元"合成"一个反事实来估计因果效应，是评估地区级/城市级无法做 A/B 的大型干预（如区域广告投放、城市政策）的黄金标准。

2. 核心算法逻辑

合成控制法（Synthetic Control, SC）通过为目标单元"合成"一个反事实来估计因果效应，是评估地区级/城市级无法做 A/B 的大型干预（如区域广告投放、城市政策）的黄金标准。

3. 业务应用场景

- 业务问题：母婴品牌在黑五期间，仅对美国加州投放 50 万美元 TikTok 联动广告。加州销量上涨，但无法区分黑五自然增长和广告带来的增量。若直接拿 49 个州合成"伪加州"，因各州差异悬殊极易产生噪声权重。

- 数据要求： - 面板格式：行=地理单元（县级，约 3000 个），列=月度销量（干预前≥12 个月） - 干预标记：`is_treated=1` 对加州，`is_treated=0` 对其余所有县 - 建议特征：月度销量、月度访客数、历史季节性指数

- ClusterSC 落地： 1. K-Means 对 2999 个供体县聚类（K=20），缩减至与加州行为同频的 30-80 个县 2. NNLS 在缩减供体池内拟合合成加州的反事实销量曲线 3. ATT = 干预后加州实际销量 - 合成反事实，即为 TikTok 广告纯增量

4. 输入数据要求

请查看原始代码模板获取输入规格。

5. 输出结果

请查看原始代码模板获取输出规格。

6. 业务价值 / ROI

• 识别无效区域广告后，优化 50 万元投放方向
• 假设媒介效率提升 20%，年化节省 = 50 万 × 12 个月 × 20% = 120 万元/年（保守）
• 若指导全年 500 万预算：年化节省 100-500 万元；ROI ≈ 50-250 倍（建模成本约 2 人月）
• 验证德国本地化改版 300-800% ROI 后，推进法/意复制
• 增量拓展带来年化 GMV 500-1500 万元，建模成本约 5-10 万元，ROI ≈ 50-150 倍
• 易：依赖 sklearn + scipy 标准库，无需 econml 等额外安装；代码结构清晰，2 周可上线

7. 代码模板

代码块数量：1 · 路径：未检测到

"""
ClusterSC 母婴品牌地区级广告增量归因
依赖: numpy, pandas, scipy, scikit-learn
运行: python model.py
"""
from paper2skills_code.causal_inference.synthetic_control_2025.model import (
    ClusterSC, simulate_geo_data
)

# ── 1. 准备面板数据 ────────────────────────────────────────────────────────
# df: 宽表，行=地理单元，列=时间期
# donors: donor 单元 id 列表
# treated: 目标单元 id 列表（支持多目标）
# pre_cols: 干预前时间列名
# post_cols: 干预后时间列名

df, donors, treated, pre_cols, post_cols = simulate_geo_data(
    n_donors=500,       # 模拟 500 个供体县
    n_treated=1,        # 1 个目标单元（加州）
    n_pre=12,           # 12 个干预前时间期（月）
    n_post=3,           # 3 个干预后时间期（黑五前后）
    treatment_effect=20.0,  # 模拟真实效应 20 单位销量
    seed=42,
)

# ── 2. 拟合 ClusterSC ─────────────────────────────────────────────────────
model = ClusterSC(
    n_clusters=15,  # 建议 K = sqrt(n_donors) 附近
    random_state=42,
)
model.fit(df, donors, treated, pre_cols)

# ── 3. 验证干预前拟合质量 ──────────────────────────────────────────────────
pre_fit = model.pre_treatment_fit(df, treated, pre_cols)
print(f"干预前 RMSPE: {pre_fit['rmspe'].iloc[0]:.4f}")
# RMSPE < 5 为佳；若 > 10，考虑增大 n_clusters 或增加干预前期数

# ── 4. 估计处理效应 ATT ────────────────────────────────────────────────────
att_df = model.estimate_att(df, treated, post_cols)
print(att_df[["period", "actual", "counterfactual", "att"]])
print(f"平均月度增量: {att_df['att'].mean():.2f} 件")

# ── 5. 业务解读 ───────────────────────────────────────────────────────────
avg_att = att_df["att"].mean()
unit_price = 200      # 客单价（元）
ad_spend = 500_000    # 广告投入（元）
incremental_gmv = avg_att * 3 * unit_price   # 3 个月增量 GMV
roi = incremental_gmv / ad_spend
print(f"3 个月增量 GMV: {incremental_gmv:,.0f} 元")
print(f"广告 ROI: {roi:.2f}x")

8. 论文来源

• 2503.21629