简介#

术语表#

以下是您在 Bokeh 文档中遇到的最重要的概念和术语

标注#

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

应用程序#

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

BokehJS#

实际呈现视觉效果并处理 Bokeh 绘图 和 小部件 在浏览器中的 UI 交互的 JavaScript 客户端库。在大多数情况下，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 是脚本的名称。

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

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 输出的其他语言。有关更多详细信息和可用绑定，请参阅 为语言绑定做出贡献。