写在前面
学习一个软件最好的方法就是啃它的官方文档。本着自己学习、分享他人的态度，分享官方文档的中文教程。软件可能随时更新，建议配合官方文档一起阅读。
1.quarto 教程 1：Hello, Quarto
::: block-1
目录
- 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 文档选项控制默认情况下打印数据框的方式?？捎醚∠畎ǎ?/p>
| 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 打?。?/p>
---
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
<center><strong>结束</center></strong>
本文由mdnice多平台发布
