paper-reproduce

name

paper-reproduce

description

Systematic methodology for reproducing published academic papers using provided data. Use when the user asks to reproduce, replicate, or verify results from a published paper, including sample selection, descriptive statistics, regression analyses, and generating reproduction reports (Markdown + LaTeX PDF). Covers the full pipeline: data exploration, variable identification/mapping, sample filtering, variable construction, statistical analysis, result comparison, and documentation. Applicable to any observational study, clinical cohort, or survey-based research paper.

Paper Reproduce — 论文复现方法论

核心原则

1. 先探索后建模 — 永远不要假设变量名和编码，必须从数据中验证
2. 逐步筛选逐步核对 — 每一步样本量都要和论文对比
3. 容忍偏差但记录偏差 — harmonized 数据集和原始数据必然有差异，关键是记录和解释
4. 边干边说 — 每完成一步立即输出中间结果，不要等全部跑完才汇报

复现流程（6 阶段）

Phase 1: 任务理解 + 数据探索

输入: 论文 PDF/任务文档 + 数据文件
输出: 变量映射表 (variable_mapping.json)

1. 精读任务文档，提取：

   • 样本筛选流程（每步的 n 和排除条件）
   • 因变量、自变量、协变量的定义和编码
   • 统计方法（回归类型、标准误类型、标准化方式）
   • 期望的表格数值（用于验证）

2. 探索数据结构：

   df = pd.read_stata('data.dta')  # 或 read_csv/read_sas
   print(f"维度: {df.shape}")
   print(f"变量: {df.columns.tolist()}")
   # 按前缀分组查看变量
   # 检查是否有 wave/time/year 标识
   

3. 变量识别四步法（最关键的步骤）：

   • 精确匹配: 搜索论文提到的变量名（如 dc009s1）
   • 语义搜索: 搜索关键词（如 mem, recall, orient）
   • 范围验证: 检查候选变量的值域是否匹配论文描述（如 0-10）
   • 交叉验证: 用已知关系验证（如 total = sub1 + sub2 + sub3）

经验教训: harmonized 数据集的变量名与原始问卷变量名通常完全不同。 不要假设 dc009s1 存在，要搜索语义等价的变量。

Phase 2: 变量构建 + 验证

输入: variable_mapping.json
输出: 构建好变量的 DataFrame

1. 逐个构建变量，每个变量构建后立即验证：

   • 值域是否在期望范围内
   • 缺失率是否合理
   • 均值/比例是否接近论文报告值

2. 组合变量的验证技巧：

   # 验证 total = sub1 + sub2 + ... + subN
   calc = df['sub1'] + df['sub2'] + df['sub3']
   diff = (df['total'] - calc).abs()
   match_rate = (diff < 0.01).mean()
   print(f"吻合率: {match_rate:.1%}")
   

3. 分类变量编码注意事项：

   • Stata/SPSS 导入的 category 变量通常是中文标签
   • 用 value_counts() 检查所有可能值
   • 论文说的"未婚"可能包含离异、丧偶、分居等多种状态
   • 论文说的"低于初中"教育，在 harmonized 数据中可能对应不同的分类变量

经验教训: 当变量均值与论文偏差大时（如 MS 均值 7.11 vs 论文 5.73）， 优先怀疑变量构成定义有误，而非数据问题。尝试不同的子变量组合。

Phase 3: 样本筛选

输入: 构建好变量的 DataFrame
输出: 分析用的最终样本

1. 严格按论文的顺序逐步排除
2. 每一步都输出并对比：

   Step N: 描述 → 保留 XXXX [论文: YYYY, 差 ZZZ]
   

3. 如果某步偏差大（>10%），停下来排查：
   • 检查变量缺失率：哪个变量贡献了最多缺失？
   • 如果是认知/生理测量变量缺失率高，考虑放宽定义
   • 对比论文的排除人数确定偏差来源

经验教训: 要求多个变量同时不缺失会导致排除量远超预期。 如果论文未说明如何处理缺失，尝试：(a) 只要求核心变量不缺失， (b) 分步排除而非一次性 dropna(subset=all_vars)。

Phase 4: 统计分析

输入: 最终样本
输出: Table 1, Table 2, Table 3 等

描述统计 (Table 1)

# 连续变量: M(SD) + t 检验
t_stat, p_val = stats.ttest_ind(group1[var], group2[var])

# 分类变量: % + 卡方检验
ct = pd.crosstab(grouping_var, category_var)
chi2, p_val, dof, expected = stats.chi2_contingency(ct)

回归分析 (Table 2/3)

# 标准化所有变量（因变量和自变量都标准化 → 得到标准化 beta）
from sklearn.preprocessing import StandardScaler
df_std = df[all_vars].copy()
for col in df_std.columns:
    df_std[col] = (df_std[col] - df_std[col].mean()) / df_std[col].std()

# OLS + 稳健标准误 (HC3)
model = smf.ols('y ~ x1 + x2 + ...', data=df_std).fit(cov_type='HC3')

交互项处理

# 标准化后再构建交互项
df_std['interaction'] = df_std['var1'] * df_std['var2']

分层分析

# 对每个子群体分别标准化后回归（不要用全样本的标准化参数）
for subset_name, subset in subsets.items():
    sub_std = subset[vars].copy()
    for col in sub_std.columns:
        sub_std[col] = (sub_std[col] - sub_std[col].mean()) / sub_std[col].std()
    model = smf.ols(formula, data=sub_std).fit(cov_type='HC3')

经验教训:

• 标准化beta要求因变量和自变量都标准化
• HC3 是最常用的稳健标准误，但不同软件默认不同（SPSS 用 HC0）
• 分层分析时去掉分层变量（如按性别分层时不控制性别）
• 分层分析对每个子群体独立标准化

Phase 5: 结果对比 + 偏差分析

逐项核对论文报告值，使用三级标记：

标记	含义	标准
✅	验证	数值接近（允许末位四舍五入差异），显著性一致
⚠️	趋势一致	方向相同，但显著性不同（通常因样本量差异）
❌	未复现	方向相反或差距太大

对每个 ❌ 和 ⚠️ 给出可能原因。

Phase 6: 输出文档

同时生成两种格式：

1. Markdown 文档: 完整的复现报告，包含方法、结果、对比表、偏差讨论
2. LaTeX → PDF: 专业排版的 PDF 报告

LaTeX 编译注意事项：

• 中文用 ctex 包 + xelatex 编译
• 流程图用 tikz
• 表格用 booktabs（三线表）
• \checkmark 需要 amssymb 包

xelatex -interaction=nonstopmode report.tex  # 第一遍
xelatex -interaction=nonstopmode report.tex  # 第二遍（交叉引用）

输出目录结构

reproduce_<study>/
├── scripts/
│   └── full_analysis.py      # 主分析脚本（可独立运行）
├── figure1.json               # 筛选流程数据
├── table1.csv                 # 描述统计
├── table2.csv                 # 回归结果
├── table3.csv                 # 分层/补充分析
├── analysis_output.txt        # 完整控制台输出
├── 复现报告.md                # Markdown 报告
├── 复现报告.tex               # LaTeX 源文件
├── 复现报告.pdf               # PDF 报告
└── data files...              # 原始数据（不修改）

常见陷阱

陷阱	表现	解决
harmonized vs 原始数据	变量名不同、缺失模式不同、编码不同	基于语义+范围搜索变量，不要硬编码变量名
组合变量定义错误	均值偏差大（>1SD）	用 total = sum(parts) 验证；尝试不同的子变量组合
缺失值级联	多变量同时要求非缺失 → 排除量远超论文	分步排除；先排核心变量缺失，再排协变量缺失
分类变量编码	中文标签多义（"未婚"的范围）	value_counts() 全部列出，逐一确认
标准化方式	β系数方向对但数值偏大/偏小	确认是全变量标准化还是只标准化连续变量
稳健标准误类型	p 值略有差异	HC0/HC1/HC3 选择；SPSS 默认 HC0
Docker 文件同步	脚本修改后容器内仍是旧版	每次修改后 docker cp 同步

参考

详细的调查数据库特定操作，参见对应的数据库 skill（如 charls-reproduce）。