简介#

术语表#

这些是您将在整个 Bokeh 文档中遇到的最重要的概念和术语

注解#

使绘图更易于阅读的视觉辅助工具。例如，这包括标题、图例、标签或带状区域。有关更多信息和示例，请参阅注解中的用户指南。

应用程序#

Bokeh 应用程序是生成 Bokeh 文档的配方。通常，这是由 Bokeh 服务器在每次创建新会话时运行的 Python 代码。

BokehJS#

JavaScript 客户端库，它实际渲染 Bokeh 绘图和 小部件在浏览器中的视觉效果并处理 UI 交互。在大多数情况下，Bokeh 会自动处理与 BokehJS 的所有交互（“我们编写 JavaScript，因此您不必这样做”）。有关更多详细信息，请参阅贡献 BokehJS章节的贡献者指南。

文档#

Bokeh 应用程序的组织数据结构。文档包含在浏览器中渲染交互式可视化或应用程序所需的所有 Bokeh 模型和数据。

嵌入#

各种有助于将 Bokeh 绘图和 小部件包含在 Web 应用程序、网页或 Jupyter 笔记本中的方法。有关更多详细信息，请参阅网页中的用户指南。

字形#

绘制矢量图形以表示数据的 API 对象。字形是 Bokeh 绘图的基本视觉构建块。这包括线条、矩形、正方形、楔形或散点图的圆圈等元素。bokeh.plotting 接口提供了一种围绕字形创建绘图的便捷方法。有关更多信息，请参阅基本绘图中的用户指南。

布局#

Bokeh 对象的集合。这可以是嵌套行和列中排列的多个 绘图和 小部件。有关更多信息和示例，请参阅网格和布局中的用户指南。

模型#

Bokeh 可视化组成的最底层对象。Bokeh 的模型是 bokeh.models 接口的一部分。大多数用户不会使用此级别的接口直接组装绘图。但是，最终所有 Bokeh 绘图都由模型集合组成。了解它们足以配置其属性和特性是很有帮助的。有关更多信息，请参阅外观中的用户指南。

绘图#

包含可视化的所有各种对象（例如 渲染器、字形或 注解）的容器。bokeh.plotting 接口提供了 figure() 函数，以帮助组装所有必要的对象。

渲染器#

用于绘制绘图元素的任何方法或函数的通用术语。由渲染器生成的元素的示例是 字形或 注解。

服务器#

Bokeh 服务器是一个可选组件。您可以使用 Bokeh 服务器来共享和发布 Bokeh 绘图和应用程序，处理大型数据集的流式传输，或启用基于 小部件和选择的复杂用户交互。有关更多信息和示例，请参阅Bokeh 服务器中的用户指南。

小部件#

不直接属于 Bokeh 绘图的用户界面元素，例如滑块、下拉菜单或按钮。您可以在 Python 代码中使用来自小部件的事件和数据，或者可以使用来自小部件的输入来更新您的 Bokeh 绘图本身。您可以在独立的 应用程序或与 Bokeh 服务器一起使用小部件。有关示例和信息，请参阅交互中的用户指南。

输出方法#

Bokeh 提供了多种生成交互式输出的方法。以下两个函数是最常见的

output_file()

为 Bokeh 可视化生成简单的独立 HTML 文档。

output_notebook()

在 Jupyter/Zeppelin 笔记本中显示 Bokeh 可视化。

这些输出函数通常与 show() 或 save() 一起使用。这是一个示例

from bokeh.plotting import figure, output_file, show

output_file("output.html")

p = figure()
p.line(x=[1, 2, 3], y=[4,6,2])

show(p)

此脚本生成一个名为 output.html 的 HTML 文件，其中包含折线图。您可以使用 python foo.py 执行它，其中 foo.py 是脚本的名称。

这些函数在交互式设置中或用于创建要从后端 Web 应用程序提供的独立 Bokeh 文档时通常很有用。

Bokeh 设置#

有各种全局设置会影响 Bokeh 的运行方式。您可以使用多种方法来更改 Bokeh 的配置：直接在 Python 代码中，在 YAML 配置文件中，或使用环境变量等。所有可用设置的完整列表以及如何更改它们，请访问 bokeh.settings。

一些最有用的设置是

browser (环境变量 BOKEH_BROWSER)

将此配置值设置为您希望 Bokeh 使用的浏览器（例如在调用 show() 时）。有效值是 Python webbrowser 模块的任何预定义浏览器名称。例如：chromium-browser 或 windows-default。您也可以将此变量设置为浏览器的完整路径。例如

export BOKEH_BROWSER=/usr/bin/chromium-browser

$Env:BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"

set BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"
resources (环境变量 BOKEH_RESOURCES)

要在浏览器中显示交互式可视化，Bokeh 需要加载 BokehJS。设置此配置值以定义从何处加载 BokehJS。例如

  • cdn 从 Bokeh 的内容分发网络 (CDN) 加载 BokehJS

  • server 从 Bokeh 服务器加载

  • relative 加载相对于给定目录的本地版本。

所有可用选项都列在 Resources 中。

您可以将此变量的一些值与其他配置值组合使用，例如 cdn_version (BOKEH_CDN_VERSION) 和 rootdir (BOKEH_ROOTDIR)。有关详细信息，请参阅 bokeh.settings。

接口#

Bokeh 为数据科学家和领域专家等不希望被软件复杂细节分散注意力的用户提供了简单直观的界面。同时，Bokeh 也迎合了可能需要更多控制或访问更复杂功能（如应用程序开发人员和软件工程师）的人员。

因此，Bokeh 采用分层方法，并为不同的用户提供不同的编程接口。

本节概述了您可以使用的两个接口：主要接口 bokeh.plotting 和低级 bokeh.models 接口。

如果您希望直接跳到基本绘图，请转到 基本绘图。有关使用 Bokeh 创建可视化的简单分步指南，请参阅入门指南。

bokeh.plotting 接口#

bokeh.plotting 是 Bokeh 的主要接口。这种通用接口类似于 Matplotlib 或 Matlab 等库的绘图接口。

bokeh.plotting 接口让您可以专注于将字形与数据关联。它会自动为您组装包含默认元素（例如坐标轴、网格和工具）的绘图。

figure() 函数是 bokeh.plotting 接口的核心。此函数创建一个 figure() 模型，其中包含用于向绘图添加不同类型字形的方法。此函数还负责组合可视化的各种元素，例如坐标轴、网格和工具。

下面是 bokeh.plotting 的示例，以及生成的绘图

from bokeh.plotting import figure, output_file, show

# create a figure object
p = figure(width=300, height=300, tools="pan,reset,save")

# add a Circle renderer to this figure
p.circle([1, 2.5, 3, 2], [2, 3, 1, 1.5], radius=0.3, alpha=0.5)

# specify how to output the plot(s)
output_file("foo.html")

# display the figure
show(p)

调用 figure() 函数是创建基本绘图对象所需的全部操作。要向绘图对象添加数据渲染器，请调用字形方法，例如 figure.circle。您无需担心坐标轴和网格（尽管您可以根据需要配置它们），并且只需列出要添加的工具即可。要在浏览器中显示可视化，在大多数情况下，您只需调用输出函数 show()。

使用 bokeh.plotting 接口，您有更多可能性来创建和自定义可视化。例如

  • 将绘图保存到 HTML 文件而不是显示它

  • 样式化和删除坐标轴、网格、注解和交互元素

  • 添加更多数据渲染器

  • 将多个绘图和小部件排列到布局中

本用户指南的基本绘图部分将引导您完成更多示例和 bokeh.plotting 接口的常见用例。

有关构建 Bokeh 的第一个可视化的易于遵循的指南，请参阅入门指南。

bokeh.models 接口#

使用 Bokeh 的低级 bokeh.models 接口，您可以完全控制 Bokeh 如何创建可视化的所有元素。但是，Bokeh 的低级接口不会帮助您以有意义或正确的方式组装各种元素。完全由您来将它们放在一起。

因此，除非您有需要更精细控制的特殊应用程序，否则您可能需要使用上面描述的 bokeh.plotting 接口。

为了能够使用 bokeh.models 接口，您需要了解 Bokeh 使您能够生成基于浏览器的交互式可视化的基本原理。在幕后，Bokeh 由两个库组成

  • BokehJS，JavaScript 库

    BokehJS 在浏览器中运行。此库处理渲染和用户交互。它采用声明性 JSON 对象的集合作为其输入，并将它们用作关于如何在浏览器中处理可视化各个方面的指令。例如

    • 绘图和小部件

    • 布局和排列

    • 工具和渲染器

    • 绘图坐标轴

    在浏览器中，BokehJS 将这些 JSON 对象转换为 BokehJS 模型，并根据相应的 BokehJS 视图渲染它们。

  • Bokeh，Python 库

    Python 库生成 BokehJS 用于在浏览器中渲染可视化的 JSON 对象。

    在其最低级别，Python 库使用一组 model 类，这些类与 BokehJS 在浏览器中创建的模型集完全镜像。

    这些 Python model 类能够验证其内容和属性，并将自身序列化为 JSON。大多数模型都非常简单，通常仅由几个属性属性组成，而没有方法。您可以通过在创建模型时设置模型的属性，或者稍后通过在模型对象上设置属性值来配置这些属性。

您可以通过 Bokeh 的 bokeh.models 接口访问所有低级 model 对象。

例如，要创建和配置 Rect 字形对象

# configure attributes when initializing a model object
glyph = Rect(x="x", y="y2", w=10, h=20, line_color=None)

# assign values to attributes to an existing model object
glyph.fill_alpha = 0.5
glyph.fill_color = "navy"

通常，您可以以这种方式配置所有 Bokeh 模型。由于所有 Bokeh 接口最终都会生成 Bokeh 模型集合，因此无论使用哪个接口，这都使您可以以相同的方式样式化和配置绘图和小部件。

有关 Bokeh 模型的更多信息，请参阅bokeh.models 中的参考指南。

注意

Python 库允许与其他可以生成适当 JSON 输出的语言绑定。有关更多详细信息和可用的绑定，请参阅贡献语言绑定。