使用 R

概述

Quarto 是 RStudio 推出的多语言、下一代版本的 R Markdown，具有许多新功能和能力。与 R Markdown 类似，Quarto 使用 Knitr 执行 R 代码，因此能够无需修改地渲染大多数现有的 Rmd 文件。

我们将首先介绍 Quarto 的基础知识，然后深入探讨 Quarto 与 R Markdown 在以下章节中的差异：代码块选项 和 输出格式。

代码块

使用大括号围绕语言名称的代码块（例如 ```{r}）是可执行的，Quarto 在渲染时会运行这些代码块。以下是一个简单的示例：

---
title: "ggplot2 演示"
author: "诺拉·琼斯"
date: "5/22/2021"
format: 
  html:
    code-fold: true
---

## 空气质量

@fig-airquality 进一步探讨了温度对臭氧水平的影响。

```{r}
#| label: fig-airquality
#| fig-cap: "温度和臭氧水平。"
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

你会注意到代码块顶部有一些特殊的注释。这些是单元级别的选项，使得图形可以进行交叉引用。

此文档会生成以下渲染输出：

你可以从可执行的代码块生成多种输出类型，包括图表、数据框的表格输出以及纯文本输出（例如打印统计摘要的结果）。

有许多选项可以控制代码执行和输出的行为，你可以在执行选项一文中了解更多信息。

除了中断 Markdown 流程的代码块外，你还可以包含内联代码。关于内联代码的更多信息，请阅读内联代码一文。

渲染

当渲染 Quarto 文档时，R 代码块会自动执行。你可以通过多种方式渲染 Quarto 文档：

1. 使用 RStudio 中的 Render 按钮：

   

   Render 按钮将渲染文档 YAML 中列出的第一个格式。如果没有指定格式，则将渲染为 HTML。

2. 使用系统 shell 中的 quarto render 命令：

   终端

   quarto render document.qmd # 所有格式
   quarto render document.qmd --to pdf
   quarto render document.qmd --to docx

   请注意，目标文件（在本例中为 document.qmd）应始终是命令行的第一个参数。

   render 命令将渲染文档 YAML 中列出的所有格式。如果没有指定格式，则将渲染为 HTML。你也可以提供 --to 参数以指定特定格式。

3. 使用 quarto R 包从 R 控制台：

   library(quarto)
   quarto_render("document.qmd") # 所有格式
   quarto_render("document.qmd", output_format = "pdf")

   函数 quarto_render() 是 quarto render 的包装器，默认情况下，将渲染文档 YAML 中列出的所有格式。

   请注意，Quarto R 包是从 R 进行命令行渲染的便利工具，使用 Quarto 并不需要它。

安装

要使用 R 与 Quarto，你应该安装 rmarkdown R 包：

install.packages("rmarkdown")

安装 rmarkdown 包时，也会安装 knitr 包，因此你将拥有渲染包含 R 代码的文档所需的一切。

Quarto 将通过查找系统 PATH 来选择 R 的版本。此外，在 Windows 上，如果未在 PATH 上找到 R，则会扫描注册表以获取当前的 R 版本。你可以通过将 QUARTO_R 环境变量设置为包含 R 二进制文件 RScript 的目录来覆盖 Quarto 使用的 R 版本。

RStudio

RStudio v2022.07 及更高版本支持编辑和预览 Quarto 文档（以下文档假设您使用的是此版本或更高版本）。

如果您在 RStudio 中使用 Quarto，强烈建议您使用 最新版本 的 RStudio（v2023.12）。

您可以从 https://posit.co/download/rstudio-desktop/ 下载 RStudio v2023.12。

创建文档

使用 文件 : 新建文件 : Quarto 文档… 命令创建新的 Quarto 文档：

渲染和预览

使用 渲染 按钮在编辑时预览文档：

如果您希望在保存时自动渲染，可以在编辑器工具栏中勾选 保存时渲染 选项。

预览将显示在编辑器旁边：

每当您重新渲染文档时，预览都会更新。并排预览适用于 HTML 和 PDF 输出。

项目

如果您想为 Quarto 文档或一组文档创建一个新项目，请使用 文件 : 新建项目… 命令，指定 新建目录，然后选择 Quarto 项目：

您可以使用此界面创建普通项目以及 网站 和 书籍。还提供了创建 git 仓库并为项目初始化 renv 环境的选项。

VS Code

Quarto 扩展 为 VS Code 提供了一系列工具，用于在 VS Code 中处理 .qmd 文件。该扩展直接与 R 扩展 集成，提供以下特定于 R 的功能：

1. 代码补全
2. 单元格执行
3. 上下文帮助

您可以通过在扩展面板中搜索 ‘quarto’ 或从 扩展市场 安装 VS Code 扩展。

VS Code 扩展包含一个 Quarto: 预览 命令，可以通过命令面板、键盘快捷键 或编辑器中的 预览 按钮（）访问。渲染后，预览将显示在 VS Code 内的窗格中，与您的文档并排显示。

您可以在 工具: VS Code 中阅读更多关于使用 VS Code 的信息。

Emacs

quarto-mode MELPA 包是一个用于编辑 Quarto 文档的 Emacs 模式。按如下方式安装 quarto-mode：

M-x refresh-package-contents
M-x install-package
  quarto-mode

如果您安装了 ESS，quarto-mode 将利用它来执行 R 代码。

使用 M-x quarto-preview 启动一个 quarto preview 服务器，该服务器会监视 quarto 内容的变化并自动刷新。如果当前缓冲区有一个关联的文件存在于 quarto 项目中，该命令将预览整个项目。否则，它将预览特定文件。

代码块选项

R Markdown文档与Quarto文档之间的一个重要区别在于，在Quarto中，代码块选项通常包含在代码块顶部的特殊注释中，而不是在开始代码块的那一行内。例如：

```{r}
#| echo: false
#| fig-cap: "Air Quality"

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Quarto采用这种方法，既可以更好地适应像fig-cap、fig-subcap和fig-alt这样的较长选项，也使得在不具备便捷编辑代码块元数据功能的更结构化的编辑器中（例如大多数传统笔记本用户界面），编辑代码块选项变得简单明了。

Note

请注意，如果你愿意，仍然可以在第一行包含代码块选项（例如```{r, echo = FALSE}）。尽管如此，我们建议使用基于注释的语法，以使文档在不同执行引擎之间更具可移植性和一致性。

以这种方式包含的代码块选项使用YAML语法而不是R语法，以与YAML前置内容中提供的选项保持一致。然而，你仍然可以通过在选项值前加上!expr来使用R代码。例如：

#| fig-cap: !expr 'paste("Air", "Quality")'

Caution

!expr语法是YAML“标签”字面量的一个示例，可能不太直观。!expr后面需要跟随一个_单一的YAML“流标量”_：有关双引号、单引号和无引号字符串的工作原理，请参阅YAML规范。

代码块标签

您可以使用 label 选项为代码块设置标签：

```{r}
#| label: convert
airquality$TempC <- (5 / 9) * (airquality$Temp - 32)
```

除非您想指定交叉引用，否则请避免使用 保留的交叉引用前缀 作为代码块标签。

输出格式

R Markdown 和 Quarto 之间的另一个区别与输出格式有关。Quarto 包含更多内置的输出格式（以及更多用于自定义每种格式的选项）。Quarto 还具有针对 网站、书籍 和 博客 等特殊项目类型的原生功能（而不是依赖外部包）。

要在 Quarto 中使用格式，您使用 format 键而不是 R Markdown 中使用的 output 键。以下是等效格式规范的比较：

R Markdown

title: "我的文档"
output:
  html_document:
    toc: true
    number_sections: true
    css: styles.css

Quarto

title: "我的文档"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css

语法差异的一个来源是 Quarto 更紧密地与 Pandoc 格式名称和选项保持一致（因此使用 - 作为单词分隔符而不是 _）。

查看所有 支持的格式 以及它们的用户指南和参考页面以获取更多详细信息。

有关更高级输出格式的更多详细信息，请参阅关于创建 网站、书籍 和 博客 的文章。

数据框

你可以使用 df-print 文档选项来控制数据框的默认打印方式。可用的选项包括：

选项	描述
default	使用数据框的默认 S3 方法。
kable	使用 knitr::kable() 函数生成 Markdown 表格。
tibble	使用 tibble 包生成纯文本表格。
paged	带有分页功能的 HTML 表格，用于处理行和列的溢出（使用 rmarkdown::paged_table() 实现）。

例如，这里我们指定希望对数据框使用 paged 打印方式：

---
title: "文档"
format: 
   html:
     df-print: paged
---

Knitr 选项

如果你使用的是 Knitr 单元执行引擎，你可以在 YAML 中指定默认的文档级 Knitr 代码块选项。例如：

---
title: "我的文档"
format: html
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true
---

你还可以使用 opts_knit 指定全局 Knitr 选项。

R.options 代码块选项是一种便捷的方式，用于定义通过 options() 临时设置的 R 选项，这些选项在代码块执行前设置，并在执行后立即恢复。

在上面的例子中，我们为单个文档建立了默认的 Knitr 代码块选项。你还可以将共享的 knitr 选项添加到项目范围的 _quarto.yml 文件或项目目录范围的 _metadata.yml 文件中。

缓存

Knitr 缓存 在单个单元格级别而不是整个文档级别运行。虽然这非常方便，但它也在管理单元格之间的依赖关系方面引入了一些特殊要求。

您可以使用标准 YAML 选项在文档或项目级别启用 Knitr 缓存：

---
title: "我的文档"
format: html
execute: 
  cache: true
---

您还可以在每个单元格基础上启用缓存（在这种情况下，您不会设置文档级别选项）：

```{r}
#| cache: true

summary(cars)
```

还有各种其他单元格级选项会影响 Knitr 缓存行为。您可以在 Knitr 单元格选项 参考中了解它们。另一个优秀的资源是 Yihui Xie 关于 缓存失效 的文章。

渲染

你可以使用 quarto render 命令行选项来控制缓存行为，而无需更改文档代码。使用这些选项可以强制所有代码块使用缓存，禁用所有代码块的缓存（即使选项中指定了缓存），或者强制刷新缓存，即使它未失效：

终端

# 使用缓存（即使未在选项中启用）
quarto render example.qmd --cache 

# 不使用缓存（即使选项中启用了缓存）
quarto render example.qmd --no-cache 

# 使用缓存并强制刷新
quarto render example.qmd --cache-refresh 

替代方案

如果你使用缓存来缓解长时间渲染的问题，你应该考虑一些与缓存并行的替代方案。

禁用执行

如果你只处理散文/Markdown，你可能希望完全禁用执行。通过指定 enabled: false 执行选项来实现这一点。例如：

---
title: "我的文档"
format: html
execute: 
  enabled: false
---

请注意，如果你使用 Jupyter .ipynb 笔记本（而不是纯文本 .qmd 文件）进行创作，那么这已经是默认行为：当你调用 quarto render 时不会发生执行（相反，执行会在你使用笔记本时发生）。

冻结执行

如果你在一个项目中工作，并且你主要关心的是同时渲染许多文档的累积影响，请考虑使用 freeze 选项。

你可以使用 freeze 选项来表示在全局项目渲染期间，计算文档不应重新渲染，或者仅在源文件更改时重新渲染：

execute:
  freeze: true  # 在项目渲染期间永不重新渲染

execute:
  freeze: auto  # 仅在源文件更改时重新渲染

请注意，freeze 控制的是在全局项目渲染期间是否执行。如果你对单个文档或项目子目录进行增量渲染，那么代码总是会被执行。例如：

Terminal

# 渲染单个文档（总是执行代码）
quarto render document.qmd

# 渲染项目子目录（总是执行代码）
quarto render articles

在关于 管理项目执行 的文章中了解更多关于使用 freeze 的信息。