教程：计算

概览

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

如果你想在自己的环境中一步步跟随操作，请下载下面的笔记本：

下载 computations.ipynb

然后，创建一个新的工作目录并将笔记本复制到该目录中。

完成这些步骤后，在终端中切换到此目录，安装笔记本依赖项（如有必要），并打开Jupyter Lab开始使用笔记本。你可以使用下表中的命令进行安装和打开Jupyter Lab。

平台	命令
Mac/Linux	Terminal python3 -m pip install jupyter matplotlib plotly pandas python3 -m jupyter lab computations.ipynb
Windows	Terminal py -m pip install jupyter matplotlib plotly pandas py -m jupyter lab computations.ipynb

我们开始时的笔记本如下所示。请注意，所有单元格尚未执行。

---
title: Quarto Computations
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()
```

接下来，在Jupyter Lab中创建一个新的终端，用于执行Quarto命令。

最后，在终端中运行quarto preview，并将Jupyter Lab与显示预览的浏览器并排显示。

Terminal

quarto preview computations.ipynb

继续运行所有单元格，然后保存笔记本。你会看到预览会立即更新。

单元格输出

笔记本中的所有代码都显示在渲染文档中。然而，对于某些文档，你可能希望隐藏所有代码，只显示输出。让我们在文档的execute选项中指定echo: false，以防止代码被打印出来。

---
title: Quarto Computations
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 计算
execute:
   code-fold: true
jupyter: python3
---

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

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

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

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

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

import matplotlib.pyplot as plt

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

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

执行单元格以查看更新后的图表。 然后，保存笔记本以便更新 Quarto 预览。

多个图表

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

这个单元格有很多变化。 如果你想在本地尝试，请复制并粘贴以下代码到笔记本中。

#| label: fig-gapminder
#| fig-cap: "预期寿命与国内生产总值"
#| 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文档中自定义可执行代码的行为和输出的基础知识。

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