r-analysis：R 分析规程

目的

R 在统计与生物医学领域不可替代，但 R 工作流有两个经典的复现陷阱：包版本全局漂移（半年前能跑的脚本今天报错）和 RStudio 交互式执行（结果依赖"先点了哪个单元格"）。本技能把每一次 R 分析约束为可复现的最小闭环：

1. 环境可重建：renv 锁文件固定全部包版本；
2. 执行可重放：脚本化非交互，Rscript 一条命令从头跑到尾；
3. 环境可审计：sessionInfo() 输出必进 provenance 记录；
4. 产物可定位：报告走 rmarkdown/quarto 渲染，统一落盘 output 契约。

本技能与 python-analysis 平行：同一套目录契约、同一套 provenance 集成，差异只在 R 生态的工具链。不涉及远程执行（远程见 remote-compute / hpc-slurm）。

前置检查

1. 确认当前目录是工作区根目录（结构约定见 research-workspace）；本技能的产物 skill 名为 r-analysis。
2. 确认原始数据已在 data/ 下且只读；R 里读数据一律用相对路径（here::here("data", ...) 或直接相对路径），不写绝对路径。
3. 检查项目根是否已有 renv.lock：有则用现有环境，不要另起炉灶；没有则按第 1 节初始化。
4. RStudio 用户注意：本技能要求的交付形态是"命令行可重放"，RStudio 里逐行运行可以用于探索，但进入产物的分析必须落成脚本。

1 · 环境：renv 锁定

首次建立环境：

install.packages("renv")   # 仅此一个包装进全局库
renv::init()               # 生成 renv.lock、renv/ 与 .Rprofile

日常纪律：

1. 新装包用 renv::install("包名")，装完立即 renv::snapshot() 更新 renv.lock；
2. 换机器或重建环境时 renv::restore()，严格按锁文件还原，不"顺手升级"；
3. renv.lock 是产物的一部分，纳入版本管理与证据胶囊；renv/ 目录本身不进版本控制（renv 默认 .gitignore 已处理）；
4. 升级包是有意决策：renv::update() 后重跑全部分析并登记新 provenance，不在论文冻结（evidence-capsule）之后升级。

2 · 随机种子与脚本化执行

1. 脚本开头固定种子：set.seed(42)；涉及并行或特定 RNG 时显式指定 RNGkind 并写进注释与 provenance note。
2. 交付形态是非交互脚本：Rscript scripts/analyze-xxx.R 一条命令跑完，无 readline()、无依赖编辑器状态。
3. 脚本放 scripts/，kebab-case 命名；参数集中在脚本顶部常量或 commandArgs 解析。
4. 种子值、R 版本、关键包版本写进 record_run 的 --note。

3 · sessionInfo() 必记录

R 的环境指纹是 sessionInfo()，等价于 Python 侧的 env_hash，必须留痕：

1. 每个分析脚本末尾输出会话信息到产物目录：

   sink(file.path(out_dir, "session-info.txt"))
   print(sessionInfo())
   sink()
   

2. 登记 provenance 时把该文件一并作为产物路径，note 中摘要 R 版本与关键包版本：

   python <插件包路径>/skills/provenance-record/scripts/record_run.py \
     --path output/r-analysis/<slug>/latest/ \
     --tool "Rscript scripts/analyze-survival.R" \
     --note "生存分析，seed=42，R 4.4.1，survival 3.7-0，详见 session-info.txt"
   

3. 远程 R 任务同样抓回 session-info.txt 再登记（见 provenance-record 的远程一节）。

4 · 数据与产物

1. 原始数据只读：从 data/ 读，永不写回；清洗产物另存（中间产物进 output/r-analysis/<slug>/<timestamp>/，复用数据集进 derived/），纠错走增补（research-workspace 只读原则）。
2. 落盘契约与其他分析 skill 一致：

   output/r-analysis/<slug>/<timestamp>/   # 本次运行全部产物
   output/r-analysis/<slug>/latest/        # 运行结束后的完整副本
   

3. 图表双格式 300 dpi（与 python-analysis 相同约定）：

   ggsave(file.path(out_dir, "km-curve.png"), p, dpi = 300, width = 6, height = 4)
   ggsave(file.path(out_dir, "km-curve.pdf"), p, width = 6, height = 4)
   

4. 统计结果（系数表、检验结果）同时落机器可读文件（CSV），报告数字须能指回该文件。

5 · 报告：rmarkdown / quarto

1. 给人看的报告用 rmarkdown（.Rmd）或 quarto（.qmd）撰写，渲染产物（HTML/PDF/DOCX）放进同一次运行的时间戳目录。
2. 报告中的数字尽量由代码内联生成（`r knitr::inline_expr(...)` / quarto 的 {r} 行内表达式），减少手抄数字；必须手抄时，对照产物 CSV 逐个核对。
3. 渲染命令同样脚本化（如 Rscript -e "quarto::quarto_render('reports/xxx.qmd')"），不用 RStudio 的 Knit 按钮作为唯一渲染途径。
4. 报告交付前可复用 python-analysis 的 stats_integrity_check.py 做数字体检（百分比、p 值、样本量、CI 的确定性检查），error 清零方可交付。

6 · 完整示例

一次 analysis 阶段的 R 分析闭环（虚构示例，slug 为 3f9a1c7e）：

# 1. 环境（首次）：R 内执行 renv::init()，之后每次分析前 renv::restore()
# 2. 跑分析脚本（非交互，一条命令）
Rscript scripts/analyze-survival.R
#    脚本内部：set.seed(42)；读 data/2026-08-cohort/；
#    产物写 output/r-analysis/3f9a1c7e/20260819-153000/（含 session-info.txt）

# 3. 渲染报告（同样脚本化）
Rscript -e "quarto::quarto_render('reports/survival-2026-08.qmd')"

# 4. 刷新 latest（先清空再放副本），然后登记 provenance
python <插件包路径>/skills/provenance-record/scripts/record_run.py \
  --path output/r-analysis/3f9a1c7e/latest/ \
  --tool "Rscript scripts/analyze-survival.R" \
  --session cli-2026-08-19-01 \
  --note "KM + Cox 分析，seed=42，R 4.4.1，survival 3.7-0，详见 session-info.txt"

# 5. 报告数字体检
python <插件路径>/skills/python-analysis/scripts/stats_integrity_check.py \
  --path reports/survival-2026-08.md --format json

每一步都可单独重跑：环境坏了重 renv::restore()，结果存疑重跑第 2 步（同种子应得同结果），报告改版只重跑第 3 步。这条链路上任何一环不可重放，都说明前面的规程有缺口，先补规程再继续。

输出模板

分析完成后的汇报：

## R 分析完成（<任务名>）

- 环境：renv（renv.lock 已 snapshot），R <版本>
- 种子：set.seed(<N>)（已登记）
- 产物：output/r-analysis/<slug>/latest/（清单：…；含 session-info.txt）
- 报告：<渲染产物路径>
- provenance：已登记（note：…）

下一步：…

本技能不做什么

• 不替用户选统计模型与检验方法：模型适用性是领域判断，必要时标注 [模型知识—待核实] 并请用户确认。
• 不管理全局 R 安装：安装 R 本身、Rtools、系统库依赖向用户说明后由用户执行。
• 不动原始数据：清洗纠错一律生成新文件（research-workspace 只读原则）。
• 不覆盖 Python 生态：Python 分析走 python-analysis；混合项目两边产物分目录登记，互不混用 skill 名。
• 不做远程提交：集群上的 R 作业按 hpc-slurm 规程封装，本技能只管本地规程。

收尾与下一步

• 交付前清单：latest/ 已刷新、session-info.txt 在产物内、provenance 已登记、数字体检 error 清零。
• 结论支撑论文论断时进入 evidence-capsule 冻结（renv.lock + session-info.txt 一并打包）。
• 报告按 reviewer-protocol 接受发布前审查；error 级意见清零后交付。
• 任务运行时间长时改用 run-monitor 后台执行（Rscript 同样适用），会话不空等。