散点

class Scatter(*args: Any, id: ID | None = None, **kwargs: Any)

基类: Marker

渲染从预定义设计列表中选择的散点标记。

使用 Scatter 绘制 Bokeh 内置的任何标记类型：asterisk, circle, circle_cross, circle_dot, circle_x, circle_y, cross, dash, diamond, diamond_cross, diamond_dot, dot, hex, hex_dot, inverted_triangle, plus, square, square_cross, square_dot, square_pin, square_x, star, star_dot, triangle, triangle_dot, triangle_pin, x, 或 y。此集合在 MarkerType 中提供。

Bokeh 的内置标记由一组基本标记组成，其中大多数可以与不同类型的附加视觉特征组合。

您可以通过两种方式选择标记类型

• 要为所有值绘制相同的标记，请使用 marker 属性来指定特定标记的名称。例如

  glyph = Scatter(x="x", y="y", size="sizes", marker="square")
  plot.add_glyph(source, glyph)
  

  这将为所有点渲染正方形标记。

• 或者，要使用数据源列中指定的标记类型，请将列名分配给 marker 属性。例如

  # source.data['markers'] = ["circle", "square", "circle", ... ]
  
  glyph = Scatter(x="x", y="y", size="sizes", marker="markers")
  plot.add_glyph(source, glyph)
  

也可以定义自定义标记。请参阅 bokeh.models.Scatter.defs。

注意

当您使用 Scatter 绘制 circle 标记时，您只能在 屏幕单位 中分配大小（通过将像素数传递给 size 属性）。如果您想在 数据单位 中定义圆的半径，请使用 Circle 字形，而不是 Scatter 字形。

注意

当使用 WebGL 输出后端时，具有多种标记类型的 Scatter 标记可能会以不同的顺序绘制。这是为了性能而做出的明确权衡。

示例

import numpy as np

from bokeh.core.enums import MarkerType
from bokeh.io import curdoc, show
from bokeh.models import ColumnDataSource, Grid, LinearAxis, Plot, Scatter

N = len(MarkerType)
x = np.linspace(-2, 2, N)
y = x**2
markers = list(MarkerType)

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

plot = Plot(
    title=None, width=300, height=300,
    min_border=0, toolbar_location=None)

glyph = Scatter(x="x", y="y", size=20, fill_color="#74add1", marker="markers")
plot.add_glyph(source, glyph)

xaxis = LinearAxis()
plot.add_layout(xaxis, 'below')

yaxis = LinearAxis()
plot.add_layout(yaxis, 'left')

plot.add_layout(Grid(dimension=0, ticker=xaxis.ticker))
plot.add_layout(Grid(dimension=1, ticker=yaxis.ticker))

curdoc().add_root(plot)

show(plot)

JSON 原型

{
  "angle": {
    "type": "value", 
    "value": 0.0
  }, 
  "decorations": [], 
  "defs": {
    "type": "map"
  }, 
  "fill_alpha": {
    "type": "value", 
    "value": 1.0
  }, 
  "fill_color": {
    "type": "value", 
    "value": "gray"
  }, 
  "hatch_alpha": {
    "type": "value", 
    "value": 1.0
  }, 
  "hatch_color": {
    "type": "value", 
    "value": "black"
  }, 
  "hatch_extra": {
    "type": "map"
  }, 
  "hatch_pattern": {
    "type": "value", 
    "value": null
  }, 
  "hatch_scale": {
    "type": "value", 
    "value": 12.0
  }, 
  "hatch_weight": {
    "type": "value", 
    "value": 1.0
  }, 
  "hit_dilation": 1.0, 
  "id": "p60652", 
  "js_event_callbacks": {
    "type": "map"
  }, 
  "js_property_callbacks": {
    "type": "map"
  }, 
  "line_alpha": {
    "type": "value", 
    "value": 1.0
  }, 
  "line_cap": {
    "type": "value", 
    "value": "butt"
  }, 
  "line_color": {
    "type": "value", 
    "value": "black"
  }, 
  "line_dash": {
    "type": "value", 
    "value": []
  }, 
  "line_dash_offset": {
    "type": "value", 
    "value": 0
  }, 
  "line_join": {
    "type": "value", 
    "value": "bevel"
  }, 
  "line_width": {
    "type": "value", 
    "value": 1
  }, 
  "marker": {
    "type": "value", 
    "value": "circle"
  }, 
  "name": null, 
  "size": {
    "type": "value", 
    "value": 4
  }, 
  "subscribed_events": {
    "type": "set"
  }, 
  "syncable": true, 
  "tags": [], 
  "x": {
    "field": "x", 
    "type": "field"
  }, 
  "y": {
    "field": "y", 
    "type": "field"
  }
}

angle = 0.0

类型:

AngleSpec

旋转标记的角度。

angle_units = 'rad'

类型:

NotSerialized(Enum(AngleUnits))

用于关联属性的单位：deg、rad、grad 或 turn

decorations = []

类型:

列表

字形装饰的集合，例如箭头头部。

使用 GlyphRenderer.add_decoration() 可以轻松为字形渲染器的所有字形进行设置。当需要更精细的控制时，请使用此属性。

注意

装饰仅用于辅助字形的视觉外观，但不参与点击测试等。

defs = {}

类型:

Dict(Regex, Instance(CustomJS))

自定义标记定义的集合。

有两种方法可以定义自定义标记

• 构造并返回 Path2D 的实例

CustomJS(code='''
    export default (args, obj, {ctx, i, r, visuals}) => {
        const path = new Path2D()
        path.arc(0, 0, r, 0, 2*Math.PI, false)
        return path
    }
''')

• 直接绘制到 Context2d 的实例

CustomJS(code='''
    export default (args, obj, {ctx, i, r, visuals}) => {
        ctx.arc(0, 0, r, 0, 2*Math.PI, false)
        visuals.fill.apply(ctx, i)
        visuals.hatch.apply(ctx, i)
        visuals.line.apply(ctx, i)
    }
''')

注意

自定义标记的名称必须以 “@” 前缀开头，例如 “@my_marker”。

注意

只有 "canvas" 和 "svg" 后端支持自定义标记。

fill_alpha = 1.0

类型:

AlphaSpec

标记的填充 alpha 值。

fill_color = 'gray'

类型:

ColorSpec

标记的填充颜色值。

hatch_alpha = 1.0

类型:

AlphaSpec

标记的阴影线 alpha 值。

hatch_color = 'black'

类型:

ColorSpec

标记的阴影线颜色值。

hatch_extra = {}

类型:

Dict(String, Instance(Texture))

标记的阴影线额外值。

hatch_pattern = None

类型:

HatchPatternSpec

标记的阴影线图案值。

hatch_scale = 12.0

类型:

FloatSpec

标记的阴影线比例值。

hatch_weight = 1.0

类型:

FloatSpec

标记的阴影线粗细值。

hit_dilation = 1.0

类型:

Size

用于扩大点击半径的因子，该半径负责定义标记响应与 Hover 和 Tap 工具交互的范围。

line_alpha = 1.0

类型:

AlphaSpec

标记的线条 alpha 值。

line_cap = 'butt'

类型:

LineCapSpec

标记的线帽值。

line_color = 'black'

类型:

ColorSpec

标记的线条颜色值。

line_dash = []

类型:

DashPatternSpec

标记的线条虚线值。

line_dash_offset = 0

类型:

IntSpec

标记的线条虚线偏移值。

line_join = 'bevel'

类型:

LineJoinSpec

标记的线条连接值。

line_width = 1

类型:

FloatSpec

标记的线条宽度值。

marker = 'circle'

类型:

MarkerSpec

要渲染的标记。这可以是任何内置标记的名称，例如 “circle”，也可以是对包含此类名称的数据列的引用。

name = None

类型:

Nullable(String)

此模型的任意用户提供的名称。

当查询文档以检索特定的 Bokeh 模型时，此名称可能很有用。

>>> plot.scatter([1,2,3], [4,5,6], name="temp")
>>> plot.select(name="temp")
[GlyphRenderer(id='399d53f5-73e9-44d9-9527-544b761c7705', ...)]

注意

对于提供的任何名称，不强制执行唯一性保证或其他条件，Bokeh 出于任何原因也不会直接使用该名称。

size = 4

类型:

SizeSpec

标记在屏幕空间单位中的大小（直径）值。

syncable = True

类型:

布尔型

指示此模型在 Web 浏览器中更新时是否应同步回 Bokeh 服务器。当处理频繁更新的对象且我们不需要其更新值时，设置为 False 可能有助于减少网络流量。

注意

将此属性设置为 False 将阻止此对象上的任何 on_change() 回调触发。但是，任何 JS 端回调仍然有效。

tags = []

类型:

列表

要附加到此模型的任意用户提供值的可选列表。

当查询文档以检索特定的 Bokeh 模型时，此数据可能很有用

>>> r = plot.scatter([1,2,3], [4,5,6])
>>> r.tags = ["foo", 10]
>>> plot.select(tags=['foo', 10])
[GlyphRenderer(id='1de4c3df-a83d-480a-899b-fb263d3d5dd9', ...)]

或者仅仅是将任何必要的元数据附加到可由 CustomJS 回调等访问的模型的便捷方式。

注意

对于提供的任何标签，不强制执行唯一性保证或其他条件，Bokeh 出于任何原因也不会直接使用标签。

x = Field(field='x', transform=Unspecified, units=Unspecified)

类型:

NumberSpec

标记中心点的 x 轴坐标。

y = Field(field='y', transform=Unspecified, units=Unspecified)

类型:

NumberSpec

标记中心点的 y 轴坐标。

apply_theme(property_values: dict[str, Any]) → None

应用一组主题值，这些值将代替默认值，但不会覆盖应用程序设置的值。

传入的字典可以保持原样并与其他实例共享，以节省内存（因此调用者和 HasProps 实例都不应修改它）。

参数:

property_values (dict) – 用于代替默认值的主题值

返回:

None

classmethod clear_extensions() → None

清除任何当前定义的自定义扩展。

序列化调用将导致任何当前定义的自定义扩展与生成的文档一起包含，无论是否使用它们。此方法可用于清除所有现有的自定义扩展定义。

clone(**overrides: Any) → Self

复制 HasProps 对象。

这将创建原始模型的浅克隆，即任何可变容器或子模型都不会被复制。允许在克隆时覆盖特定属性。

classmethod dataspecs() → dict[str, DataSpec]

收集此类上所有 DataSpec 属性的名称。

此方法始终遍历类层次结构，并包括在任何父类上定义的属性。

返回:

DataSpec 属性的名称

返回类型:

set[str]

classmethod descriptors() → list[PropertyDescriptor[Any]]

属性描述符列表，按定义顺序排列。

destroy() → None

清理对文档和属性的引用

equals(other: HasProps) → bool

模型的结构相等性。

参数:

other (HasProps) – 要比较的另一个实例

返回:

如果属性在结构上相等，则为 True，否则为 False

js_link(attr: str, other: Model, other_attr: str, attr_selector: int | str | None = None) → None

使用 JavaScript 链接两个 Bokeh 模型属性。

这是一种便捷方法，可简化添加 CustomJS 回调，以便在一个 Bokeh 模型属性的值发生更改时更新另一个属性。

参数:

• attr (str) – 此模型上 Bokeh 属性的名称

• other (Model) – 要链接到 self.attr 的 Bokeh 模型

• other_attr (str) – 要链接在一起的 other 上的属性

• attr_selector (int | str) – 用于链接可下标 attr 中项目的索引

在版本 1.1 中添加

Raises:

ValueError –

示例

带有 js_link 的此代码

select.js_link('value', plot, 'sizing_mode')

等效于以下代码

from bokeh.models import CustomJS
select.js_on_change('value',
    CustomJS(args=dict(other=plot),
             code="other.sizing_mode = this.value"
    )
)

此外，要使用 attr_selector 将范围滑块的左侧附加到绘图的 x_range

range_slider.js_link('value', plot.x_range, 'start', attr_selector=0)

这等效于

from bokeh.models import CustomJS
range_slider.js_on_change('value',
    CustomJS(args=dict(other=plot.x_range),
             code="other.start = this.value[0]"
    )
)

js_on_change(event: str, *callbacks: JSChangeCallback) → None

将 CustomJS 回调附加到任意 BokehJS 模型事件。

在 BokehJS 端，模型属性的更改事件形式为 "change:property_name"。为了方便起见，如果传递给此方法的事件名称也是模型上属性的名称，则它将自动以 "change:" 为前缀。

# these two are equivalent
source.js_on_change('data', callback)
source.js_on_change('change:data', callback)

然而，除了属性更改事件之外，还有其他类型的事件也可能需要响应。例如，要在数据流式传输到 ColumnDataSource 时运行回调，请使用源上的 "stream" 事件。

source.js_on_change('streaming', callback)

classmethod lookup(name: str, *, raises: bool = True) → PropertyDescriptor[Any] | None

查找类上 Bokeh 属性的 PropertyDescriptor，给定属性名称。

参数:

• name (str) – 要搜索的属性的名称

• raises (bool) – 如果找不到是否引发异常或返回 None

返回:

名为 name 的属性的描述符

返回类型:

PropertyDescriptor

on_change(attr: str, *callbacks: PropertyCallback) → None

在此对象上添加一个回调，以便在 attr 更改时触发。

参数:

• attr (str) – 此对象上的属性名称

• *callbacks (callable) – 要注册的回调函数

返回:

None

示例

widget.on_change('value', callback1, callback2, ..., callback_n)

on_event(event: str | type[Event], *callbacks: Callable[[Event], None] | Callable[[], None]) → None

当在此模型上发生指定的事件时运行回调。

并非所有模型都支持所有事件。有关哪些模型能够触发哪些事件的更多信息，请参阅 bokeh.events 中的特定事件。

classmethod parameters() → list[Parameter]

生成适用于从 glyph 派生的函数的 Python Parameter 值。

返回:

list(Parameter)

classmethod properties(*, _with_props: bool = False) → set[str] | dict[str, Property[Any]]

收集此类上属性的名称。

警告

在 Bokeh 的未来版本中，此方法将返回一个字典，该字典将属性名称映射到属性对象。为了使当前此方法的使用方式在未来仍然适用，请将返回值包装在 list 中。

返回:

属性名称

classmethod properties_with_refs() → dict[str, Property[Any]]

收集此类上所有也具有引用的属性的名称。

此方法始终遍历类层次结构，并包括在任何父类上定义的属性。

返回:

具有引用的属性的名称

返回类型:

set[str]

properties_with_values(*, include_defaults: bool = True, include_undefined: bool = False) → dict[str, Any]

收集一个字典，将属性名称映射到它们的值。

此方法始终遍历类层次结构，并包括在任何父类上定义的属性。

不可序列化的属性将被跳过，并且属性值采用“序列化”格式，这可能与您通常从属性中读取的值略有不同；此方法的目的是返回无损地重构对象实例所需的信息。

参数:

include_defaults (bool, 可选) – 是否包含自对象创建以来尚未显式设置的属性。（默认值：True）

返回:

从属性名称到其值的映射

返回类型:

dict

query_properties_with_values(query: Callable[[PropertyDescriptor[Any]], bool], *, include_defaults: bool = True, include_undefined: bool = False) → dict[str, Any]

使用谓词查询 HasProps 实例的属性值。

参数:

• query (callable) – 接受属性描述符并返回 True 或 False 的可调用对象

• include_defaults (bool, 可选) – 是否包含用户尚未显式设置的属性（默认值：True）

返回:

匹配属性的属性名称和值的映射

返回类型:

dict

references() → set[Model]

返回此对象引用的所有 Models。

remove_on_change(attr: str, *callbacks: Callable[[str, Any, Any], None]) → None

从此对象中删除回调

select(selector: SelectorType) → Iterable[Model]

查询此对象及其所有引用，以查找与给定选择器匹配的对象。

参数:

selector (JSON-like)

返回:

seq[Model]

select_one(selector: SelectorType) → Model | None

查询此对象及其所有引用，以查找与给定选择器匹配的对象。如果找到多个对象，则引发错误。返回单个匹配对象，如果未找到任何内容，则返回 None :param selector: :type selector: JSON-like

返回:

Model

set_from_json(name: str, value: Any, *, setter: Setter | None = None) → None

从此对象的 JSON 中设置属性值。

参数:

• name (str) – 要设置的属性的名称

• value (JSON-value) – 要设置为属性的值

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  这用于防止对 Bokeh 应用程序的“回旋镖”更新。

  在 Bokeh 服务器应用程序的上下文中，传入的属性更新将使用正在执行更新的会话进行注释。此值会通过更新触发的任何后续更改通知进行传播。会话可以将事件 setter 与自身进行比较，并阻止任何源自自身的更新。

返回:

None

set_select(selector: type[Model] | SelectorType, updates: dict[str, Any]) → None

使用指定的属性/值更新来更新与给定选择器匹配的对象。

参数:

• selector (JSON-like)

• updates (dict)

返回:

None

themed_values() → dict[str, Any] | None

获取任何主题提供的覆盖。

结果以从属性名称到值的字典形式返回，如果没有主题覆盖此实例的任何值，则返回 None。

返回:

dict 或 None

to_serializable(serializer: Serializer) → ObjectRefRep

将此对象转换为可序列化的表示形式。

trigger(attr: str, old: Any, new: Any, hint: DocumentPatchedEvent | None = None, setter: Setter | None = None) → None

unapply_theme() → None

删除任何主题值并恢复默认值。

返回:

None

update(**kwargs: Any) → None

从给定的关键字参数更新对象的属性。

返回:

None

示例

以下是等效的

from bokeh.models import Range1d

r = Range1d

# set properties individually:
r.start = 10
r.end = 20

# update properties together:
r.update(start=10, end=20)

property document: Document | None

此模型附加到的 Document (可以为 None)