Skip to content

Data Science › R Foundations › R Markdown 與 Quarto

R Markdown 與 Quarto 報告 (Reproducible Reporting) ​

把文字、程式碼、圖表放在同一份檔案,報告由程式重新執行產生,而不是手動把數字和圖貼進 Word。資料更新、樣本剔除或方法修改後,重新 render 一次全部結果就同步更新。Quarto(.qmd)是 R Markdown(.Rmd)的後繼者,支援 R、Python、Julia,新專案建議直接用 Quarto;兩者觀念與大部分語法相同。溝通層面的寫作原則見 溝通分析結果。

R Markdown vs Quarto ​

R MarkdownQuarto
副檔名.Rmd.qmd(也能直接 render .ipynb)
本體R 套件 rmarkdown獨立 CLI(RStudio 內建),R 端用 quarto 套件呼叫
語言主要是 RR、Python、Julia、Observable JS
chunk 選項寫在 chunk header:{r, echo=FALSE}寫在 chunk 內:#| echo: false
YAML 輸出格式output: html_documentformat: html
網站 / 書 / 投影片blogdown、bookdown、xaringan(各自的套件)內建:project: type: website / book、format: revealjs
狀態維護中,不再新增大功能主力開發

文件結構 ​

markdown
---
title: "RNA-seq QC report"
author: "Lab"
date: today
format:
  html:
    toc: true
    number-sections: true
    code-fold: true          # 程式碼預設摺疊,讀者可展開
    embed-resources: true    # 單一 HTML 檔,方便寄送
execute:
  echo: false                # 全域:不顯示程式碼
  warning: false
params:
  min_count: 10
---

```{r}
#| label: setup
#| include: false
library(tidyverse)
counts <- read_tsv("data/counts.tsv")
```

## 摘要

共 `{r} ncol(counts) - 1` 個樣本,過濾門檻為每基因至少 `{r} params$min_count` reads。

```{r}
#| label: fig-libsize
#| fig-cap: "各樣本的 library size"
#| fig-width: 7
colSums(counts[-1]) |> enframe() |> ggplot(aes(name, value)) + geom_col()
```

如 @fig-libsize 所示……
元素R Markdown 寫法Quarto 寫法
YAML 標頭output: html_documentformat: html
行內程式碼`r nrow(df)``{r} nrow(df)`(舊寫法也可用)
chunk 選項```{r label, echo=FALSE}```{r} 下一行 #| echo: false
交叉引用圖表需 bookdown#| label: fig-xxx + @fig-xxx
渲染rmarkdown::render("a.Rmd")quarto render a.qmd(終端機)或 quarto::quarto_render()

Chunk 選項 ​

選項(Quarto 名)執行程式?顯示程式碼?顯示結果?用途
include: false✓✗✗載入套件、讀資料、設定
echo: false✓✗✓給讀者看圖表,不看實作
eval: false✗✓✗示範程式碼、教學
output: false✓✓✗只顯示程式碼
message: false / warning: false✓隱藏訊息 / 警告套件載入訊息
cache: true只在程式變動時重跑耗時的步驟(注意上游資料變了快取不會自動失效)
fig-width / fig-height / fig-cap圖的尺寸與說明

R Markdown 用 . 分隔(fig.width),Quarto 用 -(fig-width)。全域設定:R Markdown 用 setup chunk 裡的 knitr::opts_chunk$set(echo = FALSE),Quarto 用 YAML 的 execute:。

warning: false 是為了版面,不是為了忽略問題:交付前至少看過一次所有警告。

表格 ​

r
knitr::kable(summary_tbl, digits = 2, caption = "各組摘要")   # 簡單、所有格式都能輸出
gt::gt(summary_tbl) |> gt::fmt_number(decimals = 2)            # 精細排版(HTML / PDF / Word)
DT::datatable(de_results)                                       # HTML 可搜尋、排序的互動表格(差異表現結果)

參數化報告 ​

同一模板對不同樣本批次、組織、日期區間各產出一份,比複製十份檔案再手改穩定得多。

r
# R Markdown
rmarkdown::render("qc.Rmd", params = list(batch = "B2"),
                  output_file = "qc_B2.html")

# Quarto(R 端)
quarto::quarto_render("qc.qmd", execute_params = list(batch = "B2"),
                      output_file = "qc_B2.html")

# 批次產出
purrr::walk(c("B1", "B2", "B3"), \(b)
  quarto::quarto_render("qc.qmd", execute_params = list(batch = b),
                        output_file = paste0("qc_", b, ".html")))
bash
quarto render qc.qmd -P batch:B2 --output qc_B2.html

文件內用 params$batch 取值。

輸出格式 ​

格式Quarto format:備註
HTMLhtml互動圖表、code-fold、embed-resources: true 產生單檔
PDFpdf / typstpdf 需 LaTeX(quarto install tinytex);typst 不需 LaTeX、編譯快
Worddocx可用 reference-doc: 套用期刊 / 機構的樣式範本
投影片revealjs實驗室會議報告
網站 / 書_quarto.yml 中 project: type: website / book多頁實驗手冊、分析紀錄
期刊稿件Quarto journal extensions、manuscript 專案圖表引用、參考文獻(bibliography: refs.bib)

可重現報告的檢查清單 ​

項目做法
從頭到尾能跑在乾淨 session render(不依賴 console 裡殘留的物件);RStudio 的 Render 本來就在新 session 執行
路徑用相對路徑或 here::here(),不要寫死 C:/Users/...
套件版本renv 鎖定;報告結尾附 sessionInfo()
亂數setup chunk set.seed()
耗時步驟預先跑完存成 .rds,報告只讀入(比 cache: true 更透明)
原始資料唯讀,不在報告中覆寫

常見錯誤 ​

錯誤修正
在 console 能跑、render 失敗報告用到 console 才有的物件;所有讀取都寫在文件裡
把整個清理流程塞進一個巨大 chunk拆成有 label 的小 chunk,或把清理放在獨立 script,報告只 source() / 讀結果
手動在文字中寫數字改用行內程式碼,資料更新時不會不一致
cache: true 後改了上游資料,結果沒更新加 dependson,或清除快取資料夾重 render
HTML 寄出後圖片不見embed-resources: true(R Markdown:self_contained: true)