quarto 教程 2：Computations

「写在前面」

学习一个软件最好的方法就是啃它的官方文档。本着自己学习、分享他人的态度，分享官方文档的中文教程。软件可能随时更新，建议配合官方文档一起阅读。
1.quarto 教程 1：Hello, Quarto

---

目录

• 1 概述
• 2 单元输出
• 3 代码折叠
• 4 代码链接
• 5 图
• 6 多个图
• 7 数据框
• 8 行内代码
• 9 缓存

官网教程：https://quarto.org/docs/get-started/computations/rstudio.html

1 概述

Quarto 支持 Markdown 中的可执行代码块。这使您可以创建完全可重现的文档和报告 - 生成输出所需的代码是文档本身的一部分，并且每当呈现文档时都会自动重新运行。

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

如果您想在自己的环境中逐步进行操作，请下载下面的 Quarto 文档 (.qmd)，在 RStudio 中打开它，然后单击「Render」（或使用键盘快捷键 ⇧⌘K）。我们建议还选中“Render on Save”框，以实时预览您的更改。

Download computations.qmd: https://quarto.org/docs/get-started/computations/_computations.qmd

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

2 单元输出

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

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

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

如果您之前选中了 「Render on Save」，则只需在进行此更改后保存文档即可进行实时预览。否则渲染文档以查看反映的更新。结果如下所示。

您可能希望有选择地为某些单元启用代码 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 代码块中。

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

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

有关更多详细信息，请参阅 Knitr Cell Options 文档。

3 代码折叠

您可能希望折叠代码并允许读者自行查看，而不是完全隐藏代码。您可以通过 code-fold 选项来完成此操作。删除我们之前添加的 echo 选项并添加 code-fold HTML 格式选项。

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

再次保存文档，请注意，现在每个代码块都包含新的 Code widgets。

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

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

保存文档，您将看到渲染文档的右上角出现一个代码菜单，它提供对显示和隐藏所有代码的全局控制。

4 代码链接

code-link 选项可以将代码块内的函数超链接到其在线文档。尝试将 code-link: true 添加到 HTML 格式选项。

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

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

请注意，目前代码链接仅通过 downlit 包针对 knit 引擎实现。如果 code-line-numbers 和/或 code-annotations 也为 true，则 downlit 限制会阻止当前的代码链接。

5 图

我们可以改善绘图的外观和可访问性。我们可以通过设置 fig-width 和 fig-height 来改变它的宽高比，提供 fig-cap，修改它的 label 以进行交叉引用，并使用 fig-alt 添加 alternative text。

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

#| label: fig-scatterplot
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-alt: "Scatterplot of city vs. highway mileage for cars, where points are colored by the number of cylinders. The plot displays a positive, linear, and strong relationship between city and highway mileage, and mileage increases as the number of cylinders decreases."
#| fig-width: 6
#| fig-height: 3.5

保存文档以查看更新后的绘图。请注意，我们还使用以下内容更新了对该图的 cross reference 的叙述。

@fig-scatterplot shows a positive, strong, and linear relationship between the city and highway mileage of these cars.

6 多个图

让我们向代码块中添加另一个图 -- 一个散点图，其中的点使用不同的 color scale 根据 engine displacement 进行着色。我们的目标是并排显示这些图（即，在两列中），并为每个图添加描述性小标题。由于这将产生更广泛的可视化效果，我们还将使用 column 选项将其布局在整个页面上，而不是局限于正文文本列。

这个代码块有很多变化。要继续操作，请将下面列出的选项复制并粘贴到您的 Quarto 文档中。

#| label: fig-mpg
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Color by number of cylinders"
#|   - "Color by engine displacement, in liters"
#| 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()

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

The plots in @fig-mpg show the relationship between city and highway mileage for 38 popular models of cars.
In @fig-mpg-1 the points are colored by the number of cylinders while in @fig-mpg-2 the points are colored by engine displacement.

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

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

#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Color by number of cylinders"
#|   - "Color by engine displacement, in liters"

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

我们还添加了一个选项来控制多个图形的布局方式 -- 在本例中，我们在两列中并排指定。

#| layout-ncol: 2

如果面板中有 3 个、4 个或更多图形，则有许多选项可用于自定义其布局。有关详细信息，请参阅文章 Figure Layout。

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

#| column: page

这使得我们的图形显示可以超出正常的正文文本列。请参阅 Article Layout 文档，了解所有可用的布局选项。

7 数据框

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

Option	Description
default	Use the default S3 method for the data frame.
kable	Markdown table using the knitr::kable() function.
tibble	Plain text table using the tibble package.
paged	HTML table with paging for row and column overflow (implemented using rmarkdown::paged_table())

例如，这里我们指定要对数据框进行 paged 打印：

---
title: "Document"
format: 
   html:
     df-print: paged
---

8 行内代码

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

There are `r nrow(mpg)` observations in our data. 

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

There are 234 observations in our data.

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

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

#| echo: false

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

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

The average city mileage of the cars in our data is `r mean_cty` and the average highway mileage is `r mean_hwy`. 

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

The average city mileage of the cars in our data is 16.86 and the average highway mileage is 23.44.

9 缓存

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

execute:
  cache: true

然而，缓存文档中的所有代码块可能并不可取。您还可以使用代码块选项来指示应直接缓存哪些代码块。

#| cache: true

尝试将此代码块选项添加到文档中生成绘图并保存的代码块之一。渲染文档时，您将看到工作目录中已创建一个新文件夹，其名称与文档相同，后缀为 _cache。该文件夹包含缓存的结果。您可以在 Cache 文档中找到有关 Quarto 文档中缓存的更多信息。

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

Download computations-complete.qmd: https://quarto.org/docs/get-started/computations/_computations-complete.qmd

「结束」

本文由 mdnice 多平台发布