教程：计算

概述

Quarto 提供了多种选项来控制代码和计算输出在渲染文档中的显示方式。在本教程中，我们将使用一个包含一些数值输出和图表的 .qmd 文件，并介绍如何应用这些选项。

本教程将使用 matplotlib 和 plotly Python 包。您可以使用下表中的命令来安装它们。

平台	命令
Mac/Linux	终端 python3 -m pip install jupyter matplotlib plotly pandas
Windows	终端 py -m pip install jupyter matplotlib plotly pandas

如果您想在自己的环境中一步步跟随操作，请创建一个 computations.qmd 文件并将以下内容复制到其中。

---
title: Quarto 计算
jupyter: python3
---

## NumPy

```{python}
import numpy as np
a = np.arange(15).reshape(3, 5)
a
```

## Matplotlib

```{python}
import matplotlib.pyplot as plt

fig = plt.figure()
x = np.arange(10)
y = 2.5 * np.sin(x / 20 * np.pi)
yerr = np.linspace(0.05, 0.2, 10)

plt.errorbar(x, y + 3, yerr=yerr, label='both limits (default)')
plt.errorbar(x, y + 2, yerr=yerr, uplims=True, label='uplims=True')
plt.errorbar(x, y + 1, yerr=yerr, uplims=True, lolims=True,
             label='uplims=True, lolims=True')

upperlimits = [True, False] * 5
lowerlimits = [False, True] * 5
plt.errorbar(x, y, yerr=yerr, uplims=upperlimits, lolims=lowerlimits,
             label='subsets of uplims and lolims')

plt.legend(loc='lower right')
plt.show(fig)
```

## Plotly

```{python}
import plotly.express as px
import plotly.io as pio
gapminder = px.data.gapminder()
gapminder2007 = gapminder.query("year == 2007")
fig = px.scatter(gapminder2007, 
                 x="gdpPercap", y="lifeExp", color="continent", 
                 size="pop", size_max=60,
                 hover_name="country")
fig.show()
```

然后，执行 Quarto: 预览 命令。您也可以使用 Ctrl+Shift+K 键盘快捷键，或者点击编辑器右上角的 预览 按钮（）：

请注意，在 Mac 上，您应该使用 Cmd 而不是 Ctrl 作为所有 Quarto 键盘快捷键的前缀。

以下是您在 VS Code 中应该看到的内容：

单元格执行

在编写文档时，您可能希望执行一个或多个单元格而不重新渲染整个文档。您可以使用代码单元格上方的 运行单元格 按钮来执行此操作。点击该按钮以执行单元格（输出将并排显示在 Jupyter 交互控制台中）：

有多种命令和键盘快捷键可用于执行单元格：

Quarto 命令	键盘快捷键
运行当前单元格	⇧⌘ Enter
运行选中的行	⌘ Enter
运行下一个单元格	⌥⌘ N
运行上一个单元格	⌥⌘ P
运行所有单元格	⌥⌘ R
运行上方单元格	⇧⌥⌘ P
运行下方单元格	⇧⌥⌘ N

单元格输出

源文件中的所有代码都显示在渲染文档中。然而，在某些情况下，您可能希望隐藏所有代码并仅显示输出。让我们在文档的 execute 选项中指定 echo: false，以阻止代码打印。

---
title: Quarto 计算
execute:
  echo: false
jupyter: python3
---

重新渲染文档，预览将更新以显示无代码的输出（请记住，在渲染之前不需要保存文件，因为渲染时会自动保存）。

你可能希望有选择地为某些单元格启用代码 echo。为此，请添加 echo: true 单元格选项。尝试在 NumPy 单元格中这样做。

```{python}
#| echo: true

import numpy as np
a = np.arange(15).reshape(3, 5)
a
```

重新渲染，你会注意到 NumPy 单元格的代码现在被包含了。

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

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

代码折叠

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

---
title: Quarto 计算
format:
  html:
    code-fold: true
jupyter: python3
---

渲染文档。现在，每个单元格的输出上方都有一个“代码”小部件。

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

---
title: Quarto 计算
format:
  html:
    code-fold: true
    code-tools: true
jupyter: python3
---

渲染文档，你会看到文档右上角出现了一个代码菜单，提供全局控制显示和隐藏代码的功能。

图表

让我们改进 Matplotlib 输出的外观。它肯定可以更宽，并且为交叉引用提供标题和标签会很好。

继续修改 Matplotlib 单元格，包括 label 和 fig-cap 选项，并调用 fig.set_size_inches() 以设置更大的图表尺寸和更宽的纵横比：

```{python}
#| label: fig-limits
#| fig-cap: "误差条限值选择器"

import matplotlib.pyplot as plt

fig = plt.figure()
fig.set_size_inches(12, 7)
```

重新渲染文档后，你会看到更新后的图表：

多图表

Plotly 单元格可视化了 2007 年的 GDP 和预期寿命数据。让我们在旁边绘制另一年的数据以进行比较，并添加标题和子标题。由于这将生成更宽的可视化效果，我们还将使用 column 选项将其布局在整个页面而不是受限于正文列。

这个单元格有很多变化。如果你想在本地尝试，可以将此代码复制并粘贴到 computations.qmd 中：

#| label: fig-gapminder
#| fig-cap: "预期寿命与人均GDP"
#| fig-subcap:
#|   - "Gapminder: 1957年"
#|   - "Gapminder: 2007年"
#| layout-ncol: 2
#| column: page

import plotly.express as px
import plotly.io as pio
gapminder = px.data.gapminder()
def gapminder_plot(year):
    gapminderYear = gapminder.query("year == " + 
                                    str(year))
    fig = px.scatter(gapminderYear, 
                     x="gdpPercap", y="lifeExp",
                     size="pop", size_max=60,
                     hover_name="country")
    fig.show()
    
gapminder_plot(1957)
gapminder_plot(2007)

渲染文档后，预览将更新如下：

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

#| fig-cap: "预期寿命和GDP"
#| fig-subcap:
#|   - "Gapminder: 1957"
#|   - "Gapminder: 2007"

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

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

#| layout-ncol: 2

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

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

#| column: page

这使得我们的图表显示能够超出常规正文文本列的范围。 请参阅 文章布局 的文档以了解所有可用的布局选项。

下一步

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

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