跳至主要内容

R Markdown 初学者教程

了解什么是 R Markdown、它的用途、如何安装、它在处理代码、文本和图表方面提供哪些能力、使用何种语法、支持哪些输出格式，以及如何渲染和发布 R Markdown 文档。
· 12分钟 阅读

使用 AI 探索

本文将带您了解每位 R 用户都应掌握的一款重要且实用的数据科学包——R Markdown。我们将学习什么是 R Markdown、它能带来哪些好处、用途是什么、如何安装、它在处理代码、叙述文本和数据图表方面提供了哪些能力、使用何种语法、R Markdown 文档支持哪些输出格式，以及如何渲染此类文档并与协作者分享。

由于 R Markdown 尤其适配 RStudio 集成开发环境（IDE），本文将全程在该 IDE 中演示。RStudio 教程提供了如何安装并开始使用 RStudio 的必要指南。

让我们开始吧！

什么是 R Markdown？

R Markdown 是一个免费、开源的 R 包，为创建数据科学项目提供工作空间。其主要优势在于，您可以在一个精炼、可分享且完全可复现的文档中，将代码、文本和数据可视化组合在一起，并可渲染为多种静态或交互式的输出格式。

其常见输出格式包括 HTML、PDF、Microsoft Word、演示文稿、应用、网站、仪表板、报告、模板、文章、书籍等。

此外，R Markdown 便于版本控制跟踪，并且在 R 之外还支持多种编程语言，包括 Python 和 SQL。

如果您想深入学习如何使用 R Markdown 撰写动态报告，可以从课程 Reporting with R Markdown 入手。

安装 R Markdown

在 RStudio 之外使用 R Markdown 时，我们像安装其他任何来自 CRAN（Comprehensive R Archive Network）仓库的 R 包一样进行安装：

install.packages("rmarkdown")

安装完成后，需要在当前 R 工作环境中加载该包：

library(rmarkdown)

而在 RStudio 内使用 R Markdown（本教程全程采用此方式）时，无需显式安装并加载 rmarkdown 包。只需在 RStudio 菜单栏中点击 File—New File—R Markdown，即可打开一个新的 R Markdown 文档。此时可能会收到 Install Required Packages 的通知，如下所示：

image11.png

确认安装所需包后，会弹出一个新窗口，我们在其中填写文档标题与作者姓名（均为可选但推荐），其余设置保持默认，点击 OK：

image6.png

默认 R Markdown 文档

在上一节中，我们在 RStudio 中打开了一个新的 R Markdown 文档。它看起来如下：

image16.png

可以看到，它包含我们在弹窗中提供的标题、作者姓名、当前日期以及默认输出格式。随后，还包含一些 R Markdown 基本语法示例，如添加并格式化代码块、添加标题、插入链接、强调文本以及生成图表等。

接下来我们将更细致地查看 R Markdown 的多种功能及其语法。现在，先将该默认文件保存，然后渲染为所选输出格式（此处为 HTML），看看最终效果。

要保存文件，请在 RStudio 菜单栏中点击 File—Save As...。

注意：我们之前填写的 R Markdown 文档名称并不等同于文件名。需要将文件保存到项目目录，并在后续编辑时不时保存（File—Save）。

要将已保存的文件渲染为所选输出格式（HTML），请点击文件工具栏中的 Knit：

image8.png

以下是默认 R Markdown 文档渲染为 HTML 格式后的效果：

image3.png

R Markdown 中的文本格式

在数据科学项目中，文本通常占据很大比重。因此，了解如何在 R Markdown 中进行文本格式设置，使其易读、高效且有吸引力，尤为重要。

如果您希望学习如何使用 R 进行数据分析与数据科学，并同时提升 R 编程与数据科学技能，建议从以下对初学者友好的完整职业路径开始：

标题

我们可以使用井号（#）为 R Markdown 文档添加不同级别的标题。语法如下：

# 标题 1（主标题）

## 标题 2（章节）

### 标题 3（小节）

等等。

渲染后，上述标题将显示为：

image20.png

 

 

 

 

 

文本强调

R Markdown 允许为文本添加不同类型的强调效果，例如斜体、粗体、删除线、上标或下标，如下所示：

  • *italic* 或 _italic_
  • **bold** 或 __bold__
  • ~~strikethrough~~
  • text^superscript^
  • text~subscript~

下图展示了这些强调样式渲染后的效果：

image19.png

列表

创建无序列表可使用以下三种语法之一：

* Item 1* Item 2* Item 3

或：

- Item 1- Item 2- Item 3

或：

+ Item 1+ Item 2+ Item 3

无论哪种方式，渲染结果相同：

image10.png

创建有序列表，使用以下语法：

1. Item 12. Item 23. Item 3

渲染结果基本相同，只是在每个数字前增加缩进。

请注意，如果删除或新增某一项，或数字有误（例如上述示例将 2. 误写为 20.），编号会自动更正并按预期显示：

image14.png

块引用

块引用使用 > 符号置于被引用文本首字符前：

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.

渲染后如下所示：

image12.png

在引用块后添加一个空行以结束引用。

链接

如果要以内联形式直接包含链接，需要将链接路径置于 < 和 > 符号之间。比如，下面的写法：

<https://www.google.com/>

将被渲染为：

https://www.google.com/

若要将链接锚定到某个词或短句，使用以下语法（仍以 Google 为例）：

[Google](https://www.google.com/)

渲染后为：

Google

插入图片

要在叙述中插入图片，可采用以下方式之一：

  1. 如果要添加来自互联网的图片：

![Alt_text](image_url)

  1. 如果图片文件保存在与 R Markdown 文档相同的项目文件夹中：

![Alt_text](image_file_name.extension)

  1. 如果图片文件保存在本机但不在项目文件夹内：

![Alt_text](image_file_full_path)

Alt 文本用于简要描述图片内容，并在用户因各种原因无法看到图片时发挥作用。

以下使用第一种方式插入一张 Pixabay 图片，其图片 URL 为 https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg：

![Network](https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg)

渲染文档后，图片将显示如下：

image5.png

断行与分隔

R Markdown 中有多种断行/分隔方式：

  1. 换行（Line break）——开始新的一行。通过在上一行末尾加反斜杠（\）实现。
  2. 段落分隔（Paragraph break）——开始新段落。通过在上一段末尾添加两个空格实现。
  3. 幻灯片分隔（Slide break）——在基于幻灯片的输出格式（演示文稿）中开始新幻灯片，或在其他格式中开始新章节。通过在文档中插入水平线（***）实现。
  4. 分页（Page break）——在适用的输出格式中（如 Microsoft Word）开始新页面。通过在文档中插入 \newpage 命令实现。

让我们将前三种分隔方式应用到文本中。下面是一段添加了部分 R Markdown 分隔符号的 Lorem ipsum 文本：

Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

***

Ut aliquet tristique nisl vitae volutpat.

以下为其在 HTML 文档中的渲染效果：

Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

Ut aliquet tristique nisl vitae volutpat.

R Markdown 中的代码格式与执行

代码是任意数据科学项目的另一核心组成部分。在 R Markdown 中，我们可以运行代码（不仅限于 R），可以同时显示代码与其输出、只显示代码隐藏输出、只显示输出隐藏源码等。

面向初学者的职业路径 R Programmer 与技能路径 R Programming 将有助于您学习、练习并精进 R 编码技能。

代码块

要在 R Markdown 中格式化并运行一段 R 代码，需要将其置于一对三反引号中，且首个三反引号后用花括号标注 r。例如：

```{r}
print("Hello, World!")
```

如果在未运行代码的情况下渲染文档，代码块将显示如下：

image9.png

代码语言

在 R Markdown 中，我们并不局限于使用 R，因为它还支持多种其他编程语言。要运行其他语言的代码，只需在花括号中将语言名替换为相应语言。此外，可能需要在当前 R 环境中安装并加载一些附加包。

例如，要在 R Markdown 中使用 Python，需要安装并加载 reticulate 包，它允许在同一 R Markdown 文档中实现 Python 与 R 的双向通信（如创建和访问变量）。

让我们将上一节的代码示例改写为 Python（在安装并加载 reticulate 包之后）：

```{python}
print("Hello, World!")
```

image9.png

执行代码块

在 RStudio 中使用 R Markdown 时，要执行某个代码块或其选中行，可点击文档工具栏中的 Run 按钮，并在下拉列表中选择相应选项：

image21.png

如上图所示，每个运行选项都对应一个快捷键，可直接使用以免每次都打开下拉列表。

代码块命名

虽然不是强制，但为代码块命名是个好习惯。在许多情况下都很有用：在文档中引用代码块、调试代码、在代码块间切换等。如果文档较长且包含大量代码块，命名尤其重要。

我们在语言名之后的花括号中添加代码块名称，并以空格分隔。代码块名称不能包含空格。

在下面的示例中，我们为代码块添加了名称 hello_world：

```{r hello_world}
print("Hello, World!")
```

代码块选项

代码块选项允许我们分别针对每个代码块，控制代码求值、输出、装饰、缓存、动画（若适用）以及图形（若适用）。同一代码块可添加多个选项。语法上，将选项置于花括号中、紧随代码块名称之后（若无名称则紧随语言名），并用逗号与名称及其他选项分隔。

R Markdown 提供了许多代码块选项。每个选项都有默认值，但当我们选择使用它们时，往往希望设置为非默认值。以下是最常用的一些选项及其可能对我们有用的取值：

  • echo=FALSE——最终文档中不显示代码本身，只显示其输出。
  • eval=FALSE——不运行该代码块中的代码。
  • include=FALSE——运行代码块，但不在最终文档中包含其任何内容。
  • results——默认值为 "markup"；其他取值包括：
    • "hide"——在最终文档中隐藏代码输出
    • "hold"——延迟显示代码输出，待整个代码块执行完毕后一次性展示
    • "asis"——按原样传递代码输出，不做重新格式化。
  • message=FALSE——不显示代码产生的信息。
  • error=FALSE——不显示代码产生的错误。
  • warning=FALSE——不显示代码产生的警告。
  • highlight=FALSE——在最终文档中不对代码进行高亮。
  • prompt=TRUE——在最终文档中每行代码前添加 > 符号。

下面是一些代码块的示例，它们先在 RStudio 中的 R Markdown 中运行，然后在最终文档中渲染：

R Markdown 中的代码：

image15.png

最终文档中的输出：

image17.png

行内代码

通过行内代码，我们可以将简短的代码片段直接插入到 R Markdown 文档的正文中——它们会被执行，其输出将嵌入文本显示。行内代码的语法为 r <code>。

下面是包含行内代码的简单示例：

There are `r 1+6` colors of the rainbow.

以及在最终文档中的渲染效果：

There are 7 colors of the rainbow.

在实践中，行内代码常用于聚合数据相关信息，避免手动插入数字或数据变化时容易出现的错误。

在 R Markdown 中绘图

在 R Markdown 中绘图意味着运行会生成图形的代码。因此，除行内代码外，前文关于代码格式与执行的所有内容同样适用于绘图。主要区别在于，此类代码的输出是图形，而非仅是文本和数字。

技能路径 Data Visualization with R 将帮助您培养在 R 中分析与绘制数据的能力，从而讲述更出色的数据驱动故事。

在 R Markdown 中自定义图形时，与在常规 R 环境中一样，我们使用 R 数据可视化包的工具，以及 base R 的 plot() 函数。

此外，为控制 R Markdown 文档中的绘图行为，可以使用仅与绘图相关的代码块选项。其中大多数较为具体，超出本“快速上手”教程范围。我们先了解一些在 R Markdown 中绘图时常用的基础选项：

  • fig.show——默认值为 "asis"；其他取值包括：
    • "hide"——生成图形但不在最终文档中包含
    • "hold"——延迟显示图形，待整个代码块执行完后一次性展示
    • "animate"——将该代码块生成的所有图形合成为动画。
  • fig.width——图形宽度（英寸），默认 7。
  • fig.height——图形高度（英寸），默认 7。
  • fig.align——在最终文档中的图形对齐方式，可为 "left"、"center" 或 "right"。
  • fig.cap——图形标题（字符串）。
  • fig.path——由该代码块生成的图形文件的存储目录路径。
  • fig.ext——由该代码块生成的图形文件扩展名。

下面展示在 R Markdown 中使用与绘图相关的代码块选项的示例，包括源码与渲染后的输出：

R Markdown 中的代码：

image1.png

最终文档中的输出：

image4.png

输出格式

到目前为止，我们只考虑了 HTML 文档（html_document）这一种最终文档的输出格式。然而，R Markdown 还提供许多其他输出格式，包括 Microsoft Word、Microsoft PowerPoint、PDF、交互式 R 笔记本、仪表板等。

例如，用于创建文档的 R Markdown 输出格式包括 html_document、pdf_document、word_document、github_document、html_notebook、html_vignette 等。而用于创建演示文稿的输出格式包括：powerpoint_presentation、ioslides_presentation、slidy_presentation 和 beamer_presentation。

要为 R Markdown 文档设置输出格式，需要在文档头部（又称 YAML 头，YAML 为“yet another markup language”的缩写）中的 output 设置里指定相应的取值。例如，在我们当前的 R Markdown 文档中，输出格式设置为 html_document，这也是 R Markdown 的默认输出格式：

image2.png

要更改它，只需将 html_document 替换为所需输出格式（如 pdf_document、word_document、powerpoint_presentation 等）。此后，当我们点击文件工具栏中的 Knit 时，文档将以所选输出格式进行渲染。

发布 R Markdown 文档

要发布 R Markdown 文档，请在 RStudio 菜单栏中点击 File—Publish，并选择要发布到的位置：

image18.png

然后根据所选位置的进一步指引操作，最后点击 Publish。现在，文档即可与协作者共享。

结语

总而言之，本文介绍了如何开始使用 R Markdown。我们先定义了 R Markdown 是什么以及它的用途，随后讨论了如何安装 R Markdown、如何设置文本及其各组成部分的格式、如何格式化并运行代码、如何生成图表、R Markdown 提供哪些输出格式、如何将工作文档渲染为其中一种格式，以及如何发布最终文档以与同事分享。

若想通过实践进一步掌握 R Markdown，请查看我们的 Reporting with R Markdown 课程，帮助您从数据中发掘洞见，并将结果撰写为 PDF、HTML 文件或 Shiny 应用。

主题

R