{
"title": "R 包 | R Markdown：数据报告生成利器",
"tags": [
"post",
"技术",
"R Markdown",
"数据报告",
"可重复性",
"可视化"
],
"sources": [
"xlog"
],
"external_urls": [
"https://xlog.aetherhjf.com/r-rmarkdown"
],
"date_published": "2023-03-23T08:05:39.772Z",
"content": "# R 包 | R Markdown：数据报告生成利器\n\n\n<center>\n <i> \n R Markdown 站在 knitr 和 Pandoc 的肩膀上，前者执行嵌入于文档中的计算机代码，并将 R Markdown 转换为 Markdown；后者将 Markdown 呈现出您想要的输出格式（如 PDF、HTML、Word 等）\n </i>\n</center>\n\n<br>\n\n<!--more-->\n\n此篇文章翻译自谢益辉新书 [《R Markdown: The Definitive Guide》](https://bookdown.org/yihui/rmarkdown/) 的前三章节，内容有所删减，主要介绍了 R Markdown 的相关结构及语法规则，如果想了解更多更详细的内容推荐您阅读原书。\n\n# 安装\n\n这里假设您已经安装了 R ([https://www.r-project.org](https://www.r-project.org/)) 和 RStudio IDE ([https://www.rstudio.com](https://www.rstudio.com/)) 。Rstudio 并不是必须的，但安装它会使您更加容易地使用 R Markdown。如果您没有安装 RStudio IDE，您将不得不安装 Pandoc（ [http://pandoc.org](http://pandoc.org) ），否则就不需要单独安装 Pandoc，因为在安装 RStudio 时已经将它捆绑安装了。接下来，您可以在 R 中安装 `rmarkdown` 包：\n\n```R 安装 rmarkdown 包的两种方式\n# Install from CRAN\ninstall.packages('rmarkdown')\n\n# Or if you want to test the development version,\n# install from GitHub\nif (!requireNamespace(\"devtools\"))\n install.packages('devtools')\ndevtools::install_github('rstudio/rmarkdown')\n```\n\n如果您想要生成 PDF 类型文档输出，您将需要安装 LaTeX 。对于那些以前没有安装过 LaTeX 的 R Markdown 用户，我们建议您安装 TinyTeX（https://yihui./tinytex/）：\n\n```R 安装 tinytex 包\ninstall.packages(\"tinytex\")\ntinytex::install_tinytex() # install TinyTeX\n```\n\nTinyTeX 相当于一款轻量级、跨平台、易于维护的 LaTeX 。在将 LaTeX 或 R Markdown 文档编译成 PDF 时，`tinytex` 可以帮助您自动安装所需的相关 R 包，同时还能确保一个 LaTeX 文档被编译成正确的次数，以解决所有的交叉引用问题。如果您不明白这两件事是什么意思，应该按照我们的建议来安装 TinyTeX，因为这些细节往往并不值得您花费时间和精力去关心。\n\n使用 `rmarkdown` 包、RStudio/Pandoc 和 LaTeX，您应该能够编译大多数 R Markdown 文档。在某些情况下，您可能需要其他软件包，我们将在必要时提到它们。\n\n> **参考文献**\n>\n> - R Core Team. 2018. _R: A Language and Environment for Statistical Computing_. Vienna, Austria: R Foundation for Statistical Computing. [https://www.R-project.org/](https://www.r-project.org/).\n> - Xie, Yihui. 2018f. _Tinytex: Helper Functions to Install and Maintain Tex Live, and Compile Latex Documents_. <https://github.com/yihui/tinytex>.\n\n---\n\n# 基础知识\n\nR Markdown 为数据科学提供了一个创作框架。R Markdown 能胜任以下两个任务：\n\n- 保存并执行代码；\n- 生成可共享的高质量报告。\n\nR Markdown 的设计初衷是为了更容易地实现报告内容的可重复性，这是因为计算代码和叙述都在同一个文档中，结果是由源代码自动生成的。并且 R Markdown 支持数十种静态和动态/交互式输出格式。\n\n如果您更喜欢观看视频进行学习，我们建议您查看网站 [https://rmarkdown.rstudio.com](https://rmarkdown.rstudio.com)，并在 “Get Started ” 中观看视频，其中包括了 R Markdown 的基础知识。\n\n## 文档结构\n\n下面是一份非常简易的 R Markdown 文档，是一个带有 `.Rmd` 拓展名的纯文本文档。\n\n```yaml YAML 元数据\n---\ntitle: \"Hello R Markdown\"\nauthor: \"Awesome Me\"\ndate: \"2018-02-14\"\noutput: html_document\n---\n```\n\n````markdown 主体内容\nThis is a paragraph in an R Markdown document.\n\nBelow is a code chunk:\n\n```{r}\nfit = lm(dist ~ speed, data = cars)\nb = coef(fit)\nplot(cars)\nabline(fit)\n```\n\nThe slope of the regression is `r b[1]`.\n\n```\n\n```\n````\n\n您可以使用任何文本编辑器（包括但不限于 RStudio）来创建这样的文本文档。如果使用 RStudio，您可以从 `File -> New File -> R Markdown ` 中创建一个新的 Rmd 文档。\n\n一份 R Markdown 文档有三个基础组成部分：元数据，文本和代码。元数据是在三个连接符 `---` 之间的内容。元数据的语法是 YAML（ [YAML 不是标记语言](https://en.wikipedia.org/wiki/YAML) ），所以有时它也被称为 YAML metadata 或 YAML frontmatter。 需要注意的是，缩进在 YAML 中十分重要，忽视它会让你付出惨重代价。请参阅谢益辉所写的 《bookdown》（2016）一书中的 [附录 b.2](https://bookdown.org/yihui/bookdown/r-markdown.html) 来了解一些简单的例子，这些示例展示了 YAML 语法。\n\n文档的主体遵循元数据书写的规则。文本的语法是 Markdown，将在第 2.5 节中进行介绍。有两种类型的计算机代码，在第 2.6 节中进行了详细解释：\n\n- **代码块**：以三个重音符及所使用语言开始，其中 `r` 代表所使用的程序语言，并以三个重音符结束。 可以在花括号中填写块选项（如：将图形高度设置为 5 英寸：`{r, fig.height=5}`）。\n- **内联代码**：以 ``r` 开始，并以单个重音符结束。\n\n## 文档编译\n\n最简单的方式莫过于在 RStudio 中单击 `Knit` 按钮，对应的快捷键为 `Ctrl + Shift + K` （在 macOS 中为 `Cmd + Shift + K`）。当然也可以直接运行代码 `rmarkdown::render` 来进行渲染编译，如：\n\n```R 文档渲染编译\nrmarkdown::render('foo.Rmd', 'pdf_document')\n```\n\n当编译多个文档时，使用函数更加方便，因为可以直接使用循环来进行渲染编译。\n\n## 参考卡片\n\nRStudio 已经创建了大量的参考卡片，它们可以在 https://www.rstudio.com/resources/cheatsheets/ 上免费获得。\n\n## 输出格式\n\n有两种输出格式：documents 和 presentations 。所有可用的格式如下所示 ：\n\n- `beamer_presentation`\n- `github_document`\n- `html_document`\n- `ioslides_presentation`\n- `latex_document`\n- `md_document`\n- `odt_document`\n- `pdf_document`\n- `powerpoint_presentation`\n- `rtf_document`\n- `slidy_presentation`\n- `word_document`\n\n我们将在第 3 章和第 4 章详细地记录这些输出格式。在其他扩展包中提供了更多的输出格式（从第 5 章开始）。对于 Rmd 文件的 YAML 元数据中的输出格式名称，如果格式来自扩展包，您需要包含包名（若格式来自于 `rmarkdown` 包，则不需要 `rmarkdown::`前缀 ），例如：\n\n```yaml 输出格式设置\noutput: tufte::tufte_html\n```\n\n每种输出格式通常都有多种格式选项。所有这些选项都记录在 R 包 help 页面上。例如，您可以在 R 中键入 `?rmarkdown::` 打开关于 `html_document` 格式的 help 页面。当您想要使用某些选项时，必须将这些值从 R 转换成 YAML，例如：\n\n```R ?rmarkdown::\nhtml_document(toc = TRUE, toc_depth = 2, dev = 'svg')\n```\n\n可以用 YAML 写为：\n\n```yaml 输出格式参数设置\noutput:\n html_document:\n toc: true\n toc_depth: 2\n dev: \"svg\"\n```\n\nYAML 中的字符串通常不需要引号（``dev：“svg”` 和 `dev:svg` 是相同的），除非它们包含特殊字符，比如冒号 `：`。如果您不确定是否应该引用字符串，那么用 `yaml` 包来测试它，例如：\n\n```R YAML 语法\ncat(yaml::as.yaml(list(\n title = 'A Wonderful Day',\n subtitle = 'hygge: a quality of coziness'\n)))\n\n## title: A Wonderful Day\n## subtitle: 'hygge: a quality of coziness'\n```\n\n注意，上面例子中的副标题是由于冒号而引用单引号的。\n\n如果某一选项有子选项（这意味着该选项的值是 R 中的列表），则子选项需要进一步缩进，例如：\n\n```yaml 子选项-缩进\noutput:\n html_document:\n toc: true\n includes:\n in_header: header.html\n before_body: before.html\n```\n\n一些选项将被传递给 **knitr** ，比如 `dev`、`fig_width` 和 `fig_height`。这些选项的详细文档可以在 [knitr 文档页面](https://yihui.name/knitr/options/) 上找到。请注意，实际的 knitr 选项名称可能有所不同。特别是，knitr 在名称中使用 `.`，但 rmarkdown 使用 `_`，例如，在 rmarkdown 中，`fig_width` 对应于 knitr 中的 `fig.width` 。\n\n一些选项将被传递给 **Pandoc**，比如 `toc`、`toc_depth` 和 `number_sections` 。当有疑问时，您应该参考 Pandoc 文档。R Markdown 输出格式函数通常有一个`pandoc_args` 参数，它应该是传递给 Pandoc 的参数的字符向量。如果您发现任何没有由输出格式参数表示的 Pandoc 特性，您可以使用这个终极论证，例如：\n\n```yaml pandoc_args 参数\noutput:\n pdf_document:\n toc: true\n pandoc_args: [\"--wrap=none\", \"--top-level-division=chapter\"]\n```\n\n## Markdown 语法\n\n### 内联格式\n\n- _斜体_ ：`_text_` 或 `*text*`\n\n- **粗体** ：`**text** `\n\n- 下标 ：`H~3~PO~4~` 渲染为 $H_3PO_4$\n\n- 上标 ：`Cu^2+^` 渲染为 $Cu^{2+}$\n\n- 脚注 ： `^[This is a footnote.]`\n\n- 内联代码 ：`` `code` `` , 可以使用 n+1 个重音符输出包含 n 个重音符的代码块。\n\n- 超链接 ：`[text](link) `\n\n- 图片链接 ： ``\n\n- 引用 ：\n\n ```ruby 书籍引用\n @Manual{R-base,\n title = {R: A Language and Environment for Statistical\n Computing},\n author = {{R Core Team}},\n organization = {R Foundation for Statistical Computing},\n address = {Vienna, Austria},\n year = {2017},\n url = {https://www.R-project.org/},\n }\n ```\n\n### 块级元素\n\n- **标题**\n\n ```Markdown 三级标题的书写\n # First-level header\n\n ## Second-level header\n\n ### Third-level header\n ```\n\n 如果不想让某个标题被编号，可以在标题后面添加 `{-}` 或者 `{.unnumbered}`，如：\n\n ```Markdown 标题不编号\n # Preface {-}\n ```\n\n- **无序列表**\n\n ```Markdown 无序列表\n - one item\n - one item\n - one item\n - one more item\n - one more item\n - one more item\n ```\n\n- **有序列表**\n\n ```Markdown 有序列表\n 1. the first item\n 2. the second item\n 3. the third item\n - one unordered item\n - one unordered item\n ```\n\n- **引用**\n\n ```Markdown 名言引用\n > \"I thoroughly disapprove of duels. If a man should challenge me,\n I would take him kindly and forgivingly by the hand and lead him\n to a quiet place and kill him.\"\n >\n > --- Mark Twain\n ```\n\n > \"I thoroughly disapprove of duels. If a man should challenge me,\n > I would take him kindly and forgivingly by the hand and lead him\n > to a quiet place and kill him.\"\n >\n > --- Mark Twain\n\n- **代码块**\n\n ````Markdown 代码块\n ```\n This text is displayed verbatim / preformatted\n ```\n\n Or indent by four spaces:\n\n This text is displayed verbatim / preformatted\n ````\n\n### 数学表达式\n\n`$f(k) = {n \\choose k} p^{k} (1-p)^{n-k}$ ` : $f(k) = {n \\choose k} p^{k} (1-p)^{n-k}$\n\n`$$f(k) = {n \\choose k} p^{k} (1-p)^{n-k}$$ ` :\n\n$$\nf(k) = {n \\choose k} p^{k} (1-p)^{n-k}\n$$\n\n---\n\n## 代码块选项\n\n单击 `Insert` 按钮，对应快捷键为 `Ctrl + Alt + I` （macOS：`Cmd + Option + I` ）。\n\n在 <https://yihui.name/knitr/options> 中有大量的代码块可选项，在此我们列出常用的一部分：\n\n- `eval=TRUE` ：执行当前代码块；\n\n ````R eval 巧用\n ```{r}\n # execute code if the date is later than a specified day\n do_it = Sys.Date() > '2018-02-14'\n ```\n\n ```{r, eval=do_it}\n x = rnorm(100)\n ```\n ````\n\n- `echo=TRUE` ：输出源代码；\n\n- `result` ：当设置为 `'hide'` ，文本输出将被隐藏；当设置为 `'asis'` ，文本输出将被 “原样” 书写。\n\n- `collapse=TRUE` ：将文本输出和源代码合并为单个代码块输出，更加紧凑；\n\n- `warning`, `message`, `error` ：是否在输出文档中显示警告、消息和错误；\n\n- `include=FALSE` ：运行当前代码并且不显示任何源代码与输出结果；\n\n- `cache` ：是否启用高速缓存。如果启用了缓存，则在下一次编译文档时不会对相同的代码块进行评估（如果代码块没有被修改），这将节省您的时间；\n\n- `fig.width`，`fig.height` ：（图形设备）块的大小（英寸）。注意：`fig.dim = c(6, 4)` 意味着 `fig.width = 6` 并且 `fig.height = 4`；\n\n- `out.width`， `out.height` ：输出文档中 R 图片的输出大小。可以使用百分比，例如 `out.width = '80%'` 表示页面宽度的 80%；\n\n- `fig.align` ：图片的对齐方式；\n\n- `dev` ：图形设备保存 R 图片的格式。如 `'pdf'`, `'png'`, `'svg'`, `'jpeg'`；\n\n- `fig.cap` ：图片标题；\n\n- `child` ：您可以在主文档中包含子文档。这个选项选择一条通向外部文件的路径。\n\n如果某个选项需要经常被设置为多个代码块中的值，您可以考虑在文档的第一个代码块中全局设置它：\n\n````R 全局设置\n```{r, setup, include=FALSE}\nknitr::opts_chunk$set(fig.width = 8, collapse = TRUE)\n```\n````\n\n### 图片\n\n本地图片亦可以使用代码块选项进行调节，例如：\n\n````R 本地图片选项\n```{r, out.width='25%', fig.align='center', fig.cap='...'}\nknitr::include_graphics('images/hex-rmarkdown.png')\n```\n````\n\n如果您想要淡入一个不是由 R 代码生成的图形，您可以使用 `knitr::include_graphics()` 函数，它使您能够更好地控制图像的属性，而不是像 `` 这样的 Markdown 语法难以调解图片属性。\n\n### 表格\n\n使用 `knitr::kable()` 函数可以简易的创建表格，表格标题可以通过 `caption` 来设置，例如：\n\n````R 表格选项\n```{r tables-mtcars}\nknitr::kable(iris[1:5, ], caption = 'A caption')\n```\n````\n\n如果您正在寻找更高级的表格样式控制，建议您使用 [kableExtra](https://cran.r-project.org/package=kableExtra) 包，它提供了定制 PDF 和 HTML 表格外观的功能。在第 12.3 节中解释了 `bookdown` 包如何扩展 rmarkdown 的功能，以允许在文本中轻松地交叉引用数字和表格。\n\n> **参考文献**\n>\n> - Xie, Yihui. 2015. *Dynamic Documents with R and Knitr*. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. <https://yihui.name/knitr/>.\n\n---\n\n# 输出文档\n\n## HTML 文档\n\n为了输出 HTML 文档，首先要在 YAML 元数据中写入 `output: html_document` ：\n\n```yaml\n---\ntitle: Habits\nauthor: John Doe\ndate: March 22, 2005\noutput: html_document\n---\n```\n\n### 目录（Table of contents）\n\n```yaml 目录可选项\n---\ntitle: \"Habits\"\noutput:\n html_document:\n toc: true\n toc_depth: 2\n toc_float:\n collapsed: false\n smooth_scroll: false\n---\n```\n\n- `toc: true` ：输出目录；\n- `toc_depth` ：所输出标题的最小级别；\n- `toc_float: true` ：目录悬停于内容左侧，并一直可见；\n- `collapsed` (默认为 `TRUE`) ：初始只显示顶级标题，随内容滚动目录逐级展开；\n- `smooth_scroll` (默认为 `TRUE`) ：点击目录标题是否导航到指定内容。\n\n### 目录编号 (Section numbering)\n\n```yaml 目录编号\n---\ntitle: \"Habits\"\noutput:\n html_document:\n toc: true\n number_sections: true\n---\n```\n\n注意，如果文档中没有一级标题，那么二级标题将被命名为 `0.1`, `0.2` ……\n\n### 选项卡 (Tabbed sections)\n\n```markdown 选项卡\n## Quarterly Results {.tabset .tabset-fade .tabset-pills}\n\n### By Product\n\n(tab content)\n\n### By Region\n\n(tab content)\n```\n\n\n\n- `.tabset` ：使主标题的所有子标题与 .tabset 属性一起出现在选项卡中，而不是作为独立的部分；\n- `.tabset-fade` ：选项卡切换时淡入淡出；\n- `.tabset-pills` ：改变选项卡外观，使其类似 “药丸”。\n\n### 外观与风格\n\n```yaml 主题与高亮\n---\ntitle: \"Habits\"\noutput:\n html_document:\n theme: united\n highlight: tango\n---\n```\n\n- `theme` ：主题是从 [Bootswatch](https://bootswatch.com/3/) 主题库中提取的，适用的主题包括：`default`, `cerulean`, `journal`, `flatly`, `readable`, `spacelab`, `united`, `cosmo`, `lumen`, `paper`, `sandstone`, `simplex`, 和 `yeti`.\n- `highlight` ：代码高亮模式。支持的风格包括： `default`, `tango`, `pygments`, `kate`, `monochrome`, `espresso`, `zenburn`, `haddock` 和 `textmate`.\n\n### 图片选项\n\n```yaml 图片选项\n---\ntitle: \"Habits\"\noutput:\n html_document:\n fig_width: 7\n fig_height: 6\n fig_caption: true\n---\n```\n\n- `fig_width` 和 `fig_height` ：图片宽度和高度；\n- `fig_caption` ：控制图片是否包括标题；\n- `dev` ：图片渲染格式，默认为 `png`。\n\n### 表格打印\n\n默认表格输出格式为：\n\n| Option | Description |\n| :-----: | :--------------------------------------------------------- |\n| default | Call the `print.data.frame` generic method |\n| kable | Use the `knitr::kable` function |\n| tibble | Use the `tibble::print.tbl_df` function |\n| paged | Use `rmarkdown::print.paged_df` to create a pageable table |\n\n设定为 paged 格式后输出形式为：\n\n````yaml 表格设置\n---\ntitle: \"Motor Trend Car Road Tests\"\noutput:\n html_document:\n df_print: paged\n---\n``` {r, rows.print=5}\nmtcars\n```\n````\n\n\n\nTABLE 3.2: The options for paged HTML tables.\n\n| Option | Description |\n| -------------- | ----------------------------------------------------- |\n| max.print | The number of rows to print. |\n| max.print | The number of rows to print. |\n| cols.print | The number of columns to display. |\n| cols.min.print | The minimum number of columns to display. |\n| pages.print | The number of pages to display under page navigation. |\n| pages.print | The number of pages to display under page navigation. |\n| rownames.print | When set to `FALSE` turns off row names. |\n\n### 代码折叠\n\n```yaml 代码隐藏\n---\ntitle: \"Habits\"\noutput:\n html_document:\n code_folding: hide\n---\n```\n\n- `code_folding: hide` ：初始默认不显示代码，查看者可点击进行显示；\n- `code_folding: show` ：初始默认显示代码，查看者可点击进行隐藏；\n\n### 高级定制\n\n#### 保留 Markdown 文件\n\n当运行一个 R Markdown 文件（`*.Rmd`）时，将创造一个 Markdown 文件（`*.md`）并将该文件通过 Pandoc 转换为 HTML 文件。如果想要保留 Markdown 文件，可以使用 `keep_md` 选项：\n\n```yaml 保留 .md 文档\n---\ntitle: \"Habits\"\noutput:\n html_document:\n keep_md: true\n---\n```\n\n#### 添加本地 HTML 文档\n\n可以通过添加额外的 HTML 内容或完全替换核心 Pandoc 模板来完成更高级的输出定制。为了在文档头部或文档主体之前/之后包含内容，您可以使用以下选项：\n\n```yaml 添加 HTML 文档\n---\ntitle: \"Habits\"\noutput:\n html_document:\n includes:\n in_header: header.html\n before_body: doc_prefix.html\n after_body: doc_suffix.html\n---\n```\n\n#### 自定义模板\n\n```yaml 自定义模板\n---\ntitle: \"Habits\"\noutput:\n html_document:\n template: quarterly_report.html\n---\n```\n\n有关模板的其他详细信息，请参考 [Pandoc 模板](http://pandoc.org/MANUAL.html#templates) 上的文档。您还可以研究默认的 HTML 模板 [`default.html5`](https://github.com/jgm/pandoc-templates/) 。\n\n其他类型文档格式控制方式类似，如欲详细了解请 [参考原作](https://bookdown.org/yihui/rmarkdown/documents.html) 。\n\n---\n\n\n",
"attributes": [
{
"value": "r-rmarkdown",
"trait_type": "xlog_slug"
}
]
}
