教程：计算

概述

Quarto 支持在 Markdown 中嵌入可执行代码块。 这使您能够创建完全可重现的文档和报告——生成输出的代码本身就是文档的一部分，并且在每次渲染文档时都会自动重新运行。

在本教程中，我们将向您展示如何在 RStudio 中使用 Quarto 编写完全可重现的计算文档。

如果您想在自己的环境中一步步跟随操作，请下载下面的 Quarto 文档（.qmd），在 RStudio 中打开它，然后点击 渲染（或使用快捷键 ⇧⌘K）。 我们还建议勾选 保存时渲染 选项，以便实时预览您的更改。

下载 computations.qmd

请注意，您需要使用 RStudio v2022.07 或更高版本打开此文档，您可以在此处下载 here。

单元格输出

默认情况下，代码及其输出会在渲染的文档中显示。

RStudio 窗口中 computations.qmd 在可视化编辑器中打开（右侧），渲染后的文档在左侧。文档标题为 Quarto Computations，包含一些文本和代码。渲染后的版本还显示了一个可视化图表。

然而，对于某些文档，您可能希望隐藏所有代码并仅显示输出。 为此，请在 YAML 中的 execute 选项内指定 echo: false。

---
title: "Quarto Computations"
execute:
  echo: false
---

如果您之前勾选了 保存时渲染，只需保存文档即可实时预览此更改。 否则，渲染文档以查看更新后的效果。结果将如下所示。

渲染后的 computations.qmd 文档，标题为 Quarto Computations，包含一些描述性文本和一个图表。代码未显示。

您可能希望有选择地为某些单元格启用代码 echo。 为此，添加 echo: true 单元格选项。 尝试使用标记为 scatterplot 的代码块。

#| label: scatterplot
#| echo: true

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

再次保存文档，并注意 scatterplot 代码块的代码现在已包含在内。

渲染后的 computations.qmd 文档，标题为 Quarto Computations，包含一些描述性文本和一个图表。图表的代码显示，但加载包的代码未显示。

echo 选项可以设置为 true、false 或 fenced。 最后一个选项在编写文档和教学材料时可能特别有用，因为它允许您在代码输出中包含围栏代码分隔符，以强调可执行代码需要该分隔符。 您可以在 Fenced Echo 文档中阅读有关此选项的更多信息。

还有大量其他选项可用于单元格输出，例如 warning 用于显示/隐藏警告（这在显示包加载消息时特别有用），include 作为阻止任何输出（代码或结果）包含在输出中的通用选项，以及 error 用于防止代码执行中的错误中止文档渲染（并在渲染的文档中打印错误）。

有关更多详细信息，请参阅 Knitr 单元格选项 文档。

代码折叠

与其完全隐藏代码，您可能希望将其折叠，并允许读者自行选择查看。 您可以通过 code-fold 选项实现这一点。 移除我们之前添加的 echo 选项，并添加 code-fold HTML 格式选项。

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
---

再次保存文档，并注意每个代码块现在都包含一个新的代码小部件。

RStudio 中 computations.qmd 打开。右侧是可视化编辑器。YAML 定义了标题和格式。标题为 Quarto Computations。格式为 html，code-fold 选项设置为 true。右侧是渲染后的文档版本。标题后跟随一些文本，接着是一个代码小部件，点击后可以展开，随后是更多文本、另一个代码小部件，最后是图表。代码小部件是折叠的，因此在渲染后的文档中代码不可见。

您还可以提供全局控制代码折叠的功能。 尝试将 code-tools: true 添加到 HTML 格式的选项中。

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
    code-tools: true
---

保存文档后，你将看到在渲染文档的右上角出现了一个代码菜单，该菜单提供了全局控制显示和隐藏所有代码的功能。

渲染后的 computations.qmd 文档版本。文档右上角出现了一个新的代码小部件。截图显示该小部件被点击，显示出包含三个选项的下拉菜单：显示所有代码、隐藏所有代码和查看源代码。背景是渲染后的文档。标题后是一些文本，接着是一个可以点击展开的代码小部件，然后是更多的文本、另一个代码小部件，最后是图形。代码小部件是折叠的，因此在渲染后的文档中代码不可见。

代码链接

code-link 选项启用了代码块中函数的超链接，链接到它们的在线文档。 尝试将 code-link: true 添加到 HTML 格式的选项中。

---
title: "Quarto Computations"
format:
  html:
    code-link: true
---

保存文档并观察到函数现在是可以点击的超链接。

渲染后的 computations.qmd 文档版本。文档包含标题（Quarto Computations）、文本、代码块和图形。截图显示代码块中的函数名是可点击的，点击其中一个会将你带到包网站上的文档（图像的前景显示了这一点）。显示的函数是 ggplot2 中的 theme_minimal()。

请注意，代码链接目前仅通过 downlit 包为 knitr 引擎实现。downlit 的一个限制是，如果 code-line-numbers 和/或 code-annotations 也为 true，则无法实现代码链接。

图形

我们可以改进图形的外观和可访问性。 我们可以通过设置 fig-width 和 fig-height 来改变其纵横比，提供 fig-cap，修改其 label 以进行交叉引用，并使用 fig-alt 添加替代文本。

我们将添加以下代码块选项。

#| label: fig-scatterplot
#| fig-cap: "38款流行汽车的城市和高速公路油耗。"
#| fig-alt: "城市与高速公路油耗的散点图，点按气缸数着色。图中显示了城市和高速公路油耗之间呈正向、线性且强烈的关联，油耗随着气缸数的减少而增加。"
#| fig-width: 6
#| fig-height: 3.5

保存文档以查看更新后的图形。 请注意，我们还通过以下方式使用交叉引用更新了叙述以引用此图形。

@fig-scatterplot 显示了这些汽车的城市和高速公路油耗之间呈正向、强烈且线性的关系。

打开 computations.qmd 的 RStudio。右侧是可视化编辑器。YAML 定义了标题和格式。标题是 Quarto Computations。格式是 html，code-fold 选项设置为 true。与页面上的早期图像相比，代码块显示了添加到代码块的新代码块选项。右侧是文档的渲染版本。标题后是一些文本，接着是一个可以点击展开的代码小部件，然后是更多的文本、另一个代码小部件，最后是图形。代码小部件是折叠的，因此在渲染后的文档中代码不可见。

多个图形

让我们在代码块中添加另一个图形——一个按发动机排量着色的散点图，使用不同的颜色比例。 我们的目标是并排显示这些图形（即，在两列中），并为每个图形提供描述性子标题。 由于这将生成一个更宽的可视化效果，我们还将使用 column 选项将其布局在整个页面而不是仅限于正文文本列。

此代码块中有相当多的更改。 要跟随操作，请将下面列出的选项复制并粘贴到你的 Quarto 文档中。

#| label: fig-mpg
#| fig-cap: "38款流行汽车的城市和高速公路油耗。"
#| fig-subcap:
#|   - "按气缸数着色"
#|   - "按发动机排量（升）着色"
#| layout-ncol: 2
#| column: page

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

ggplot(mpg, aes(x = hwy, y = cty, color = displ)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c(option = "E") +
  theme_minimal()

此外，用以下内容替换描述可视化的现有文本。

@fig-mpg中的图表展示了38种流行车型的城市和高速公路里程之间的关系。
在@fig-mpg-1中，点的颜色由气缸数量决定，而在@fig-mpg-2中，点的颜色由发动机排量决定。

然后，保存文档并检查渲染后的输出，它应该如下所示。

渲染后的computations.qmd文档的新图表。文档包含标题（Quarto计算）、文本、代码块，并且图表包含两个并排的子图表，每个都是散点图。文本显示可点击的交叉引用链接至图1、图1a和图1b。

让我们讨论一下这里使用的一些新选项。 你之前见过fig-cap，但我们现在添加了一个fig-subcap选项。

#| fig-cap: "38种流行车型的城市和高速公路里程。"
#| fig-subcap:
#|   - "按气缸数量着色"
#|   - "按发动机排量（升）着色"

对于具有多个输出的代码单元格，添加fig-subcap选项使我们能够将它们视为子图表。

我们还添加了一个选项来控制多个图表的布局——在这种情况下，我们指定了两列并排。

#| layout-ncol: 2

如果你在一个面板中有3、4或更多图表，有许多选项可用于自定义它们的布局。详情请参阅图表布局文章。

最后，我们添加了一个选项来控制我们的图表所占页面宽度的跨度。

#| column: page

这使得我们的图表显示能够超出正常的正文文本列。有关所有可用布局选项的更多信息，请参阅文章布局文档。

数据框

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

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

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

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

内联代码

要在markdown中包含可执行表达式，请将表达式括在`{r} `中1。 例如，我们可以使用内联代码来声明数据中的观察次数。尝试将以下markdown文本添加到你的Quarto文档中。

我们的数据中有`{r} nrow(mpg)`个观察值。

保存你的文档并检查渲染后的输出。反引号内的表达式已被执行，句子中包含了实际的观察次数。

我们的数据中有234个观察值。

如果你要内联的表达式更复杂，涉及多个函数或管道，我们建议将其包含在一个代码块中（使用echo: false）并将结果分配给一个对象。然后，你可以在内联代码中调用该对象。

例如，假设你想声明数据中汽车的平均城市和高速公路里程。首先，在代码块中计算这些值。

#| echo: false

mean_cty <- round(mean(mpg$cty), 2)
mean_hwy <- round(mean(mpg$hwy), 2)

然后，将以下markdown文本添加到你的Quarto文档中。


我们数据中汽车的平均城市里程是`r mean_cty`，平均高速公路里程是`r mean_hwy`。

保存你的文档并检查渲染后的输出。

我们数据中汽车的平均城市里程是16.86，平均高速公路里程是23.44。

缓存

如果你的文档包含计算时间过长的代码块，你可能希望缓存这些块的结果。你可以使用cache选项，要么在文档级别使用YAML执行选项。

execute:
  cache: true

然而，缓存文档中的所有代码块可能不是首选。你也可以直接使用块选项来指示哪些块应该被缓存。

#| cache: true

尝试将此块选项添加到文档中生成图表的代码块之一并保存。当文档被渲染时，你会在工作目录中看到一个新文件夹，其名称与你的文档相同，后缀为_cache。该文件夹包含缓存的结果。你可以在缓存文档中了解更多关于Quarto文档中缓存的信息。

如果你按照本教程一步一步操作，你现在应该有一个实现了我们涵盖的所有内容的Quarto文档。否则，你可以下载下面的computations.qmd的完整版本。

下载computations-complete.qmd

下一步

您现在已经了解了在Quarto文档中自定义可执行代码的行为和输出的基础知识。

接下来，请查看创作教程，以了解更多关于输出格式和技术写作功能，如引用、交叉引用和高级布局。

Footnotes

  1. Quarto还支持Knitr语法`r `，更多信息请参阅内联代码↩︎