data-analysis

数据分析工作流

使用 R 执行端到端数据分析：加载、探索、分析并生成可直接用于发表的输出。

输入： $ARGUMENTS — 数据集路径（例如 data/county_panel.csv）或分析目标的描述（例如“使用 CPS 数据，通过州固定效应回归工资与教育程度的关系”）。

---

约束

• 遵循 R 代码规范，参见 .claude/rules/r-code-conventions.md
• 将所有脚本保存到 scripts/R/，并使用描述性文件名
• 将所有输出（图表、表格、RDS）保存到 output/
• 对每个计算出的对象使用 saveRDS()——Quarto 幻灯片可能需要这些对象
• 所有图表均使用项目主题（检查 .claude/rules/ 中是否有自定义主题）
• 在展示结果前，对生成的脚本运行 r-reviewer

---

工作流阶段

阶段 0：预检报告

在编写任何分析代码前，先生成预检报告，说明你已读取输入内容。这可以避免 Agent 臆造变量名或跳过项目规范这一常见问题。

在阶段 1 之前，在回复用户时输出以下内容块：

## Pre-Flight Report

**Dataset:** [path]
- Variables found: [list from head()/names()]
- Rows: [count]
- Key types: [e.g., "outcome=numeric, treatment=binary, state=factor"]
- Missing-data summary: [% missing per key var]

**Project conventions read:**
- `.claude/rules/r-code-conventions.md` — [one-line summary of most relevant rule]
- `.claude/rules/content-invariants.md` — [INV-9, INV-10, INV-11, INV-12 applicable]

**Task interpretation:** [one sentence restating what the user asked for]

**Plan:** [3-5 bullet outline of the R script structure]

如果任何输入无法读取（文件缺失或格式无法读取），请停止并先询问用户。

阶段 1：设置与数据加载

1. 创建 R 脚本，并添加规范的文件头（标题、作者、用途、输入、输出）
2. 在顶部加载所需软件包（使用 library()，绝不使用 require()）
3. 按 YYYYMMDD 格式在顶部设置一次随机种子（遵循 r-code-conventions.md），例如 set.seed(20260415)（INV-9）
4. 加载并检查数据集

阶段 2：探索性数据分析

生成诊断输出：

• 汇总统计： summary()、缺失率、变量类型
• 分布： 为关键连续变量绘制直方图
• 关系： 散点图、相关矩阵
• 时间模式： 如果是面板数据，绘制随时间变化的趋势
• 组间比较： 如果有处理组/对照组，比较处理前的均值

将所有诊断图表保存到 output/diagnostics/。

阶段 3：主要分析

根据研究问题：

• 回归分析： 面板数据使用 fixest，横截面数据使用 lm/glm
• 标准误： 在适当层级进行聚类，并说明原因
• 多个设定： 从简单模型开始，逐步加入控制变量
• 效应大小： 除原始系数外，同时报告标准化效应

设定台账——每次运行均记录，无论是否保留

本阶段估计的每个设定，包括被舍弃和运行失败的设定，都要在运行时向 quality_reports/spec-ledger.md 追加一行。这是对审稿人“你还尝试了什么？”这一问题的记录：它让搜索过程保持可见，而不是阻止搜索；同时记录各个设定，但不会建议运行哪些设定。

• 仅追加。 绝不编辑或删除任何行；如需更正，应新增一行。修改已提交行的提交会导致仓库卫生检查失败。
• 状态为 kept、dropped 或 failed；对于未保留的设定，原因列说明原因。
• 估计值为可选项。对于受限数据，在数值通过披露审查前留空（参见 confidential-data.md）。
• 公式中的 | 应转义为 \|，否则表格会损坏。包含反引号的设定（例如 Stata 局部宏 `x'）应使用双反引号包裹：`` reg y `controls' ``。

LEDGER=quality_reports/spec-ledger.md
[ -f "$LEDGER" ] || printf '%s\n' "# Specification ledger" "" \
  "Every specification estimated, kept or not, one row each, appended as it is run. Never edit a past row; a correction is a new row." "" \
  "| Date | Commit | Script:line | Outcome | Specification | Sample | Status | Why | Estimate |" \
  "|---|---|---|---|---|---|---|---|---|" > "$LEDGER"
if REV=$(git rev-parse --short HEAD 2>/dev/null); then       # -dirty = anything uncommitted outside quality_reports/, untracked files included
  [ -n "$(git status --porcelain -- . ':(exclude)quality_reports' 2>/dev/null)" ] && REV="$REV-dirty"
else
  REV="no-commit"
fi
printf '| %s | %s ' "$(date +%F)" "$REV" >> "$LEDGER"          # one printf + one heredoc per specification
cat >> "$LEDGER" <<'EOF'
| scripts/R/03_analyze.R:42 | log_wage | `feols(log_wage ~ treat + age \| id + year, cluster = ~id)` | panel 2010-2019 | kept | main specification | 0.082 (0.021) |
EOF

阶段 4：可直接用于发表的输出

表格：

• 使用 modelsummary（优先）或 stargazer 生成回归表
• 包含所有标准元素：系数、标准误、显著性星号、N、R 平方
• 导出为 .tex 以便插入 LaTeX，并导出为 .html 以便快速查看

图表：

• 使用带有项目主题的 ggplot2
• 设置 bg = "transparent"，以兼容 Beamer
• 设置规范的坐标轴标签（句首字母大写格式，并注明单位）
• 使用明确的尺寸导出：ggsave(width = X, height = Y)
• 同时保存为 .pdf 和 .png

阶段 5：保存与审查

1. 使用 saveRDS() 保存所有关键对象（回归结果、汇总表、处理后的数据）
2. 根据需要使用 dir.create(..., recursive = TRUE) 创建 output/ 子目录
3. 对生成的脚本运行 r-reviewer Agent：

Delegate to the r-reviewer agent:
"Review the script at scripts/R/[script_name].R"

4. 解决审查中发现的任何严重或高优先级问题。

---

脚本结构

遵循此模板：

# ============================================================
# [Descriptive Title]
# Author: [from project context]
# Purpose: [What this script does]
# Inputs: [Data files]
# Outputs: [Figures, tables, RDS files]
# ============================================================

# 0. Setup ----
library(tidyverse)
library(fixest)
library(modelsummary)

set.seed(20260415)  # YYYYMMDD per r-code-conventions.md (INV-9)

dir.create("output/analysis", recursive = TRUE, showWarnings = FALSE)

# 1. Data Loading ----
# [Load and clean data]

# 2. Exploratory Analysis ----
# [Summary stats, diagnostic plots]

# 3. Main Analysis ----
# [Regressions, estimation]

# 4. Tables and Figures ----
# [Publication-ready output]

# 5. Export ----
# [saveRDS for all objects, ggsave for all figures]

---

重要事项

• 如实复现，不要猜测。 如果用户指定了回归分析，就严格按要求执行。
• 展示分析过程。 在进行回归分析前，先打印汇总统计量。
• 检查问题。 留意多重共线性、离群值和完全预测。
• 使用相对路径。 所有路径都相对于仓库根目录。
• 不要硬编码数值。 使用变量来设置样本限制、日期范围等。

长时间运行的拟合：使用 Monitor 工具（2026 年 4 月）

对于耗时超过几分钟的回归、模拟或自助法循环，使用 Bash 并设置 run_in_background: true 来启动，然后使用 Anthropic 的 Monitor 工具，将 R 的标准输出实时传输到对话中。操作模式如下：

1. 使用 Bash 在后台启动，并将所有输出发送到日志：mkdir -p output && Rscript scripts/R/03_analyze.R > output/03_analyze.log 2>&1。进程退出时，后台作业会自动通知你。
2. 启动 Monitor，使用命令持续读取日志并筛选关键节点和失败信息，例如：tail -f output/03_analyze.log | grep --line-buffered -E "Coefficients table written|Error|Execution halted"。Monitor 没有作业 ID 参数：它自身 command 的标准输出就是事件流。tail -f 不会退出，因此请将 timeout_ms 设置为超过预期运行时长，或设置 persistent: true，并在作业完成后使用 TaskStop 停止 Monitor。
3. 根据实时输出继续操作或调整方案。

这可以避免轮询循环反模式（sleep 30; check; sleep 30; check），也能避免在空闲等待期间消耗缓存。尤其适合与指南中的注重成本的并行处理章节搭配使用。