教程：计算

概述

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

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

平台 命令
Mac/Linux {.bash filename="终端"} | python3 -m pip install jupyter matplotlib plotly pandas
Windows {.powershell filename="终端"} | 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 preview，然后将您的编辑器与显示预览的浏览器并排放置。

终端
quarto preview computations.qmd

左侧是文本编辑器，右侧是浏览器中的实时预览。

单元格输出

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

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

保存文件后进行此更改。预览将更新以显示没有代码的输出。

computations.qmd 的输出，设置为 'echo: false'，显示标题、NumPy 部分的数组结果、Matplotlib 部分的折线图以及 Plotly 部分的交互式气泡图。

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

```{python}
#| echo: true

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

保存文件并注意，现在 NumPy 单元格的代码已包含在内。

computations.qmd 的渲染 NumPy 部分，显示代码和结果数组。

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

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

代码折叠

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

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

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

渲染后的 computations.qmd 文件中的 NumPy 部分，显示了一个可切换的标记为'代码'的部分以及生成的数组。

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

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

保存文件后，你会在文档的右上角看到一个代码菜单，该菜单提供了全局显示和隐藏代码的控制。

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

图形

让我们改进 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)
```

保存文件以重新渲染并查看更新后的图表：

渲染后的 computations.qmd 文件中的 Matplotlib 部分，包含一个可折叠的代码小部件、图表以及图表下方写着'图 1: 误差条限制选择器'的标题。

多个图形

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)

保存文件后，预览将更新如下：

Plotly 部分的输出，显示了并排的两个图表。第一个图表下方有一个标题，写着'(a) Gapminder: 1957'，第二个图表的标题是'(b) Gapminder 2007'。在两个图表下方，有一个标题写着'图 1: 预期寿命和 GDP（数据来自世界银行，通过 gapminder.org）'。

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

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

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

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

#| layout-ncol: 2

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

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

#| column: page

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

下一步

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

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