创建可重复性研究报告

本讲概述

本讲将介绍如何使用R Markdown创建动态、可重复的研究报告：

  • Markdown基础语法
  • R Markdown文档结构
  • 代码块与输出控制
  • 图表与表格
  • 参数化报告

预计时长：45分钟理论 + 15分钟演示

1. Markdown基础

1.1 什么是Markdown？

Markdown是John Gruber于2004年创建的轻量级标记语言，设计目标是：

“Readability is the primary design goal”

1.2 基础语法速查

语法 效果
# 标题 一级标题
## 标题 二级标题
**粗体** 粗体
*斜体* 斜体
`代码` 代码
[链接](url) 链接
![图片](url) 图片
- 列表 无序列表
1. 列表 有序列表

1.3 扩展语法

| 表格 | 列2 |
|------|-----|
| 内容 | 内容 |

> 引用文字

---

分割线

~~删除线~~

1.4 LaTeX公式

行内公式: $E = mc^2$

独立公式:
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$

2. R Markdown入门

2.1 什么是R Markdown？

R Markdown = R代码 + Markdown文本 → 动态报告

工作流程：

.Rmd 文件 
   ↓
knitr (执行代码)
   ↓
.md 文件
   ↓
pandoc (转换)
   ↓
HTML / PDF / Word

2.2 文档结构

---
title: "报告标题"
author: "作者"
date: "2025-02-27"
output: html_document
---

# 第一章

正文内容...


::: {.cell}

```{.r .cell-code}
# R代码
summary(cars)
```

::: {.cell-output .cell-output-stdout}

```
     speed           dist       
 Min.   : 4.0   Min.   :  2.00  
 1st Qu.:12.0   1st Qu.: 26.00  
 Median :15.0   Median : 36.00  
 Mean   :15.4   Mean   : 42.98  
 3rd Qu.:19.0   3rd Qu.: 56.00  
 Max.   :25.0   Max.   :120.00  
```


:::
:::


## 1.1 小节

更多内容...

2.3 YAML元数据

---
title: "研究标题"
subtitle: "副标题"
author: 
  - name: "王诗翔"
    affiliation: "中南大学"
  - name: "合作者"
    affiliation: "其他单位"
date: "2026-02-28"
output: 
  html_document:
    toc: true              # 目录
    toc_float: true        # 浮动目录
    code_folding: show     # 代码折叠
    number_sections: true  # 章节编号
    theme: cerulean        # 主题
    highlight: tango       # 代码高亮
  pdf_document:
    toc: true
    latex_engine: xelatex
---

3. 代码块

3.1 基本语法

```{r}
#| label: chunk-name
#| echo: true
#| eval: true

# R代码
x <- 1:10
mean(x)
```

3.2 常用选项

选项 说明 常用值
echo 显示代码 true/false
eval 执行代码 true/false
output 显示结果 true/false
fig-width 图宽 数字(英寸)
fig-height 图高 数字(英寸)
fig-cap 图标题 字符串
warning 显示警告 true/false
message 显示消息 true/false

3.3 代码块示例

显示代码和结果（默认）：

```{r}
head(mtcars, 3)
```

只显示结果：

```{r}
#| echo: false
summary(cars)
```

显示代码，不执行：

```{r}
#| eval: false
# 耗时计算
heavy_computation()
```

隐藏警告：

```{r}
#| warning: false
library(tidyverse)  # 抑制加载警告
```

显示代码，不执行：

```{r}
#| eval: false
# 耗时计算
heavy_computation()
```

隐藏警告：

```{r}
#| warning: false
library(tidyverse)  # 抑制加载警告
```

4. 内联代码

4.1 语法

使用 `r 和 ` 包裹R代码：

数据集包含 32 个观测值，
平均油耗为 20.090625 mpg。

4.2 应用场景

  • 自动更新样本量
  • 动态插入统计结果
  • 确保正文与表格数据一致

示例代码（缩进4空格表示代码块）：

分析显示，TP53基因在肿瘤组的平均表达量为 `r round(mean(tp53_tumor), 2)`， 显著高于正常组（p = `r format(p_value, digits=2, scientific=TRUE)`）。

5. 图表与表格

5.1 基础图形

```{r}
#| fig-width: 8
#| fig-height: 6
#| fig-cap: "基因表达散点图"
plot(tp53_expr, p53_protein,
     main = "TP53 mRNA与蛋白表达相关性",
     xlab = "TP53 mRNA表达量",
     ylab = "p53蛋白水平",
     pch = 19, col = "steelblue")
```

5.2 ggplot2图形

```{r}
#| fig-cap: "差异表达基因火山图"
library(ggplot2)

ggplot(de_results, aes(x = log2FoldChange, y = -log10(pvalue))) +
  geom_point(aes(color = abs(log2FoldChange) > 1 & pvalue < 0.05)) +
  theme_minimal() +
  labs(title = "差异表达基因火山图",
       x = "log2 Fold Change",
       y = "-log10(p-value)")
```

5.3 表格

基础表格：

```{r}
knitr::kable(
  head(gene_expr_summary, 5),
  caption = "基因表达统计摘要（前5个基因）",
  align = c('l', 'c', 'c', 'c')
)
```

交互式表格（HTML）：

```{r}
DT::datatable(de_results, options = list(pageLength = 10))
```

6. 参数化报告

6.1 定义参数

---
params:
  cancer_type: "BRCA"
  gene_of_interest: "TP53"
  fc_threshold: 2
  pvalue_threshold: 0.05
  show_volcano: true
---

6.2 使用参数

```{r}
# 筛选差异表达基因
de_genes <- de_results[
  abs(de_results$log2FoldChange) > params$fc_threshold &
  de_results$pvalue < params$pvalue_threshold,
]

cat("癌症类型:", params$cancer_type, "\n")
cat("目标基因:", params$gene_of_interest, "\n")
cat("差异表达基因数:", nrow(de_genes), "\n")
```

```{r}
#| eval: params$show_volcano
# 条件显示火山图
plot_volcano(de_results, params$fc_threshold, params$pvalue_threshold)
```

6.3 应用场景

  • 批量生成各癌症类型的分析报告
  • 不同参数敏感性分析
  • 多中心研究的分中心报告

7. 输出格式

7.1 HTML文档

output:
  html_document:
    toc: true
    toc_float: true
    code_folding: show
    theme: cerulean  # default, bootstrap, cerulean, journal...
    highlight: tango  # default, tango, pygments, kate...

7.2 PDF文档

output:
  pdf_document:
    toc: true
    number_sections: true
    latex_engine: xelatex  # 支持中文
    template: null  # 可自定义模板

需要安装LaTeX：

代码 
install.packages("tinytex")
tinytex::install_tinytex()

7.3 Word文档

output:
  word_document:
    toc: true
    reference_docx: template.docx  # 自定义样式

8. 高级技巧

8.1 代码重用

使用 knitr::read_chunk() 引用外部代码文件：

```{r}
#| include: false
knitr::read_chunk('analysis.R')
```

```{r}
#| label: analysis-setup
# 这里会插入 analysis.R 中标记为 ## ----analysis-setup 的代码
```

8.2 条件输出

```{r}
#| include: knitr::is_html_output()
# 仅在HTML输出时包含
DT::datatable(de_results)
```

```{r}
#| include: knitr::is_latex_output()
# 仅在PDF输出时包含
knitr::kable(head(de_results, 20))
```

8.3 参考文献

---
bibliography: references.bib
csl: nature.csl  # 引用样式
---

详见Smith等人的研究 [@smith2020]。

# 参考文献

关键要点

概念 要点
.Rmd结构 YAML + Markdown + 代码块
代码块选项 控制代码显示与执行
内联代码 实现动态更新
参数化 一份模板，多份报告
多格式 HTML/PDF/Word一键生成

课堂演示

  1. 创建新R Markdown文档
  2. 配置YAML元数据
  3. 添加代码块并设置选项
  4. 插入图表和表格
  5. Knit生成HTML和PDF

课后作业

  1. 阅读 R Markdown Cookbook
  2. 完成实验手册练习2
  3. 准备自己的第一份R Markdown报告（基因表达分析报告）

下节预告：Quarto —— 下一代科学出版工具

联系信息

  • 授课教师：王诗翔 副教授
  • 单位：中南大学 · 生物信息学 专业
  • 实验室主页：https://wanglabcsu.github.io/
  • 邮箱：wangshx@csu.edu.cn
  • GitHub：https://github.com/WangLabCSU