数据源#

任何数据可视化的基础都是底层数据。本节介绍向 Bokeh 提供数据的各种方法，从直接传递数据值到创建 ColumnDataSource (CDS) 以及使用 CDSView 过滤数据。

使用 Python 列表提供数据#

使用标准的 Python 数据列表将值直接传递到绘图函数中。

在此示例中，列表 x_values 和 y_values 将数据传递给 circle() 函数（有关更多示例，请参见绘图函数）

from bokeh.plotting import figure

x_values = [1, 2, 3, 4, 5]
y_values = [6, 7, 2, 3, 6]

p = figure()
p.scatter(x=x_values, y=y_values)

提供 NumPy 数据#

与使用 Python 列表和数组类似，您也可以在 Bokeh 中使用 NumPy 数据结构

import numpy as np
from bokeh.plotting import figure

x = [1, 2, 3, 4, 5]
random = np.random.standard_normal(5)
cosine = np.cos(x)

p = figure()
p.scatter(x=x, y=random)
p.line(x=x, y=cosine)

将数据作为 ColumnDataSource 提供#

ColumnDataSource (CDS) 是大多数 Bokeh 绘图的核心。它为绘图的字形提供数据。

当您将 Python 列表或 NumPy 数组等序列传递给 Bokeh 渲染器时，Bokeh 会自动为您创建包含此数据的 ColumnDataSource。但是，自己创建 ColumnDataSource 可以让您访问更高级的选项。

例如：创建您自己的 ColumnDataSource 允许您在多个绘图和小部件之间共享数据。如果您将单个 ColumnDataSource 与多个渲染器一起使用，则这些渲染器还会共享有关您使用 Bokeh 工具栏中的选择工具选择的数据的信息（请参阅联动选择）。

可以将 ColumnDataSource 视为数据序列的集合，每个序列都有自己唯一的列名。

创建 ColumnDataSource#

要创建基本的 ColumnDataSource 对象，您需要一个 Python 字典来传递给该对象的 data 参数

Bokeh 使用字典的键作为列名。
字典的值用作 ColumnDataSource 的数据值。

您作为字典一部分传递的数据可以是任何非字符串的有序值序列，例如列表或数组（包括 NumPy 数组和 pandas Series）

data = {'x_values': [1, 2, 3, 4, 5],
        'y_values': [6, 7, 2, 3, 6]}

source = ColumnDataSource(data=data)

注意

ColumnDataSource 中的所有列都具有相同的长度。因此，您传递给单个 ColumnDataSource 的所有值序列也必须具有相同的长度。如果您尝试传递不同长度的序列，Bokeh 将无法创建您的 ColumnDataSource。

使用 ColumnDataSource 绘图#

要将 ColumnDataSource 与渲染器函数一起使用，您至少需要传递以下三个参数

x：ColumnDataSource 的列的名称，其中包含绘图 x 值的数据
y：ColumnDataSource 的列的名称，其中包含绘图 y 值的数据
source：ColumnDataSource 的名称，其中包含您刚刚为 x 和 y 参数引用的列。

例如

from bokeh.plotting import figure
from bokeh.models import ColumnDataSource

# create a Python dict as the basis of your ColumnDataSource
data = {'x_values': [1, 2, 3, 4, 5],
        'y_values': [6, 7, 2, 3, 6]}

# create a ColumnDataSource by passing the dict
source = ColumnDataSource(data=data)

# create a plot using the ColumnDataSource's two columns
p = figure()
p.scatter(x='x_values', y='y_values', source=source)

修改 ColumnDataSource#

要修改现有 ColumnDataSource 的数据，请更新 ColumnDataSource 对象的 .data 属性

要向现有 ColumnDataSource 添加新列
```
new_sequence = [8, 1, 4, 7, 3]
source.data["new_column"] = new_sequence
```
注意

您要添加的列的长度必须与现有列的长度匹配。
要替换现有 ColumnDataSource 中的所有数据，请为 .data 属性分配一个全新的字典
```
source.data = new_dict
```
注意

替换 ColumnDataSource 的全部内容也是更新其列长度的唯一方法。当您以更改任何列长度的方式更新数据时，您必须通过传递新字典同时更新所有列。无法一次更新一列的长度。

使用数据帧#

data 参数也可以是数据帧（pandas、Polars、PyArrow 或 Narwhals 支持的任何其他即时数据帧）或 pandas GroupBy 对象

source = ColumnDataSource(df)

如果您使用 DataFrame，则 Bokeh 中生成的 ColumnDataSource 将具有与 DataFrame 的列相对应的列。列的命名遵循以下规则

如果 DataFrame 具有命名的索引列，则 ColumnDataSource 也将具有具有此名称的列。
如果索引名称为 None （或者如果没有索引），则 ColumnDataSource 将具有通用名称：index （如果该名称可用）或 level_0。

使用 pandas MultiIndex#

如果您使用 pandas MultiIndex 作为 Bokeh ColumnDataSource 的基础，则 Bokeh 会在创建 ColumnDataSource 之前展平列和索引。对于索引，Bokeh 会创建一个元组索引，并将 MultiIndex 的名称用下划线连接起来。列名也将用下划线连接起来。例如

df = pd.DataFrame({('a', 'b'): {('A', 'B'): 1, ('A', 'C'): 2},
                   ('b', 'a'): {('A', 'C'): 7, ('A', 'B'): 8},
                   ('b', 'b'): {('A', 'D'): 9, ('A', 'B'): 10}})
cds = ColumnDataSource(df)

这将生成一个名为 index 的列，其中包含 [(A, B), (A, C), (A, D)]，以及名为 a_b、b_a 和 b_b 的列。

此过程仅适用于列名是字符串的情况。如果您使用非字符串列名，则需要在将其用作 Bokeh ColumnDataSource 的基础之前手动展平 DataFrame。

使用 pandas GroupBy#

group = df.groupby(('colA', 'ColB'))
source = ColumnDataSource(group)

如果您使用 pandas GroupBy 对象，则 ColumnDataSource 的列对应于调用 group.describe() 的结果。describe 方法为所有未分组的原始列生成统计度量列，例如 mean 和 count。

生成的 DataFrame 具有包含原始列名和计算度量的 MultiIndex 列。Bokeh 使用上述规则展平数据。

例如：如果 DataFrame 具有列 'year' 和 'mpg'，则将 df.groupby('year') 传递给 ColumnDataSource 将生成诸如 'mpg_mean' 之类的列。

注意

适配 GroupBy 对象需要 pandas 版本 0.20.0 或更高版本。

将数据附加到 ColumnDataSource#

ColumnDataSource 流式传输是将新数据附加到 ColumnDataSource 的有效方法。当您使用 stream() 方法时，Bokeh 只会将新数据发送到浏览器，而不是发送整个数据集。

stream() 方法采用 new_data 参数。此参数需要一个字典，该字典将列名映射到您要附加到相应列的数据序列。

该方法采用一个额外的可选参数 rollover。这是要保留的最大数据长度。当数据量超过最大值定义的数据量时，Bokeh 将从列的开头丢弃数据。rollover 的默认值为 None。此默认值允许数据无限增长。

source = ColumnDataSource(data=dict(foo=[], bar=[]))

# has new, identical-length updates for all columns in source
new_data = {
    'foo' : [10, 20],
    'bar' : [100, 200],
}

source.stream(new_data)

有关使用流式传输的示例，请参见 examples/server/app/ohlc。

替换 ColumnDataSource 中的数据#

ColumnDataSource 修补是更新数据源切片的有效方法。通过使用 patch() 方法，Bokeh 只会将新数据发送到浏览器，而不是发送整个数据集。

patch() 需要一个字典，该字典将列名映射到表示要应用的修补更改的元组列表。

可以与 patch() 一起使用的元组示例

(index, new_value)  # replace a single column value

# or

(slice, new_values) # replace several column values

有关完整示例，请参见 examples/server/app/patch_app.py。

转换数据#

到目前为止，您已将数据添加到 ColumnDataSource 以控制 Bokeh 绘图。但是，您也可以直接在浏览器中执行一些数据操作。

例如，在浏览器中动态计算颜色映射可以减少 Python 代码量。如果颜色映射所需的计算直接在浏览器中进行，您还需要发送更少的数据。

本节概述了可用的不同转换对象。

客户端颜色映射#

通过颜色映射，您可以将数据序列中的值编码为特定颜色。

Bokeh 提供了三个函数来直接在浏览器中执行颜色映射

用于线性颜色映射的 linear_cmap() 函数
用于对数颜色映射的 log_cmap() 函数
用于均衡直方图颜色映射的 eqhist_cmap() 函数

所有这三个函数的操作方式都类似，并接受以下参数

包含要映射颜色的数据的 ColumnDataSource 列的名称
调色板（可以是 Bokeh 的预定义调色板之一，也可以是自定义颜色列表）
颜色映射范围的 min 和 max 值。

颜色映射函数将数据源中的数值从 min 值到 max 值映射到调色板的颜色。

例如，使用范围为 [0,99] 和颜色 ['red', 'green', 'blue'] 的 linear_cmap() 函数将导致以下值到颜色的映射

      x < 0  : 'red'     # values < low are clamped
>= x < 33 : 'red'
>= x < 66 : 'green'
>= x < 99 : 'blue'
>= x      : 'blue'    # values > high are clamped

例如

fill_color=linear_cmap('counts', 'Viridis256', min=0, max=10)

将颜色映射与绘图对象的 color 属性（例如 fill_color）一起使用。

from numpy.random import standard_normal

from bokeh.plotting import figure, show
from bokeh.transform import linear_cmap
from bokeh.util.hex import hexbin

x = standard_normal(50000)
y = standard_normal(50000)

bins = hexbin(x, y, 0.1)

p = figure(tools="", match_aspect=True, background_fill_color='#440154')
p.grid.visible = False

p.hex_tile(q="q", r="r", size=0.1, line_color=None, source=bins,
           fill_color=linear_cmap('counts', 'Viridis256', 0, max(bins.counts)))

show(p)

映射器函数返回的数据规范包括 bokeh.transform。您可以访问此数据，以便在不同的上下文中使用映射器函数的结果。例如，要创建 ColorBar

from bokeh.models import ColumnDataSource
from bokeh.plotting import figure, show
from bokeh.transform import linear_cmap

x = list(range(1, 11))
y = list(range(1, 11))

source = ColumnDataSource(dict(x=x,y=y))

p = figure(width=300, height=300, title="Linear color map based on Y")

# use the field name of the column source
cmap = linear_cmap(field_name='y', palette="Spectral6", low=min(y), high=max(y))

r = p.scatter(x='x', y='y', color=cmap, size=15, source=source)

# create a color bar from the scatter glyph renderer
color_bar = r.construct_color_bar(width=10)

p.add_layout(color_bar, 'right')

show(p)

映射标记类型#

当您使用分类数据时，可以为数据中的每个类别使用不同的标记。使用 factor_mark() 函数自动为不同类别分配不同的标记

from bokeh.plotting import figure, show
from bokeh.sampledata.penguins import data
from bokeh.transform import factor_cmap, factor_mark

SPECIES = sorted(data.species.unique())
MARKERS = ['hex', 'circle_x', 'triangle']

p = figure(title = "Penguin size", background_fill_color="#fafafa")
p.xaxis.axis_label = 'Flipper Length (mm)'
p.yaxis.axis_label = 'Body Mass (g)'

p.scatter("flipper_length_mm", "body_mass_g", source=data,
          legend_group="species", fill_alpha=0.4, size=12,
          marker=factor_mark('species', MARKERS, SPECIES),
          color=factor_cmap('species', 'Category10_3', SPECIES))

p.legend.location = "top_left"
p.legend.title = "Species"

show(p)

此示例还使用 factor_cmap() 对这些相同的类别进行颜色映射。

注意

factor_mark() 转换通常仅对 scatter 字形方法有用，因为按标记类型参数化仅对散点图有意义。

包含 JavaScript 代码与 CustomJSTransform#

除了上面的内置转换函数之外，您还可以使用自己的 JavaScript 代码。使用 CustomJSTransform() 函数添加在浏览器中执行的自定义 JavaScript 代码。

下面的示例使用带有参数 v_func 的 CustomJSTransform() 函数。v_func 是 “向量化函数” 的缩写。您提供给 v_func 的 JavaScript 代码需要期望变量 xs 中包含输入数组，并返回包含转换值的 JavaScript 数组

v_func = """
    const first = xs[0]
    const norm = new Float64Array(xs.length)
    for (let i = 0; i < xs.length; i++) {
        norm[i] = xs[i] / first
    }
    return norm
"""
normalize = CustomJSTransform(v_func=v_func)

plot.line(x='aapl_date', y=transform('aapl_close', normalize), line_width=2,
          color='#cf3c4d', alpha=0.6,legend="Apple", source=aapl_source)

此示例中的代码将原始价格数据转换为相对于第一个数据点的归一化收益序列

过滤数据#

Bokeh 使用名为 “视图” 的概念来选择数据的子集。视图由 Bokeh 的 CDSView 类表示。当您使用视图时，可以使用一个或多个过滤器来选择特定的数据点，而无需更改底层数据。您还可以在不同的绘图之间共享这些视图。

要使用过滤后的数据子集进行绘图，请将 CDSView 传递给 Bokeh 绘图上任何渲染器方法的 view 参数。

CDSView 具有一个属性 filter

filter 是 Filter 模型的实例，在下面列出和描述。

在此示例中，您创建了一个名为 view 的 CDSView。view 使用 ColumnDataSource source 和两个过滤器的交集 filter1 和 filter2。view 然后传递给 scatter() 渲染器函数

from bokeh.plotting import figure
from bokeh.models import ColumnDataSource, CDSView

filter1 = ... # IndexFilter(), BooleanFilter(), etc.
filter2 = ...

source = ColumnDataSource(some_data)
view = CDSView(filter=filter1 & filter2)

p = figure()
p.scatter(x="x", y="y", source=source, view=view)

IndexFilter#

IndexFilter 是最简单的过滤器类型。它具有一个 indices 属性，该属性是您要包含在绘图中的数据索引的整数列表。

from bokeh.layouts import gridplot
from bokeh.models import CDSView, ColumnDataSource, IndexFilter
from bokeh.plotting import figure, show

source = ColumnDataSource(data=dict(x=[1, 2, 3, 4, 5], y=[1, 2, 3, 4, 5]))
view = CDSView(filter=IndexFilter([0, 2, 4]))

TOOLS = "box_select,hover,reset"

p1 = figure(height=300, width=300, tools=TOOLS)
p1.scatter(x="x", y="y", size=10, hover_color="red", source=source)

p2 = figure(height=300, width=300, tools=TOOLS)
p2.scatter(x="x", y="y", size=10, hover_color="red", source=source, view=view)

show(gridplot([[p1, p2]]))

BooleanFilter#

BooleanFilter 使用其 booleans 属性中的 True 或 False 值列表从数据源中选择行。

from bokeh.layouts import gridplot
from bokeh.models import BooleanFilter, CDSView, ColumnDataSource
from bokeh.plotting import figure, show

source = ColumnDataSource(data=dict(x=[1, 2, 3, 4, 5], y=[1, 2, 3, 4, 5]))

bools = [True if y_val > 2 else False for y_val in source.data['y']]
view = CDSView(filter=BooleanFilter(bools))

TOOLS = "box_select,hover,reset"

p1 = figure(height=300, width=300, tools=TOOLS)
p1.scatter(x="x", y="y", size=10, hover_color="red", source=source)

p2 = figure(height=300, width=300, tools=TOOLS,
            x_range=p1.x_range, y_range=p1.y_range)
p2.scatter(x="x", y="y", size=10, hover_color="red", source=source, view=view)

show(gridplot([[p1, p2]]))

GroupFilter#

GroupFilter 是用于分类数据的过滤器。使用此过滤器，您可以从数据集中选择属于特定类别的行。

GroupFilter 具有两个属性

column_name：ColumnDataSource 中要应用过滤器的列的名称
group：要选择的类别的名称

在下面的示例中，数据集 data 包含一个名为 species 的分类变量。所有数据都属于三个物种类别的其中之一：Adelie、Chinstrap 或 Gentoo。此示例中的第二个绘图使用 GroupFilter 仅显示属于类别 Adelie 的数据点

from bokeh.layouts import gridplot
from bokeh.models import CDSView, ColumnDataSource, GroupFilter
from bokeh.plotting import figure, show
from bokeh.sampledata.penguins import data

source = ColumnDataSource(data)
view = CDSView(filter=GroupFilter(column_name="species", group="Adelie"))

TOOLS = "box_select,reset,help"

p1 = figure(title="Full data set", height=300, width=300, tools=TOOLS)
p1.scatter(x="bill_length_mm", y="bill_depth_mm", source=source)

p2 = figure(title="Adelie only", height=300, width=300,
            tools=TOOLS, x_range=p1.x_range, y_range=p1.y_range)
p2.scatter(x="bill_length_mm", y="bill_depth_mm", size=6,
           source=source, view=view, color='darkorange')

show(gridplot([[p1, p2]]))

CustomJSFilter#

您还可以使用自己的 JavaScript 或 TypeScript 代码来创建自定义过滤器。要包含您的自定义过滤器代码，请使用 Bokeh 的 CustomJSFilter 类。将您的代码作为字符串传递给 CustomJSFilter 的参数 code。

您的 JavaScript 或 TypeScript 代码需要返回索引列表或表示过滤子集的布尔值列表。您可以从您的 JavaScript 或 TypeScript 代码中访问您正在使用的 ColumnDataSource 和 CDSView。Bokeh 通过变量 source 使 ColumnDataSource 可用

custom_filter = CustomJSFilter(code='''
const indices = [];

// iterate through rows of data source and see if each satisfies some constraint
for (let i = 0; i < source.get_length(); i++){
    if (source.data['some_column'][i] == 'some_value'){
        indices.push(true);
    } else {
        indices.push(false);
    }
}
return indices;
''')

AjaxDataSource#

更新和流式传输数据非常适用于 Bokeh 服务器应用程序。但是，也可以在独立文档中使用类似的功能。AjaxDataSource 提供了此功能，而无需 Bokeh 服务器。

要设置 AjaxDataSource，您需要使用 REST 端点的 URL 和轮询间隔对其进行配置。

在浏览器中，数据源以指定的间隔从端点请求数据。然后，它使用来自端点的数据在本地更新数据。

在本地更新数据可以通过两种方式进行：完全替换现有本地数据，或者将新数据附加到现有数据（最多可配置 max_size）。替换本地数据是默认设置。将 "replace" 或 "append" 作为 AjaxDataSource 的 mode 参数传递以控制此行为。

您与 AjaxDataSource 一起使用的端点应返回与标准 ColumnDataSource 格式匹配的 JSON 字典，即，将名称映射到值数组的 JSON 字典

{
    'x' : [1, 2, 3, ...],
    'y' : [9, 3, 2, ...]
}

或者，如果 REST API 返回不同的格式，则可以提供 CustomJS 回调，以通过此数据源的 adapter 属性将 REST 响应转换为 Bokeh 格式。

否则，使用 AjaxDataSource 与使用标准 ColumnDataSource 相同

# setup AjaxDataSource with URL and polling interval
source = AjaxDataSource(data_url='http://some.api.com/data',
                        polling_interval=100)

# use the AjaxDataSource just like a ColumnDataSource
p.circle('x', 'y', source=source)

这是使用 AjaxDataSource 时 Bokeh 中实时数据流的外观预览

Animated image showing a timeseries scatter plot updating periodically via the ajax streaming data source.

有关完整示例，请参见 Bokeh GitHub 存储库中的 examples/basic/data/ajax_source.py。

联动选择#

如果两个绘图都使用相同的 ColumnDataSource，则可以在两个绘图之间共享选择

from bokeh.layouts import gridplot
from bokeh.models import ColumnDataSource
from bokeh.plotting import figure, show
from bokeh.sampledata.penguins import data
from bokeh.transform import factor_cmap

SPECIES = sorted(data.species.unique())

TOOLS = "box_select,lasso_select,help"

source = ColumnDataSource(data)

left = figure(width=300, height=400, title=None, tools=TOOLS,
              background_fill_color="#fafafa")
left.scatter("bill_length_mm", "body_mass_g", source=source,
             color=factor_cmap('species', 'Category10_3', SPECIES))

right = figure(width=300, height=400, title=None, tools=TOOLS,
               background_fill_color="#fafafa", y_axis_location="right")
right.scatter("bill_depth_mm", "body_mass_g", source=source,
              color=factor_cmap('species', 'Category10_3', SPECIES))

show(gridplot([[left, right]]))

使用过滤数据的联动选择#

使用 ColumnDataSource，您还可以拥有两个基于相同数据但每个都使用该数据的不同子集的绘图。两个绘图仍然通过它们所基于的 ColumnDataSource 共享选择和悬停检查。

以下示例演示了此行为

第二个绘图是第一个绘图的数据子集。第二个绘图使用 CDSView 仅包含 y 值大于 250 或小于 100 的数据。
如果您使用任一绘图中的 BoxSelect 工具进行选择，则选择也会自动反映在另一个绘图中。
如果您在一个绘图中悬停在一个点上，则另一个绘图中相应的点也会自动突出显示（如果存在）。

from bokeh.layouts import gridplot
from bokeh.models import BooleanFilter, CDSView, ColumnDataSource
from bokeh.plotting import figure, show

x = list(range(-20, 21))
y0 = [abs(xx) for xx in x]
y1 = [xx**2 for xx in x]

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

# create a view of the source for one plot to use
view = CDSView(filter=BooleanFilter([True if y > 250 or y < 100 else False for y in y1]))

TOOLS = "box_select,lasso_select,hover,help"

# create a new plot and add a renderer
left = figure(tools=TOOLS, width=300, height=300, title=None)
left.scatter("x", "y0", size=10, hover_color="firebrick", source=source)

# create another new plot, add a renderer that uses the view of the data source
right = figure(tools=TOOLS, width=300, height=300, title=None)
right.scatter("x", "y1", size=10, hover_color="firebrick", source=source, view=view)

p = gridplot([[left, right]])

show(p)

其他数据类型#

您还可以使用 Bokeh 渲染网络图数据和地理数据。有关如何设置这些类型的绘图的数据的更多信息，请参见网络图和地理数据。