7.2 R Markdown：自动生成结案报告

7.2 R Markdown：自动生成结案报告

本节摘要：结案报告最大的敌人是"数据和结论对不上"——改了数据忘了改图表。R Markdown 把文字、代码、图表编进同一卷文档，代码即笔录，一键重渲染出报告。本节讲文档骨架、代码块的选项控制、参数化批量渲染，把前六章任何一案整理成可复现的正式卷宗。

一卷三材：文、码、图

R Markdown 文档就是普通文本加两种特殊区块：YAML 头信息定输出格式，反引号代码块嵌可执行的 R 代码。渲染时代码现场执行、图表现场生成、结果现场嵌进文档——报告与证据永远同步，这是"复制粘贴式报告"永远做不到的。

一份最简卷宗的骨架长这样：开头是三横线围住的 YAML 头（声明标题与输出格式），正文是普通 Markdown，中间穿插三反引号围成的 R 代码块，块头花括号里写块名与选项。示意如下（用缩进表示原样文本）：

---
title: "房价估价案结案报告"
output: html_document
---

## 案情摘要

本案检验房间数与低收入比例对房价中位数的解释力。

「r 代码块，块名 load」
data(Boston, package = "MASS")
fit <- lm(medv ~ rm + lstat, data = Boston)
summary(fit)

## 证据图

「r 代码块，块名 plot，选项 echo 为 FALSE」
plot(Boston$lstat, Boston$medv, xlab = "低收入比例", ylab = "房价中位数")
abline(lm(medv ~ lstat, data = Boston), col = "red")
​

代码块选项：控制现场

行内代码用反引号加 r 的写法嵌入正文，比如"本案样本量为某行内计算"——数字由代码算出，正文永远不需要手改。

参数化：一次写作，周周出卷

在 YAML 里声明参数，同一份卷宗每周换数据自动重出：

---
title: "周度油耗监测简报"
output: html_document
params:
  week: 2026-W33
---
​

# 文档内以 params$week 引用，例如做标题、筛数据
report_data <- subset(weekly_cases, week == params$week)
​

命令行批量渲染，一条命令出全年 52 期：

rmarkdown::render("简报模板", params = list(week = "2026-W34"))
​

手工报告与可复现卷宗的对比

报告自动化流水线

⚠️ 常见坑：报告里依赖控制台里手敲的变量——渲染在新环境从头执行，找不到变量当场报错。卷宗必须自足：数据导入、清洗、建模、出图全部写进代码块，任何一个环节靠"之前跑过"都会在渲染时翻车。

一份完整结案卷宗的块布局

真实报告的代码块不是随手插的，而是按"数据、函数、分析、图表、结论"的固定次序编排。给房价估价案排一个标准布局：

块 setup    （include 为 FALSE）library 全部集中在此，隐藏输出
块 data     （echo 为 FALSE）导入与清洗，正文只讲口径
块 model    （结果保留）lm 拟合与 summary，系数表现在成文
块 diagnose （fig.width 7 fig.height 5）四联诊断图
块 verdict  （eval 为 TRUE）用行内计算把效应量写进结论句
​

三个实操收益：库集中装载，改依赖只动一处；清洗块隐藏代码但结果可追溯，正文不被三百行管道淹没；图表块的宽高显式声明，渲染出的图在不同机器上尺寸一致——团队交接时这三点最先被感谢。

输出格式与表格修饰

output:
  html_document:
    toc: true            # 自动目录
    toc_float: true      # 目录侧边悬浮
    theme: readable      # 主题一张脸
  word_document: default # 同一卷宗同时出网页与文档版
​

正文里嵌回归表还有 kable 加持：把块选项设为 results 等于 asis，用 knitr 的 kable 函数把系数表渲染成正式表格，比贴 summary 原始输出体面得多。多格式输出是 R Markdown 的隐藏优势——委托人要文档版、归档要网页版，同一源文件各渲染一次即可，不存在"两个版本数字对不上"的事故。

⚠️ 排错实录一：渲染时报 could not find function——几乎总是某块依赖的包没在 setup 块装载，或变量定义在被 eval 等于 FALSE 跳过的块里。

排错实录二：图不显示——多半是 fig.show 或 include 被误设，或工作目录不对：渲染时的工作目录默认是文档所在目录，读数据请用相对该目录的路径。

本节要点回顾

• 代码即笔录：报告与证据同步，杜绝手工搬运出错
• 块选项四件：echo、eval、warning、include 控制现场
• 行内代码嵌数字：正文里的统计量由计算得出
• params 参数化：一份模板批量出卷
• 卷宗自足原则：渲染环境从零执行，不依赖会话残留
• 块布局有次序：setup、data、model、diagnose、verdict 依次排
• 图块显式宽高：跨机器渲染尺寸一致，团队交接少扯皮
• 多格式一份源：网页与文档版同源渲染，杜绝双版本错位

与本章第 1 节的呼应也值得落一笔：性能优化让分析"跑得动"，报告让结论"存得住、传得开"。实践中两者的顺序常常反过来——先用 R Markdown 把现行流程固化成卷宗，再对渲染变慢的环节做性能优化，"先可复现、再提速"是更稳的工程次序。