Configuring Plot Tools¶

BoxSelectTool¶

• name: 'box_select'
• icon:

The box selection tool allows the user to define a rectangular selection region by left-dragging a mouse, or dragging a finger across the plot area. The box select tool may be configured to select across only one dimension by setting the dimensions property to a list containing width or height.

BoxZoomTool¶

• name: 'box_zoom'
• icon:

The box zoom tool allows the user to define a rectangular region to zoom the plot bounds too, by left-dragging a mouse, or dragging a finger across the plot area.

LassoSelectTool¶

• name: 'lasso_select'
• icon:

The lasso selection tool allows the user to define an arbitrary region for selection by left-dragging a mouse, or dragging a finger across the plot area.

PanTool¶

• name: 'pan', 'xpan', 'ypan',
• icon:

The pan tool allows the user to pan the plot by left-dragging a mouse or dragging a finger across the plot region.

It is also possible to constrain the pan tool to only act on either just the x-axis or just the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool aliases 'xpan' and 'ypan', respectively.

PolySelectTool¶

• name: 'poly_select'
• icon:

The polygon selection tool allows the user to define an arbitrary polygonal region for selection by left-clicking a mouse, or tapping a finger at different locations.

TapTool¶

• name: 'tap'
• icon:

The tap selection tool allows the user to select at single points by clicking a left mouse button, or tapping with a finger.

WheelZoomTool¶

• name: 'wheel_zoom', 'xwheel_zoom', 'ywheel_zoom'
• icon:

The wheel zoom tool will zoom the plot in and out, centered on the current mouse location. It will respect any min and max values and ranges preventing zooming in and out beyond these.

It is also possible to constraint the wheel zoom tool to only act on either just the x-axis or just the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool aliases 'xwheel_zoom' and 'ywheel_zoom', respectively.

WheelPanTool¶

• name: 'xwheel_pan', 'ywheel_pan'
• icon:

The wheel pan tool will translate the plot window along the specified dimension without changing the window’s aspect ratio. The tool will respect any min and max values and ranges preventing panning beyond these values.

UndoTool¶

• name: 'undo'
• icon:

The undo tool allows to restore previous state of the plot.

RedoTool¶

• name: 'redo'
• icon:

The redo tool reverses the last action performed by undo tool.

ResetTool¶

• name: 'reset'
• icon:

The reset tool will restore the plot ranges to their original values.

SaveTool¶

• name: 'save'
• icon:

The save tool pops up a modal dialog that allows the user to save a PNG image of the plot.

ZoomInTool¶

• name: 'zoom_in', 'xzoom_in', 'yzoom_in'
• icon:

The zoom-in tool will increase the zoom of the plot. It will respect any min and max values and ranges preventing zooming in and out beyond these.

It is also possible to constraint the wheel zoom tool to only act on either just the x-axis or just the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool aliases 'xzoom_in' and 'yzoom_in', respectively.

ZoomOutTool¶

• name: 'zoom_out', 'xzoom_out', 'yzoom_out'
• icon:

The zoom-out tool will decrease the zoom level of the plot. It will respect any min and max values and ranges preventing zooming in and out beyond these.

It is also possible to constraint the wheel zoom tool to only act on either just the x-axis or just the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool aliases 'xzoom_in' and 'yzoom_in', respectively.

CrosshairTool¶

• name: 'crosshair'
• menu icon:

Th crosshair tool draws a crosshair annotation over the plot, centered on the current mouse position. The crosshair tool draw dimensions may be configured by setting the dimensions property to one of the enumerated values width, height, or both.

HoverTool¶

• name: 'hover'
• menu icon:

The hover tool is a passive inspector tool. It is generally on at all times, but can be configured in the inspector’s menu associated with the toolbar.

Basic Tooltips¶

By default, the hover tool will generate a “tabular” tooltip where each row contains a label, and its associated value. The labels and values are supplied as a list of (label, value) tuples. For instance, the tooltip below on the left was created with the accompanying tooltips definition on the right.

hover.tooltips = [ ("index", "$index"), ("(x,y)", "($x, $y)"), ("radius", "@radius"), ("fill color", "$color[hex, swatch]:fill_color"), ("foo", "@foo"), ("bar", "@bar"), ]

Field names that begin with $ are “special fields”. These often correspond to values that are intrinsic to the plot, such as the coordinates of the mouse in data or screen space. These special fields are listed here:

$index:	index of selected point in the data source
$x:	x-coordinate under the cursor in data space
$y:	y-coordinate under the cursor in data space
$sx:	x-coordinate under the cursor in screen (canvas) space
$sy:	y-coordinate under the cursor in screen (canvas) space
$color:	colors from a data source, with the syntax: $color[options]:field_name. The available options are: hex (to display the color as a hex value), and swatch to also display a small color swatch.

Field names that begin with @ are associated with columns in a ColumnDataSource. For instance the field name "@price" will display values from the "price" column whenever a hover is triggered. If the hover is for the 17th glyph, then the hover tooltip will correspondingly display the 17th price value.

Note that if a column name contains spaces, the it must be supplied by surrounding it in curly braces, e.g. @{adjusted close} will display values from a column named "adjusted close".

Here is a complete example of how to configure and use the hover tool with a default tooltip:

from bokeh.plotting import figure, output_file, show, ColumnDataSource
from bokeh.models import HoverTool

output_file("toolbar.html")

source = ColumnDataSource(data=dict(
    x=[1, 2, 3, 4, 5],
    y=[2, 5, 8, 2, 7],
    desc=['A', 'b', 'C', 'd', 'E'],
))

hover = HoverTool(tooltips=[
    ("index", "$index"),
    ("(x,y)", "($x, $y)"),
    ("desc", "@desc"),
])

p = figure(plot_width=400, plot_height=400, tools=[hover],
           title="Mouse over the dots")

p.circle('x', 'y', size=20, source=source)

show(p)

"@foo{0,0.000}"    # formats 10000.1234 as: 10,000.123

"@foo{(.00)}"      # formats -10000.1234 as: (10000.123)

"@foo{($ 0.00 a)}" # formats 1230974 as: $ 1.23 m

hover_tool.formatters = { "close date": "datetime"}

HoverTool(
    tooltips=[
        ( 'date',   '@date{%F}'            ),
        ( 'close',  '$@{adj close}{%0.2f}' ), # use @{ } for field names with spaces
        ( 'volume', '@volume{0.00 a}'      ),
    ],

    formatters={
        'date'      : 'datetime', # use 'datetime' formatter for 'date' field
        'adj close' : 'printf',   # use 'printf' formatter for 'adj close' field
                                  # use default 'numeral' formatter for other fields
    },

    # display a tooltip whenever the cursor is vertically in line with a glyph
    mode='vline'
)

import numpy as np
from bokeh.plotting import figure, output_file, show, ColumnDataSource
from bokeh.models import HoverTool

output_file("tools_hover_tooltip_image.html")

ramp = np.array([np.linspace(0, 10, 200)]*20)
steps = np.array([np.linspace(0, 10, 10)]*20)
bitmask = np.random.rand(25, 10) > 0.5

data = dict(image=[ramp, steps, bitmask],
            squared=[ramp**2, steps**2, bitmask**2],
            pattern=['smooth ramp', 'steps', 'bitmask'],
            x=[0, 0, 25],
            y=[5, 20, 5],
            dw=[20,  20, 10],
            dh=[10,  10, 25])

cds = ColumnDataSource(data=data)
hover = HoverTool(tooltips=[
    ('index', "$index"),
    ('pattern', '@pattern'),
    ("x", "$x"),
    ("y", "$y"),
    ("value", "@image"),
    ('squared', '@squared')], )

p = figure( x_range=(0, 35), y_range=(0, 35), tools=[hover, 'wheel_zoom'])
p.image(source=cds, image='image', x='x', y='y', dw='dw', dh='dh', palette="Inferno256")
show(p)

from bokeh.plotting import figure, output_file, show, ColumnDataSource
from bokeh.models import HoverTool

output_file("toolbar.html")

source = ColumnDataSource(data=dict(
    x=[1, 2, 3, 4, 5],
    y=[2, 5, 8, 2, 7],
    desc=['A', 'b', 'C', 'd', 'E'],
    imgs=[
        'https://bokeh.pydata.org/static/snake.jpg',
        'https://bokeh.pydata.org/static/snake2.png',
        'https://bokeh.pydata.org/static/snake3D.png',
        'https://bokeh.pydata.org/static/snake4_TheRevenge.png',
        'https://bokeh.pydata.org/static/snakebite.jpg'
    ],
    fonts=[
        '<i>italics</i>',
        '<pre>pre</pre>',
        '<b>bold</b>',
        '<small>small</small>',
        '<del>del</del>'
    ]
))

hover = HoverTool( tooltips="""
    <div>
        <div>
            <img
                src="@imgs" height="42" alt="@imgs" width="42"
                style="float: left; margin: 0px 15px 15px 0px;"
                border="2"
            ></img>
        </div>
        <div>
            <span style="font-size: 17px; font-weight: bold;">@desc</span>
            <span style="font-size: 15px; color: #966;">[$index]</span>
        </div>
        <div>
            <span>@fonts{safe}</span>
        </div>
        <div>
            <span style="font-size: 15px;">Location</span>
            <span style="font-size: 10px; color: #696;">($x, $y)</span>
        </div>
    </div>
    """
)

p = figure(plot_width=400, plot_height=400, tools=[hover],
           title="Mouse over the dots")

p.circle('x', 'y', size=20, source=source)

show(p)

BoxEditTool¶

• name: 'box_edit'
• menu icon:

The BoxEditTool allows drawing, dragging and deleting Rect glyphs on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, the renderers that are to be edited must be supplied explicitly as a list:

r1 = p.rect('x', 'y', 'width', 'height', source=source)
r2 = p.rect('x', 'y', 'width', 'height', source=source2)
tool = BoxEditTool(renderers=[r1, r2])

The tool will automatically modify the columns on the data source corresponding to the x, y, width and height values of the glyph. Any additional columns in the data source will be padded with the declared empty_value, when adding a new box. When drawing a new box the data will always be added to the ColumnDataSource on the first supplied renderer.

The animation above shows the supported tool actions, highlighting mouse actions with a circle around the cursor and key strokes by showing the pressed keys. The BoxEditTool can Add, Move and Delete boxes on plots:

Add box

Hold shift then click and drag anywhere on the plot or double tap once to start drawing, move the mouse and double tap again to finish drawing.

Move box

Click and drag an existing box, the box will be dropped once you let go of the mouse button.

Delete box

Tap a box to select it then press BACKSPACE key while the mouse is within the plot area.

To Move or Delete multiple boxes at once:

Move selection

Select box(es) with SHIFT+tap (or another selection tool) then drag anywhere on the plot. Selecting and then dragging on a specific box will move both.

Delete selection

Select box(es) with SHIFT+tap (or another selection tool) then press BACKSPACE while the mouse is within the plot area.

PointDrawTool¶

• name: 'point_draw'
• menu icon:

The PointDrawTool allows adding, dragging and deleting point-like glyphs (of XYGlyph type) on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, the renderers that are to be edited must be supplied explicitly as a list:

c1 = p.circle('x', 'y', 'width', 'height', source=source)
r1 = p.rect('x', 'y', 0.1, 0.1, source=source2)
tool = BoxEditTool(renderers=[c1, r1])

The tool will automatically modify the columns on the data source corresponding to the x and y values of the glyph. Any additional columns in the data source will be padded with the declared empty_value, when adding a new point. Any newly added points will be inserted on the ColumnDataSource of the first supplied renderer.

The animation above shows the supported tool actions, highlighting mouse actions with a circle around the cursor and key strokes by showing the pressed keys. The PointDrawTool can Add, Move and Delete point-like glyphs on plots:

Add point

Tap anywhere on the plot

Move point

Tap and drag an existing point, the point will be dropped once you let go of the mouse button.

Delete point

Tap a point to select it then press BACKSPACE key while the mouse is within the plot area.

To Move or Delete multiple points at once:

Move selection

Select point(s) with SHIFT+tap (or another selection tool) then drag anywhere on the plot. Selecting and then dragging a specific point will move both.

Delete selection

Select point(s) with SHIFT+tap (or another selection tool) then press BACKSPACE while the mouse is within the plot area.

PolyDrawTool¶

• name: 'poly_draw'
• menu icon:

The PolyDrawTool allows drawing, selecting and deleting Patches and MultiLine glyphs on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, the renderers that are to be edited must be supplied explicitly as a list.

The tool will automatically modify the columns on the data source corresponding to the xs and ys values of the glyph. Any additional columns in the data source will be padded with the declared empty_value, when adding a new point. Any newly added patch or multi-line will be inserted on the ColumnDataSource of the first supplied renderer.

The animation above shows the supported tool actions, highlighting mouse actions with a circle around the cursor and key strokes by showing the pressed keys. The PolyDrawTool can Add, Move and Delete patches and multi-lines:

Add patch/multi-line

Double tap to add the first vertex, then use tap to add each subsequent vertex, to finalize the draw action double tap to insert the final vertex or press the ESC key.

Move patch/multi-line

Tap and drag an existing patch/multi-line, the point will be dropped once you let go of the mouse button.

Delete patch/multi-line

Tap a patch/multi-line to select it then press BACKSPACE key while the mouse is within the plot area.

PolyEditTool¶

• name: 'poly_edit'
• menu icon:

The PolyEditTool allows editing the vertices of one or more Patches or MultiLine glyphs. The glyphs to be edited can be defined via the renderers property and the renderer for the vertices can be defined via the vertex_renderer, which must render a point-like Glyph (of XYGlyph type).

The tool will automatically modify the columns on the data source corresponding to the xs and ys values of the glyph. Any additional columns in the data source will be padded with the declared empty_value, when adding a new point.

The animation above shows the supported tool actions, highlighting mouse actions with a circle around the cursor and key strokes by showing the pressed keys. The PolyEditTool can Add, Move and Delete vertices on existing patches and multi-lines:

Show vertices

Double tap an existing patch or multi-line

Add vertex

Double tap an existing vertex to select it, the tool will draw the next point, to add it tap in a new location. To finish editing and add a point double tap otherwise press the ESC key to cancel.

Move vertex

Drag an existing vertex and let go of the mouse button to release it.

Delete vertex

After selecting one or more vertices press BACKSPACE while the mouse cursor is within the plot area.