Jupyter#

在笔记本中工作#

Jupyter 笔记本是可计算的文档，通常用于探索性工作、数据分析、教学和演示。笔记本是一系列输入单元格，它们可以单独执行以立即显示其输出。除了经典笔记本之外，还有针对较新的JupyterLab 项目的笔记本。Bokeh 可以将独立和 Bokeh 服务器内容都嵌入到两者中。

独立输出#

独立的 Bokeh 内容不需要 Bokeh 服务器，可以直接嵌入到经典 Jupyter 笔记本以及 JupyterLab 中。

经典笔记本#

要在经典 Jupyter 笔记本中内联显示 Bokeh 图表，请使用 output_notebook() 函数，而不是（或除了）output_file() 函数。不需要其他修改。当您调用 show() 时，图表将在下一个笔记本输出单元格中内联显示。请参见下方 Jupyter 的屏幕截图

Screenshot of a Jupyter notebook displaying a Bokeh scatterplot inline after calling show().

要让单个笔记本输出单元格显示多个图表，请在输入单元格中多次调用 show()。图表将按顺序显示。

Screenshot of a Jupyter notebook displaying multiple Bokeh scatterplots inline after calling show() multiple times.

JupyterLab#

要将 JupyterLab 与 Bokeh 一起使用，您至少应使用 3.0 版的 JupyterLab。在 JupyterLab 中启用 Bokeh 可视化还需要安装 jupyter_bokeh 扩展。

安装 JupyterLab 后，可以使用 pip 或 conda 安装 jupyter_bokeh

使用 conda 安装

确保您已安装了 Anaconda 或 Miniconda。使用以下命令安装 jupyter_bokeh

conda install jupyter_bokeh

使用 pip 安装

使用以下命令安装 jupyter_bokeh

pip install jupyter_bokeh

有关使用旧于 3.0 版的 JupyterLab 版本安装 jupyter_bokeh 的说明，请参阅 README，该文件位于 jupyter_bokeh 的 GitHub 存储库中。

安装 jupyter_bokeh 后，就可以像使用经典笔记本一样使用 Bokeh。

Screenshot of Jupyterlab with a Bokeh ridgeplot displayed inline.

Bokeh 服务器应用程序#

您还可以嵌入完整的 Bokeh 服务器应用程序，将绘图事件和 Bokeh 的内置小部件直接连接到 Python 回调代码。有关 Bokeh 服务器应用程序的常规信息，请参见 Bokeh 服务器。有关在 Jupyter 笔记本中嵌入的 Bokeh 应用程序的完整示例，请参阅以下笔记本

examples/server/api/notebook_embed.ipynb

JupyterHub#

在从自己的 JupyterHub 实例运行笔记本时，需要采取一些额外步骤才能嵌入 Bokeh 服务器应用程序，并启用客户端浏览器与在 JupyterLab 单元格中运行的 Bokeh 服务器之间的网络连接。这是因为您的浏览器需要连接到 Bokeh 服务器正在监听的端口。但是，JupyterHub 充当浏览器和 JupyterLab 容器之间的反向代理。

Bokeh 通过提供 notebook_url 参数来解决此问题，该参数可以传递一个可调用对象来根据整数端口计算最终 URL。此外，如果 JupyterHub 管理员定义了环境变量 JUPYTER_BOKEH_EXTERNAL_URL，则定义 notebook_url 的过程将完全自动化，并且不再需要指定 notebook_url。这具有以下优点：同一个笔记本可以在 JupyterHub 和独立的 JupyterLab 会话中无修改地运行。

所需依赖项#

按照上述所有 JupyterLab（不是 JupyterHub）说明操作，然后通过安装 jupyter-server-proxy 包并启用服务器扩展来继续操作

pip install jupyter-server-proxy && jupyter server extension enable --py jupyter-server-proxy

如果您打算使用 JupyterLab，则需要安装相应的扩展，可以通过 GUI 或使用以下命令进行安装

jupyter labextension install @jupyterlab/server-proxy

面向管理员的 JupyterHub#

如果您是 JupyterHub 管理员，则可以通过在笔记本环境中设置环境变量来使 Bokeh 自动使用未修改的笔记本

export JUPYTER_BOKEH_EXTERNAL_URL="https//our-hub.science.edu"

这通常在 JupyterHub Helm 图表配置 YAML 中完成，如下所示

hub:
  single_user:
    extraEnv:
      JUPYTER_BOKEH_EXTERNAL_URL="https://our-public-hub-name.edu"

上述操作的最终效果是，Bokeh 会自动使用下一节中的技术，不需要采取任何额外操作。

面向用户的 JupyterHub#

对于未设置 JUPYTER_BOKEH_EXTERNAL_URL 的 Hub，请定义一个函数来帮助创建浏览器连接到 Bokeh 服务器的 URL。有关参考实现，请参见下方。您必须修改此代码或将 JupyterHub 安装的 URL 分配给环境变量 EXTERNAL_URL。在这种情况下，JupyterHub 默认使用 JUPYTERHUB_SERVICE_PREFIX。

def remote_jupyter_proxy_url(port):
    """
    Callable to configure Bokeh's show method when a proxy must be
    configured.

    If port is None we're asking about the URL
    for the origin header.
    """
    base_url = os.environ['EXTERNAL_URL']
    host = urllib.parse.urlparse(base_url).netloc

    # If port is None we're asking for the URL origin
    # so return the public hostname.
    if port is None:
        return host

    service_url_path = os.environ['JUPYTERHUB_SERVICE_PREFIX']
    proxy_url_path = 'proxy/%d' % port

    user_url = urllib.parse.urljoin(base_url, service_url_path)
    full_url = urllib.parse.urljoin(user_url, proxy_url_path)
    return full_url

将您定义的函数作为 notebook_url 关键字参数传递给 show() 函数。然后，Bokeh 在设置服务器并创建用于加载图形的 URL 时，会调用此函数

show(obj, notebook_url=remote_jupyter_proxy_url)

您可能需要在此之后重新启动服务器，然后 Bokeh 内容应加载并执行在 Jupyter 环境中定义的 Python 回调函数。

信任笔记本#

根据您使用的笔记本版本，您可能需要信任笔记本，才能在关闭笔记本并重新打开时重新渲染 Bokeh 图表。信任笔记本选项通常位于文件菜单下

Screenshot of the Jupyter File menu expanded to show the Trust Notebook option.

笔记本幻灯片#

您可以使用带有 Reveal.js 的笔记本从单元格生成幻灯片。您还可以将独立（即非服务器）Bokeh 图表包含在这些幻灯片中。但是，您需要采取一些额外的步骤才能正确显示输出。特别要注意，包含 output_notebook 的单元格不应跳过。

output_notebook 调用的已渲染单元格输出确保 BokehJS 库已加载。否则，Bokeh 图表将无法正常工作。如果此单元格的类型设置为“skip”，则 BokehJS 不会加载，并且 Bokeh 图表不会显示。如果您想隐藏此单元格，请将其分配给“notes” 幻灯片类型。

笔记本句柄#

您可以更新已显示的图表，而无需重新加载。为此，请将 notebook_handle=True 参数传递给 show()，以便它返回一个句柄对象。您可以使用此句柄对象和 push_notebook() 函数来使用图表属性、数据源值等的任何最新更改更新图表。

此笔记本句柄功能仅在经典 Jupyter 笔记本中受支持，尚未在 JupyterLab 或 Zeppelin 中实现。

以下屏幕截图说明了笔记本句柄的基本用法

导入标准函数和 push_notebook()

Screenshot of Jupyter showing Bokeh push_notebook being imported .

创建一些绘图并传递 notebook_handle=True 给 show()

Screenshot of Jupyter with Bokeh content created with notebook comms enabled.

检查该句柄是否与刚显示的 In[2] 的输出单元格相关联

Screenshot of Jupyter showing the representation of a notebook comms handle in an output cell.

更新绘图的某些属性，然后使用该句柄调用 push_notebook()

请注意，In[2] 的输出单元格已更改（无需重新执行）

Screenshot of Jupyter showing the previous plot updated in place, with glyph color white now.

有关笔记本句柄使用的更详细示例，请参见以下笔记本

Jupyter 交互器#

您可以使用笔记本小部件（称为交互器）来更新 Bokeh 绘图。执行此操作的关键是 push_notebook() 函数。交互器的更新回调会调用此函数，以根据小部件值更新绘图。请参见以下 examples/output/jupyter/push_notebook/Jupyter Interactors.ipynb 示例笔记本的屏幕截图

Screenshot of Jupyter showing a Bokeh plot together with ipywidget sliders.

笔记本外部的 IPyWidgets#

现在您已经了解了如何在 JupyterLab 和经典笔记本环境中使用 Bokeh，您可能希望利用这些环境之外充满活力的 Jupyter 生态系统。您可以通过 Bokeh 的 ipywidgets_bokeh 扩展来实现

$ conda install -c bokeh ipywidgets_bokeh

或者

$ pip install ipywidgets_bokeh

此扩展允许您在 Bokeh 中使用 IPyWidgets。只需将小部件包装在 IPyWidget 模型中，并将包装器添加到文档或将其包含在布局中即可。您无需安装或启用任何其他扩展。

示例#

请按照以下步骤构建具有单个 Jupyter 滑块的应用程序，该滑块会将其调整日志记录到控制台

首先构建一个小部件并配置观察者

from ipywidgets import FloatSlider
angle = FloatSlider(min=0, max=360, value=0, step=1, description="Angle")

def on_change(change):
    print(f"angle={change['new']} deg")
angle.observe(on_change, names="value")

要将小部件与 Bokeh 集成，请将其包装在 IPyWidget 中

from ipywidgets_bokeh import IPyWidget
ipywidget = IPyWidget(widget=angle)

将包装器添加到 Bokeh 文档

from bokeh.plotting import curdoc
doc = curdoc()
doc.add_root(ipywidget)

要运行该应用程序，请输入 bokeh serve ipy_slider.py，其中 ipy_slider.py 是应用程序的名称（有关详细信息，请参见 Bokeh 服务器）。此应用程序位于 https://127.0.0.1:5006/ipy_slider。

您可以在此基础上创建更复杂的布局并包含高级小部件，例如 ipyleaflet 和 ipyvolume。有关更多示例，请参见 Bokeh 存储库中的 examples/output/jupyter/ipywidgets。