显示Altair图表#

Altair 生成 Vega-Lite 可视化，这需要一个 Javascript 前端来显示图表。 因为笔记本环境将 Python 后端与 Javascript 前端结合在一起， 许多用户发现它们在使用 Altair 时很方便。

Altair 图表可以在 Jupyter Notebook、JupyterLab、Zeppelin 和相关的笔记本环境中开箱即用，只要有网络连接以加载所需的 javascript 库。

Altair也可以与各种启用显示Altair图表的IDE一起使用，并且可以在大多数平台上离线使用，只要启用了适当的前端扩展；详细信息如下。

Altair的渲染框架#

因为不同的显示系统有不同的要求和限制，Altair 提供了一个 API 来在各种 渲染器 之间切换，以调整 Altair 的图表表示。这些可以在 alt.renderers 中的渲染器注册表中选择。最常用的内置渲染器有：

alt.renderers.enable("html")

(默认) 输出图表的HTML表示。HTML渲染器可以在 JupyterLab、Jupyter Notebook、Zeppelin、VSCode-Python 及许多相关的笔记本前端工作，以及Jupyter生态系统工具，如 nbviewer 和 nbconvert HTML输出。 它需要网络连接以加载相关的Javascript库。

alt.renderers.enable("mimetype")

(在Altair 4.0之前的默认值)： 输出一个特定于vega-lite的mimetype，可以被适当的前端扩展解释以显示图表。它还输出图的PNG表示，这对于离线查看图表或在不支持渲染vegaspecs的平台（如GitHub）上查看图表非常有用。它与较新的JupyterLab、nteract和VSCode-Python版本兼容，但不与Jupyter Notebook、以及像nbviewer和nbconvert这样的工具兼容。

alt.renderers.enable("jupyter")

(在版本 5.3 中新增): 使用 JupyterChart 输出图表。此渲染器 与支持第三方 Jupyter 小部件的环境兼容，包括 JupyterLab、Jupyter Notebook、VSCode-Python 和 Colab。 它需要网络连接以加载相关的 Javascript 库。请注意， 尽管此渲染器使用 JupyterChart，但它不提供在 Python 中访问值和选择参数的能力。 要实现此功能，请根据 JupyterChart 文档中的说明显式创建一个 JupyterChart 对象。

alt.renderers.enable("jupyter", offline=True)

(在版本 5.3 中添加): 与上面的 "jupyter" 渲染器相同，但从 vl-convert-python 包加载 JavaScript 依赖项（而不是从在线 CDN），因此不需要互联网连接。

alt.renderers.enable("browser")

(在版本 5.3 中添加): 在外部网页浏览器中显示图表。这个渲染器在使用 Vega-Altair 的本地非 Jupyter 环境中特别有用，比如在 IPython 或 Spyder 中。有关更多信息，请参见 浏览器渲染器。

此外，Altair 包括以下渲染器：

  • "default", "colab", "kaggle", "zeppelin": 与 "html" 相同

  • "jupyterlab", "nteract": 与 "mimetype" 相同

  • "png": 渲染器，负责将图表渲染并转换为 PNG 格式，使用 "image/png" MIME 类型输出。

  • "svg": 渲染器，将图表渲染并转换为SVG图像，使用"image/svg+xml" MIME类型输出。

  • "olli": 一个使用 Olli 为屏幕阅读器用户生成可访问文本结构的渲染器。

  • "json": 输出原始 JSON 图表规范的渲染器，使用 "application/json" MIME 类型。

您可以使用 alt.renderers.names() 返回所有注册的渲染器作为 Python 列表。

其他渲染器可以通过Python的入口点系统由第三方包安装，或者您可以创建自己的渲染器，参见 自定义渲染器。

在JupyterLab中显示#

JupyterLab 1.0及更高版本将与Altair的默认渲染器在具有实时网页连接的情况下工作：无需渲染启用步骤。

可选地，针对 JupyterLab 的离线渲染，您可以使用 mimetype 渲染器：

# Optional in JupyterLab: requires an up-to-date vega labextension.
alt.renderers.enable('mimetype')

并确保您安装了正确版本的vega labextension；对于Altair 4可以使用以下命令进行安装：

$ jupyter labextension install @jupyterlab/vega5-extension

在 JupyterLab 版本 2.0 或更高版本中，此扩展默认安装，不过 JupyterLab 发布中可用的版本通常需要几个月才能跟上新的 Altair 发布。

在Jupyter Notebook中显示#

经典的 Jupyter Notebook 将与 Altair 的默认渲染器一起工作，无需步骤启用渲染：不需要渲染启用步骤。

可选地，对于在Jupyter Notebook中的离线渲染，您可以使用笔记本渲染器：

# Optional in Jupyter Notebook: requires an up-to-date vega nbextension.
alt.renderers.enable('notebook')

这个渲染器由ipyvega笔记本扩展提供，可以通过使用pip进行安装和启用：

$ pip install vega

或conda：

$ conda install vega --channel conda-forge

在旧版本的 notebook (<5.3) 中，你需要额外启用扩展：

$ jupyter nbextension install --sys-prefix --py vega

在nteract中显示#

nteract 无法原生显示 HTML 输出，因此 Altair 的默认 html 渲染器将无法工作。然而，nteract 原生支持基于 mimetype 的 vega 和 vega-lite 渲染。要在 nteract 中使用 Altair，请确保您使用的是支持 Vega-Lite v5 mimetype 的版本，并使用：

alt.renderers.enable('mimetype')

在VSCode中显示#

VSCode-Python 与 Altair 的默认渲染器配合使用，具有实时网络连接：不需要渲染启用步骤。

可选地，对于离线渲染，您可以使用mimetype渲染器：

# Optional in VS Code
alt.renderers.enable('mimetype')

仪表板#

Altair 兼容常见的 Python 仪表板包。它们中的许多甚至提供支持从图表读取 parameters 。这使您能够例如选择数据点并根据该选择更新仪表板的另一部分，例如表格：

包

显示交互式Altair图表

支持读取参数

面板

✔

✔

Plotly Dash

✔

✔

Jupyter Voila 使用 JupyterChart

✔

✔

Marimo

✔

✔

Shiny 使用 JupyterChart

✔

✔

Solara

✔

✔

Streamlit

✔

✔

上述提到的框架都需要您在服务器上运行Web应用程序，如果您想与其他人分享您的工作。Web应用程序为您提供了很多灵活性，例如，您可以根据仪表板中下拉菜单的值从数据库中获取数据。然而，这也带来了一些复杂性。 对于Altair本身提供的交互性足够的用例，您还可以使用生成不需要Web服务器的HTML页面的工具，比如Quarto或Jupyter Book。

如果您使用的是此处未列出的仪表板包，请 在GitHub上提出问题 以便我们可以添加它。

在没有JavaScript前端的环境中工作#

Altair生成的Vega-Lite规范可以在任何Python环境中生成，但当前渲染这些规范需要一个JavaScript引擎。因此，Altair在上述基于浏览器的环境中工作最为顺畅。即便如此，使用下面描述的方法，Altair也可以在非基于浏览器的环境中有效使用。

静态图像渲染器#

“"png"” 和 “"svg"” 渲染器依赖于嵌入在 vl-convert 可选依赖项中的 JavaScript 引擎，从 Vega-Lite 图表规范生成静态图像。这些静态图像随后在基于 IPython 的环境中使用 Mime Renderer Extensions 系统显示。这种方法可用于在 IPython QtConsole 和 Spyder 中内联显示 Altair 图表的静态版本，以及在像 JupyterLab 这样的基于浏览器的环境中。

可以这样启用 "svg" 渲染器：

alt.renderers.enable("svg")

这个 "png" 渲染器像这样启用:

alt.renderers.enable("png")

“png”渲染器支持以下关键字参数配置选项：

  • 可以使用scale_factor参数通过指定的比例因子（默认值1.0）来增加图表大小。

  • 该 ppi 参数控制显示图像的每英寸像素分辨率（默认72）。

示例用法：

alt.renderers.enable("png", scale_factor=2, ppi=144)

浏览器渲染器#

为了支持在非浏览器环境中显示具有交互功能的图表，"browser" 渲染器会自动在系统网页浏览器的标签中打开图表。

可以通过如下方式启用 "browser" 渲染器：

alt.renderers.enable("browser")

浏览器渲染器支持以下关键字参数配置选项：

  • using 参数可以用来指定使用哪个系统 web 浏览器。这个参数可以设置为一个字符串来指示必须使用的单一浏览器（例如 "safari"），或者它可以设置为浏览器名称的列表，这样会使用第一个可用的浏览器。有关支持的浏览器名称的列表，请参阅webbrowser module的文档。如果未指定，则使用系统默认浏览器。

  • 参数 offline 可用于指定 JavaScript 依赖项是从在线 CDN 加载还是与图表规范一起嵌入。当 offline 为 False（默认值）时，JavaScript 依赖项从在线 CDN 加载，因此需要互联网连接。当 offline 为 True 时，JavaScript 依赖项与图表规范一起嵌入，因此不需要互联网连接。将 offline 设置为 True 需要可选的 vl-convert-python 依赖项。

  • port 参数可用于配置图表 HTML 所服务的系统端口。默认为随机开放端口。

限制：

  • 这个 "browser" 渲染器设置了一个临时网络服务器，该服务器只提供一次图表，然后打开指定的浏览器指向该服务器的 URL。这种方法不需要在磁盘上创建临时 HTML 文件，并且在内存上是高效的，因为不需要长期运行的网络服务器进程。这种方法的一个局限性是，如果浏览器被刷新，图表将会丢失，并且无法复制图表 URL 并粘贴到另一个浏览器标签中。

  • 在基于IPython的环境中，"browser"渲染器将在图表为单元格或命令的最终值时自动在浏览器中打开图表。此行为在标准python REPL中不可用。在这种情况下，可以使用chart.show()方法手动调用活动渲染器并在浏览器中打开图表。

  • 此渲染器不兼容远程环境，例如 Binder 或 Colab。

手动 save() 和显示#

如果您愿意，您可以先将图表保存到文件（html、png等），然后再显示它。有关更多信息，请参见 保存 Altair 图表。

故障排除#

Altair 有许多移动部件：它在 Python 中创建数据结构，这些 结构被传递给前端渲染器，渲染器运行 JavaScript 代码以生成输出。这种复杂性意味着可能会出现奇怪的状态，在这些状态下事情并不会如预期那样立即工作。

本节总结了一些最常见的问题及其解决方案。

常规故障排除#

图表根本不显示#

如果您期望输出一个图表但什么都没有看到，这意味着 Javascript 渲染库未被调用。这可能有几个原因：

  1. 您使用的是不支持JavaScript的ECMAScript 6的旧浏览器： 在这种情况下，图表可能无法正确显示或根本不显示。例如，Altair 图表在任何版本的Internet Explorer中都无法渲染。 如果是这种情况，您可能会在浏览器的 Javascript Console中看到语法错误。

  2. 您的浏览器无法加载javascript库。这可能是由于本地防火墙、广告拦截器，或者因为您的浏览器离线。检查您的浏览器的 Javascript Console 以查看是否有错误。

  3. 您可能未能触发笔记本的显示机制（见下文）。

如果您在笔记本环境中工作，图表仅在 单元格的最后一行评估为图表对象时显示

类比一下，考虑简单的Python操作的输出：

>>> x = 4  # no output here
>>> x      # output here, because x is evaluated
4
>>> x * 2  # output here, because the expression is evaluated
8

如果你输入的最后一项是赋值操作，则不会显示任何输出。这对于Altair图表也是成立的：

import altair as alt
from vega_datasets import data
cars = data.cars.url

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N',
)

最后的语句是一个赋值，所以没有输出，图表也没有显示。如果你有一个分配给变量的图表，你需要以对该变量的评估结束单元格：

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N',
)

chart

或者，您可以直接评估一个图表，而不将其分配给变量，在这种情况下，对象定义本身就是最终语句，并将作为输出显示：

alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N',
)

图表显示，但内容为空#

有时图表可能会出现，但内容是空的；例如：

import altair as alt

alt.Chart('nonexistent_file.csv').mark_line().encode(
    x='x:Q',
    y='y:Q',
)

如果情况是这样的，通常意味着以下两种情况之一：

  1. 您的数据由一个无效或无法访问的URL指定

  2. 您的编码与数据源中的列不匹配

在上面的例子中， nonexistent_file.csv 不存在，因此图表未能渲染（相关警告将在 Javascript Console 中可见）。

可能导致这种情况的其他一些特定情况：

You have an adblocker active

引用URL数据的图表有时会在您的浏览器的广告拦截器中触发误报。检查您的浏览器的 Javascript Console 是否有错误，并尝试禁用您的广告拦截器。

You are loading data cross-domain

如果您将图表保存为HTML并使用file://网址在浏览器中打开，大多数浏览器将不允许javascript从http://域加载数据集。这是您浏览器中的一个安全功能，无法禁用。要在本地查看此类图表，一个好的方法是使用一个简单的本地HTTP服务器，如Python提供的服务器：

$ python -m http.server
Your encodings do not match your data

如果您引用了数据中不存在的字段，无论是由于字段名称的拼写错误，还是因为列包含特殊字符（见下文），则会产生类似的空白图表。

这里是一个错误指定字段名称导致空白图表的例子：

import pandas as pd

data = pd.DataFrame({'x': [1, 2, 3],
                     'y': [3, 1, 4]})

alt.Chart(data).mark_point().encode(
    x='x:Q',
    y='y:Q',
    color='color:Q'  # <-- this field does not exist in the data!
  )

Altair不检查字段是否有效，因为在完整的架构中有许多方式可以指定字段，考虑所有边缘情况是非常困难的。改善用户体验是首要任务；参见 vega/vega-lite#3576。

包含特殊字符的编码#

基于Vega-Lite语法的Altair允许编码名称使用特殊字符来访问嵌套属性（参见Vega-Lite的Field文档）。

这可能会导致在使用此类列绘制图表时，Altair 出错。 例如，以下图表是无效的：

import pandas as pd
data = pd.DataFrame({'x.value': [1, 2, 3]})

alt.Chart(data).mark_point().encode(
    x='x.value:Q',
)

要直接绘制这些数据，您必须在字段名称中转义句点：

import pandas as pd
data = pd.DataFrame({'x.value': [1, 2, 3]})

alt.Chart(data).mark_point().encode(
    x=r'x\.value:Q',
)

一般来说，最好在数据源中避免使用特殊字符，如 "."、"[" 和 "]"，如果条件允许的话。

在JupyterLab中排除故障#

VegaLite 4/5 对象#

如果您使用的是 Jupyter notebook 而不是 JupyterLab，那就参考 Notebook: VegaLite 4/5 对象

如果您使用的是 JupyterLab（而不是 Jupyter notebook）并看到一条错误信息提到 VegaLite 4 object 或 VegaLite 5 object，则这意味着您已启用 mimetype 渲染器，但您的 JupyterLab 前端不支持 VegaLite 4 或 5 mimetype。

最简单的解决方案是使用默认渲染器：

alt.renderers.enable('default')

并重新运行包含图表的单元格。

如果您想在JupyterLab中使用mimetype渲染，请使用 pip install -U jupyterlab 或 conda update jupyterlab 将JupyterLab更新到最新版本。

VegaLite 3 对象#

如果您使用的是 Jupyter notebook 而不是 JupyterLab，请参阅 Notebook: VegaLite 3 object

如果您正在使用 JupyterLab（不是 Jupyter notebook）并看到以下输出：

<VegaLite 3 object>

这很可能意味着您正在使用过旧版本的JupyterLab。 Altair 3.0或更高版本与JupyterLab 1.0或更高版本最佳兼容； 通过以下命令检查版本：

$ jupyter lab --version
1.2.0

如果您有较旧的 jupyterlab 版本，那么请使用 pip install -U jupyterlab 或 conda update jupyterlab 来更新 JupyterLab，这取决于您首次安装它的方式。

在JupyterLab中禁用JavaScript输出#

如果您正在使用 JupyterLab 并看到以下输出：

JavaScript output is disabled in JupyterLab

这可能意味着有两件事是错的

  1. 您正在使用旧版本的 Altair。JupyterLab 仅与 Altair 版本 2.0 或更高版本兼容；您可以通过在笔记本代码单元中执行以下命令来检查 altair 版本：

    import altair as alt
alt.__version__

    如果版本低于 2.0，请退出 JupyterLab 并按照 在 JupyterLab 中显示 的安装说明进行操作。

  2. 您启用了错误的渲染器。JupyterLab 使用默认渲染器，但如果您使用 alt.renderers.enable() 启用了其他渲染器，图表将无法在 JupyterLab 中正确渲染。您可以通过运行以下命令检查哪个渲染器处于活动状态：

    import altair as alt
print(alt.renderers.active)

    JupyterLab 渲染仅在活动渲染器为 "default" 或 "jupyterlab" 时有效。您可以通过运行以下命令重新启用默认渲染器：

    import altair as alt
alt.renderers.enable('default')

    （请注意，默认渲染器是默认启用的，因此只有在您在某处显式更改了渲染器的情况下，才需要这样做。）

文本图表表示#

如果你使用的是 Notebook 而不是 JupyterLab，请参考 Notebook: 文本图表表示

如果您正在使用 JupyterLab 并看到类似于以下的 Chart 对象的文本表示：

Chart({
  data: 'https://vega.github.io/vega-datasets/data/cars.json',
  encoding: FacetedEncoding({
    x: X({
      shorthand: 'Horsepower'
    })
  }),
  mark: 'point'
})

这可能意味着您正在使用较旧的Jupyter内核。 您可以通过运行以下命令确认这一点：

import IPython; IPython.__version__
# 6.2.1

如果使用的内核是IPython 4.X或更早版本，Altair将无法正确显示。

解决这个问题最简单的方法是更改你的内核：选择“Kernel”->“Change Kernel”，然后使用第一个出现的内核。

Javascript 错误: require 未定义#

如果您正在使用 JupyterLab 并看到以下错误：

Javascript Error: require is not defined

这可能意味着您启用了笔记本渲染器，而这在 JupyterLab 中不受支持：也就是说，您在某处运行了 alt.renderers.enable('notebook')。 JupyterLab 支持 Altair 的默认渲染器，您可以使用以下方法重新启用：

alt.renderers.enable('default')

笔记本中的故障排除#

笔记本: VegaLite 4/5 对象#

如果你正在使用JupyterLab而不是Jupyter笔记本，请参考 VegaLite 4/5 Object

如果您使用的是 Jupyter Notebook（而不是 JupyterLab）并看到错误信息提到 VegaLite 4 object 或 VegaLite 5 object，那么这意味着您启用了 mimetype 渲染器。最简单的解决方案是使用默认渲染器:

alt.renderers.enable('default')

并重新运行包含图表的单元格。

笔记本: VegaLite 3 对象#

如果您使用的是 JupyterLab 而不是 Jupyter notebook，请参考 VegaLite 3 Object

如果你正在使用这个笔记本（不是JupyterLab）并看到以下输出：

<Vegalite 3 object>

这意味着要么：

  1. 您忘记启用笔记本渲染器。如在 Jupyter Notebook 中显示所述，您需要安装版本 2.0 或更高版本的 vega 包和 Jupyter 扩展，然后使用以下命令启用它：

    import altair as alt
alt.renderers.enable('notebook')

    以便在经典笔记本中渲染图表。

    如果上述代码出现错误：

    NoSuchEntryPoint: No 'notebook' entry point found in group 'altair.vegalite.v2.renderer'

    这意味着您尚未安装 vega 包。如果您看到此错误，请确保遵循在 Jupyter Notebook 中显示的标准安装说明。

  2. 您的Jupyter notebook版本过旧。运行：

    $ jupyter notebook --version

    并确保您拥有5.3或更新的版本。如果没有，则使用 pip install -U jupyter notebook 或 conda update jupyter notebook 更新notebook，具体取决于您最初是如何安装这些包的。

如果您已完成上述步骤但图表仍未渲染，这很可能意味着您在笔记本中使用了不同的 内核。如果您使用的是 Python 2，请切换到名为 Python 2 的内核；如果您使用的是 Python 3，请切换到 Python 3。

笔记本：文本图表表示#

如果您使用的是Notebook而不是JupyterLab，请参考 文本图表表示

如果您没有使用 Jupyter Notebook 环境，请参考 在 Jupyter 之外进行故障排除.

如果您正在使用 Jupyter notebook 并看到类似于此的 Chart 对象的文本表示：

Chart({
  data: 'https://vega.github.io/vega-datasets/data/cars.json',
  encoding: FacetedEncoding({
    x: X({
      shorthand: 'Horsepower'
    })
  }),
  mark: 'point'
})

这可能意味着您正在使用较旧的Jupyter内核。 您可以通过运行以下命令确认这一点：

import IPython; IPython.__version__
# 6.2.1

如果使用的内核是IPython 4.X或更早版本，Altair将无法正确显示。

解决此问题的最简单方法是更改您的内核： 选择“Kernel”->“Change Kernel”，然后根据您在安装Altair时使用的Python版本选择“Python 2”或“Python 3”。

在Jupyter外部的故障排除#

如果您在Jupyter笔记本环境外使用Altair（例如Python或IPython终端），图表将作为文本表示显示。渲染Altair图表需要执行Javascript代码，而您的Python终端无法原生执行。

有关如何在没有 Notebook 环境中使用 Altair 的建议，请参阅 在没有 JavaScript 前端的环境中工作。