快速启动¶

Bokeh是一个面向现代web浏览器的交互式可视化库。它提供优雅、简洁的多功能图形结构，并在大型或流式数据集上提供高性能的交互性。Bokeh可以帮助任何想要快速方便地制作交互式绘图、仪表板和数据应用程序的人。

为了提供高级定制所需的简单性和强大灵活的功能，Bokeh向用户公开了两个界面级别：

bokeh.models: A low-level 为应用程序开发人员提供最大灵活性的接口。
bokeh.plotting: A higher-level 以合成视觉符号为中心的界面。

此快速入门着重于|博克。绘图|接口。

安装¶

安装Bokeh有多种方法，我们推荐最简单的一种，即使用 Anaconda Python distribution 并在Bash或Windows命令提示符下输入以下命令：

conda install bokeh

这将安装Bokeh需要的所有依赖项。Anaconda将所有平台和配置（包括Windows）上的安装工作量降至最低，并将示例安装到 examples/ 您的Anaconda或Miniconda安装目录的子目录。

如果您确信已经安装了所有需要的依赖项，例如NumPy，则可以使用 pip 在命令行：

pip install bokeh

注解

这个 pip 方法不安装示例。克隆Git存储库并查看 examples/ 查看示例的签出目录。

入门¶

Bokeh是一个大型库，它公开了许多功能，因此本节仅简要介绍一些常见的Bokeh用例和工作流。更多详细信息请咨询用户指南 .

让我们从一些例子开始。

在基本Python列表中以直线图的形式打印数据，包括缩放、平移、保存和其他工具，非常简单明了：

from bokeh.plotting import figure, output_file, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [6, 7, 2, 4, 5]

# output to static HTML file
output_file("lines.html")

# create a new plot with a title and axis labels
p = figure(title="simple line example", x_axis_label='x', y_axis_label='y')

# add a line renderer with legend and line thickness
p.line(x, y, legend_label="Temp.", line_width=2)

# show the results
show(p)

当您执行这个脚本时，您将看到一个新的输出文件 "lines.html" ，浏览器会自动打开一个新的选项卡来显示它（出于演示目的，我们在本文档中直接包含了打印输出）。

创建绘图的基本步骤|博克。绘图|接口包括：

准备一些数据: 在本例中，纯Python列表，但NumPy数组或Pandas系列也可以。
告诉Bokeh在哪里生成输出: 在这种情况下，使用 output_file() ，带有文件名 "lines.html" . 另一个选择是 output_notebook() 用于Jupyter笔记本电脑。
呼叫 figure(): 这将创建具有典型默认选项的打印，并易于自定义标题、工具和轴标签。
添加渲染器: 在这种情况下，我们使用|线|对于我们的数据，指定视觉自定义，如颜色、图例和宽度。
叫博克去 show() 或 save() 结果: 这些函数将绘图保存到HTML文件中，并可选择在浏览器中显示它。

可以重复步骤3和4来创建多个绘图，如下例所示。

在|博克。绘图|如果我们需要通过添加更多的数据系列、字形、对数轴等来定制输出，那么接口也非常方便。将多个字形组合在一个图上很容易，如下所示：

from bokeh.plotting import figure, output_file, show

# prepare some data
x = [0.1, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
y0 = [i**2 for i in x]
y1 = [10**i for i in x]
y2 = [10**(i**2) for i in x]

# output to static HTML file
output_file("log_lines.html")

# create a new plot
p = figure(
   tools="pan,box_zoom,reset,save",
   y_axis_type="log", y_range=[0.001, 10**11], title="log axis example",
   x_axis_label='sections', y_axis_label='particles'
)

# add some renderers
p.line(x, x, legend_label="y=x")
p.circle(x, x, legend_label="y=x", fill_color="white", size=8)
p.line(x, y0, legend_label="y=x^2", line_width=3)
p.line(x, y1, legend_label="y=10^x", line_color="red")
p.circle(x, y1, legend_label="y=10^x", fill_color="red", line_color="red", size=6)
p.line(x, y2, legend_label="y=10^x^2", line_color="orange", line_dash="4 4")

# show the results
show(p)

Jupyter笔记本¶

在这一点上，我们应该提到Jupyter笔记本。

Jupyter笔记本是用于探索性数据分析的常用工具，在PyData社区中广泛使用。Bokeh与Jupyter笔记本电脑无缝集成。要在笔记本中查看以上示例，您只需更改 output_file() 到 output_notebook() 相反。

你可以直接与 live tutorial notebooks 由MyBinder在线主持。静态版本可以在 Bokeh NBViewer Gallery .

这个 Bokeh GitHub repository 在 examples/howto 目录。克隆存储库后，导航到此处并运行：

jupyter notebook

您可以打开自动打开的索引页上列出的任何笔记本并与之交互。特别是，您可以查看以下示例，这些示例展示了如何将Bokeh与Jupyter交互式小部件一起使用：

examples/howto/notebook_comms/Jupyter Interactors.ipynb: 一个基本的例子，结合了Bokeh的交互功能和Jupyter的下拉列表和滑块。
examples/howto/notebook_comms/Numba Image Example.ipynb: 一个更高级的示例，它使用Numba有效地基于Jupyter小部件控件以交互方式执行图像处理。

注解

Bokeh绘图将不会在GitHub笔记本预览中显示内联 . Bokeh绘图使用JavaScript代码进行渲染，但GitHub会从预览内容中删除所有JavaScript。

样本数据¶

Bokeh源代码中包含的一些示例使用了单独分发的示例数据文件。要下载此数据，请在Bash或Windows命令提示符下执行以下命令：

bokeh sampledata

有关详细信息，请参阅|bokeh.sampledata公司|参考。

概念¶

让我们考虑一下上面的图，并使用它们来帮助定义一些核心概念。

情节¶

情节是博克的中心概念。它们是包含所有不同对象（渲染器、指南、数据和工具）的容器，这些对象构成了呈现给用户的最终可视化效果。在|博克。绘图|接口提供 figure() 函数帮助组装所有必需的对象。

字形¶

字形的视觉外观直接与与字形的各种属性关联的数据值相关联。在上面的示例中，我们看到位置属性类似于 x 和 y 可以设置为数据向量。但是字形也有一些组合线条属性，填充属性和图案填充特性控制他们的外表。所有这些属性也可以设置为“矢量化”值。我们将在下面展示这个例子。

指南和注释¶

Bokeh图还可以有其他的视觉组件，帮助演示或帮助用户进行比较。它们分为两类。指南是帮助用户判断距离、角度等的视觉辅助工具。这些工具包括网格线或条带、轴（如线性、对数或日期时间）也可能有刻度和刻度标签。注解图的名称或部分是视觉辅助工具。包括标题、图例等。

范围¶

范围描述绘图的数据空间边界。默认情况下，使用|博克。绘图|接口配置有 DataRange1d 尝试自动设置绘图边界以包含所有可用数据的对象。但有可能提供明确的 Range1d 对象的固定边界。为了方便起见，这些通常也可以拼写为2元组或列表：

p = figure(x_range=[0,10], y_range=(10, 20))

资源¶

要生成绘图，必须将客户端库BokehJS JavaScript和CSS代码加载到浏览器中。默认情况下 output_file() 函数将从 cdn.bokeh.org . 但是，您也可以配置Bokeh，通过传递参数，生成直接嵌入BokehJS资源的静态HTML文件 mode="inline" 到 output_file() 功能。

更多示例¶

下面还有几个示例来演示|博克。绘图|接口。

矢量化颜色和大小¶

这个例子展示了如何为glyph属性提供数据值序列，比如 fill_color 和 radius . 本例中需要注意的其他事项：

向提供工具名称的显式列表 figure()
使用从CDN获取BokehJS资源 mode 参数
设置 x_range 和 y_range 明确地
转弯 off （通过将其值设置为 None ）
使用NumPy数组提供数据

import numpy as np

from bokeh.plotting import figure, output_file, show

# prepare some data
N = 4000
x = np.random.random(size=N) * 100
y = np.random.random(size=N) * 100
radii = np.random.random(size=N) * 1.5
colors = [
    "#%02x%02x%02x" % (int(r), int(g), 150) for r, g in zip(50+2*x, 30+2*y)
]

# output to static HTML file (with CDN resources)
output_file("color_scatter.html", title="color_scatter.py example", mode="cdn")

TOOLS = "crosshair,pan,wheel_zoom,box_zoom,reset,box_select,lasso_select"

# create a new plot with the tools above, and explicit ranges
p = figure(tools=TOOLS, x_range=(0, 100), y_range=(0, 100))

# add a circle renderer with vectorized colors and sizes
p.circle(x, y, radius=radii, fill_color=colors, fill_alpha=0.6, line_color=None)

# show the results
show(p)

连锁淘刷¶

将不同曲线图的各个方面联系在一起是一种有用的数据可视化技术。在Bokeh，这种联系通常由分享一些绘图组件在绘图之间。下面是一个示例 链接平移 （改变一个绘图的范围会导致其他绘图更新）通过在绘图之间共享范围对象。在本例中，需要注意的其他事项：

打电话 figure() 多次创建多个绘图
使用 gridplot() 在一个数组中排列多个绘图
使用新的字形方法显示新的字形|图.三角形|以及|图.正方形|
通过设置隐藏工具栏 toolbar_location 到 None
设置方便参数 color （同时设置 line_color 和 fill_color ） alpha （同时设置 line_alpha 和 fill_alpha ）

import numpy as np

from bokeh.layouts import gridplot
from bokeh.plotting import figure, output_file, show

# prepare some data
N = 100
x = np.linspace(0, 4*np.pi, N)
y0 = np.sin(x)
y1 = np.cos(x)
y2 = np.sin(x) + np.cos(x)

# output to static HTML file
output_file("linked_panning.html")

# create a new plot
s1 = figure(width=250, plot_height=250, title=None)
s1.circle(x, y0, size=10, color="navy", alpha=0.5)

# NEW: create a new plot and share both ranges
s2 = figure(width=250, height=250, x_range=s1.x_range, y_range=s1.y_range, title=None)
s2.triangle(x, y1, size=10, color="firebrick", alpha=0.5)

# NEW: create a new plot and share only one range
s3 = figure(width=250, height=250, x_range=s1.x_range, title=None)
s3.square(x, y2, size=10, color="olive", alpha=0.5)

# NEW: put the subplots in a gridplot
p = gridplot([[s1, s2, s3]], toolbar_location=None)

# show the results
show(p)

虽然工具栏处于隐藏状态，但“平移”工具仍然存在并处于活动状态。单击并拖动以上绘图以平移它们，并查看它们的范围是如何链接在一起的。

另一个经常有用的联系是 连锁刷牙 （一个绘图上的选择会导致另一个绘图上的选择更新）。下面的示例演示了通过共享 ColumnDataSource 两个地块之间：

import numpy as np
from bokeh.plotting import *
from bokeh.models import ColumnDataSource

# prepare some date
N = 300
x = np.linspace(0, 4*np.pi, N)
y0 = np.sin(x)
y1 = np.cos(x)

# output to static HTML file
output_file("linked_brushing.html")

# NEW: create a column data source for the plots to share
source = ColumnDataSource(data=dict(x=x, y0=y0, y1=y1))

TOOLS = "pan,wheel_zoom,box_zoom,reset,save,box_select,lasso_select"

# create a new plot and add a renderer
left = figure(tools=TOOLS, width=350, height=350, title=None)
left.circle('x', 'y0', source=source)

# create another new plot and add a renderer
right = figure(tools=TOOLS, width=350, height=350, title=None)
right.circle('x', 'y1', source=source)

# put the subplots in a gridplot
p = gridplot([[left, right]])

# show the results
show(p)

选择长方体或套索选择工具，然后单击并拖动以在一个绘图上进行选择，这将更新另一个绘图上的选择。

日期时间轴¶

处理日期和时间序列是另一个常见的任务。博克有一个复杂的 DatetimeAxis 它可以根据绘图的当前比例更改显示的记号。Bokeh会自动默认某些输入 DatetimeAxis ，但您始终可以通过传递值显式地请求一个 "datetime" 到 x_axis_type 或 y_axis_type 参数到 figure() . 在本例中需要注意的几个问题：

设置 plot_width 和 plot_height 论据 figure()
通过为打印和其他对象的属性指定值来自定义它们
方便地访问指南和注释 Figure 属性： legend ， grid ， xgrid ， ygrid ， axis ， xaxis ， yaxis

import numpy as np

from bokeh.plotting import figure, output_file, show
from bokeh.sampledata.stocks import AAPL

# prepare some data
aapl = np.array(AAPL['adj_close'])
aapl_dates = np.array(AAPL['date'], dtype=np.datetime64)

window_size = 30
window = np.ones(window_size)/float(window_size)
aapl_avg = np.convolve(aapl, window, 'same')

# output to static HTML file
output_file("stocks.html", title="stocks.py example")

# create a new plot with a datetime axis type
p = figure(plot_width=800, plot_height=350, x_axis_type="datetime")

# add renderers
p.circle(aapl_dates, aapl, size=4, color='darkgrey', alpha=0.2, legend_label='close')
p.line(aapl_dates, aapl_avg, color='navy', legend_label='avg')

# NEW: customize by setting attributes
p.title.text = "AAPL One-Month Average"
p.legend.location = "top_left"
p.grid.grid_line_alpha = 0
p.xaxis.axis_label = 'Date'
p.yaxis.axis_label = 'Price'
p.ygrid.band_fill_color = "olive"
p.ygrid.band_fill_alpha = 0.1

# show the results
show(p)

Bokeh应用程序¶

Bokeh还附带了一个可选的服务器组件Bokeh服务器。我们可以在不使用Bokeh服务器的情况下创建许多有趣的交互式可视化，正如我们在上面所看到的。然而，Bokeh服务器提供了许多新颖而强大的功能，包括：

驱动计算和绘图更新的UI小部件和绘图选择。
大型数据集的智能服务器端下采样。
流数据自动更新绘图。
复杂的字形重写和“大数据”转换。
为更广泛的受众发布绘图和仪表板。

Bokeh服务器使用的详细信息需要比Quickstart允许的更多空间，但您可以在下面看到（并与之交互）一个简单的Bokeh服务器应用程序：

更多托管Bokeh应用程序的示例可以在服务器应用程序示例剖面图绘图示例 . 有关如何使用服务器和编写Bokeh服务器绘图和应用程序的信息，请参阅运行Bokeh服务器剖面图用户指南 .

下一步是什么？¶

这个快速入门几乎触及了Bokeh的能力。

有关Bokeh提供的不同绘图api的更多信息，使用Bokeh服务器，以及如何在自己的应用程序和文档中嵌入Bokeh绘图，请查看用户指南 . 有关所有模块、类、模型和对象的详细信息，请参阅参考文献 . 如果您对学习如何构建和开发Bokeh感兴趣，或者有关如何创建新语言绑定的信息，请参阅开发商指南。

要查看关于如何将Bokeh用于自己的数据的现成示例，请查看绘图示例 . 要查看详细的示例和演练，以及查找通过做来学习Bokeh的练习，请通过 live tutorial notebooks .

有关问题和技术帮助，请加入 Bokeh Discourse .

参观 Bokeh GitHub repository 试试这些例子。

一定要在Twitter上关注我们 @bokeh 你说什么？