R Markdown与可重复研究

从代码到专业科研报告

王诗翔 副教授
中南大学生物医学信息系

课程介绍

为什么需要R Markdown？

传统科研工作流程的痛点

❌ 传统方式

  • Excel + Word + PPT 分离
  • 数据更新后手动改图
  • 代码和文档不同步
  • 难以复现分析过程

✅ R Markdown方式

  • 代码+文档一体化
  • 数据更新自动刷新
  • 一处修改全局更新
  • 完全可重复的分析

本讲目标

你将掌握

技能 应用场景
✅ Markdown语法 撰写README、文档
✅ R Markdown结构 生信分析报告
✅ 代码块控制 展示/隐藏分析过程
✅ 图表表格 发表级可视化
✅ Quarto工作流 现代科研写作

第1部分：Markdown基础

什么是Markdown？

Markdown是轻量级标记语言，用纯文本编写格式化文档

设计哲学

“让格式语法尽可能可读” — John Gruber

优势

  • ✅ 纯文本，版本控制友好
  • ✅ 易读易写，专注内容
  • ✅ 一键转换为HTML/PDF/Word

基础语法速查

标题与格式

# 一级标题
## 二级标题
**粗体**  *斜体*  ~~删除线~~
[链接](https://example.com)
![图片](image.png)
> 引用文字

列表与表格

- 无序列表
  - 子项目
1. 有序列表

| 基因 | 表达量 | 显著性 |
|------|--------|--------|
| TP53 | 12.5 | *** |

代码与公式

行内代码与代码块

使用 `filter()` 函数筛选数据

```r
# R代码块
library(dplyr)
data |> filter(age > 50)
```

LaTeX公式

行内：$E = mc^2$

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

第2部分：R Markdown核心

R Markdown是什么？

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

工作流程

.Rmd文件 → knitr执行 → Markdown → pandoc → HTML/PDF/Word
    ↑______________________________________________|
              (数据更新后重新编译)

核心优势

  1. 动态报告 — 数据变化，报告自动更新
  2. 可重复性 — 他人可完全复现分析
  3. 多格式输出 — 一份源码，多种格式

文档结构

---
title: "TP53基因表达分析"
author: "王诗翔"
date: "2025-02-27"
output: html_document
---

# 简介

TP53是重要的肿瘤抑制基因...

## 数据分析

```{r}
# 读取数据
expr_data <- read.csv("tp53_expression.csv")
summary(expr_data)
```

表达量分布如上图所示...

YAML元数据配置

---
title: "研究标题"
subtitle: "副标题"
author: "王诗翔"
date: "2025-02-27"
output: 
  html_document:
    toc: true              # 目录
    code_folding: hide     # 折叠代码
    theme: cerulean        # 主题
    fig_width: 8           # 图宽
    fig_height: 6          # 图高
---

代码块选项

基本语法

```{r chunk-name, echo=TRUE, eval=TRUE}
# R代码
x <- 1:10
mean(x)
```

常用选项

选项 说明 常用值
echo 显示代码 TRUE/FALSE
eval 执行代码 TRUE/FALSE
results 输出处理 'markup'/'hide'
warning 显示警告 TRUE/FALSE
message 显示消息 TRUE/FALSE
fig.width 图宽 数字
fig.height 图高 数字
fig.cap 图标题 字符串

代码块演示

只显示结果（隐藏代码）

```{r, echo=FALSE}
summary(cars)
```
     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

代码块演示

显示代码和结果

```{r}
head(cars, 3)
```
head(cars, 3)
  speed dist
1     4    2
2     4   10
3     7    4

内联代码

在文本中嵌入R代码结果，实现动态更新

数据集包含 50 个观测值，
平均速度为 15.4 mph。

数据集包含 50 个观测值， 平均速度为 15.4 mph。

生信应用

  • 自动更新样本量、P值
  • 确保正文与表格一致
  • 多组比较自动调整描述

图表输出

基础图形

plot(cars$speed, cars$dist, 
     main = "车速与刹车距离",
     xlab = "速度",
     ylab = "距离",
     pch = 19, col = "steelblue", cex = 1.5)

车速与刹车距离

ggplot2高级可视化

library(ggplot2)

ggplot(mtcars, aes(x = wt, y = mpg, color = factor(cyl))) +
  geom_point(size = 4, alpha = 0.7) +
  geom_smooth(method = "lm", se = FALSE) +
  labs(title = "汽车重量与油耗关系",
       subtitle = "按气缸数分组",
       x = "重量 (1000 lbs)",
       y = "每加仑英里数",
       color = "气缸数") +
  theme_minimal(base_size = 14)

表格制作

使用knitr::kable

knitr::kable(
  head(mtcars[, 1:5], 5),
  caption = "mtcars数据集前5行",
  align = c('l', 'c', 'c', 'c', 'c'),
  format = "html"
)
mtcars数据集前5行
mpg cyl disp hp drat
Mazda RX4 21.0 6 160 110 3.90
Mazda RX4 Wag 21.0 6 160 110 3.90
Datsun 710 22.8 4 108 93 3.85
Hornet 4 Drive 21.4 6 258 110 3.08
Hornet Sportabout 18.7 8 360 175 3.15

参数化报告

定义参数

---
params:
  gene: "TP53"
  tumor_type: "BRCA"
  threshold: 10
  show_plot: true
---

使用参数

```{r}
# 根据参数筛选数据
gene_data <- expr_data[expr_data$gene == params$gene, ]
mean_expr <- mean(gene_data$expression)

if (params$show_plot) {
  hist(gene_data$expression, main = params$gene)
}
```

第3部分：Quarto现代工作流

什么是Quarto？

Quarto是下一代科学出版系统，统一R Markdown、Jupyter等格式

与R Markdown的关系

R Markdown → Quarto → 统一的多语言平台
   ↓              ↓
仅支持R      R + Python + Julia

核心优势

  • 🌐 多语言支持 — 不限于R
  • 📱 响应式设计 — 移动端友好
  • 🎨 现代外观 — 更美观的默认样式
  • 🔗 原生交叉引用 — 无需额外包

Quarto文档结构

---
title: "Quarto演示"
format: 
  html:
    code-fold: true
    code-tools: true
---

## Python分析

```{python}
import pandas as pd
import numpy as np

df = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100)
})
df.describe()
```

## R可视化

```{r}
library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg)) + 
  geom_point(color = "steelblue", size = 3) +
  theme_minimal()
```

Quarto vs R Markdown

功能 R Markdown Quarto
代码选项 {r, echo=FALSE} #| echo: false
图宽 fig.width=8 #| fig-width: 8
交叉引用 需bookdown 原生支持
多语言 仅R R/Python/Julia

Quarto代码块选项

基本语法（Quarto风格）

```{r}
#| label: chunk-name
#| echo: false
#| eval: true
#| fig-width: 8
#| fig-height: 6
#| fig-cap: "图表标题"

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

交叉引用

见 @fig-tp53 显示了TP53表达分布。

```{r}
#| label: fig-tp53
#| fig-cap: "TP53基因表达分布"

tp53_expr <- c(8.5, 12.3, 6.7, 15.2, 9.1, 11.5, 7.8, 13.2)
hist(tp53_expr, main = "TP53基因表达分布", 
     xlab = "表达量", col = "steelblue")
```

第4部分：最佳实践

可重复性研究原则

1. 环境记录

# 记录会话信息
sessionInfo()

# 使用renv管理依赖
renv::init()      # 初始化
renv::snapshot()  # 保存状态
renv::restore()   # 恢复环境

2. 项目结构

project/
├── data/          # 原始数据（只读）
├── analysis/      # 分析脚本
├── output/        # 结果输出
├── figures/       # 图表
├── report.qmd     # 主报告
└── renv.lock      # 环境锁定

代码规范

命名规范

# ✅ 推荐
calculate_bmi <- function(weight_kg, height_m) {}
patient_age <- 25
tumor_samples <- c("T1", "T2", "T3")

# ❌ 避免
calc <- function(w, h) {}
x <- 25
samples <- c("T1", "T2", "T3")

文档注释

#' 计算差异表达基因
#' 
#' @param expr_matrix 表达矩阵
#' @param group 分组信息
#' @param method 检验方法
#' @return 差异表达结果数据框
#' @export
find_de_genes <- function(expr_matrix, group, method = "t-test") {
  # 实现...
}

生信报告模板

标准结构

# 标题

## 1. 背景介绍
研究背景、目的

## 2. 数据与方法
- 数据来源
- 分析方法
- 软件版本

## 3. 结果
### 3.1 数据质控
### 3.2 差异分析
### 3.3 功能富集

## 4. 讨论与结论

## 5. 附录
- 代码
- 会话信息

总结与展望

本讲要点

Markdown

  • 轻量级标记语言，专注内容
  • 支持标题、列表、表格、代码、公式

R Markdown

  • 代码+文本=动态报告
  • YAML配置、代码块选项、内联代码
  • 参数化报告实现自动化

Quarto

  • 下一代科学出版系统
  • 多语言支持、原生交叉引用

练习作业

基础练习

  1. 用Markdown写一段实验方法描述
  2. 创建包含代码、图表的R Markdown报告
  3. 使用内联代码显示统计结果

进阶练习

  1. 创建参数化报告（分析不同基因）
  2. 将R Markdown转换为Quarto
  3. 添加交叉引用和目录

思考

  • 如何保证分析的可重复性？
  • 在什么情况下选择Quarto而非R Markdown？

课程总结

实验设计 → 数据采集 → 质量控制 → 
统计分析 → 可视化 → R Markdown/Quarto → 
可重复性报告 → 投稿发表

核心能力

  • 用 R 处理和分析数据
  • 用 tidyverse 高效编程
  • 用 R Markdown/Quarto 撰写报告
  • 遵循 可重复性 研究原则

开始你的可重复研究之旅！

王诗翔 副教授
中南大学生物医学信息系

📧 wangshx@csu.edu.cn
🐙 https://github.com/WangLabCSU

下节课预告

  • 实验指导：R Markdown实战
  • 撰写你的第一份生信分析报告

谢谢！