Configuring plot tools¶

BoxSelectTool¶

• name: 'box_select'

• icon:

The box selection tool allows you to define a rectangular selection by left-dragging a mouse, or dragging a finger across the plot area. You can configure the box select tool to select across only one dimension by setting the dimensions property to width or height instead of the default both.

After a selection is made, the indices of the selected points are available from properties on the Selection object for a glyph data source. For example:

source.selected.indices

will hold the selected indices in the common case of a “scatter” type glyph.

BoxZoomTool¶

• name: 'box_zoom'

• icon:

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

LassoSelectTool¶

• name: 'lasso_select'

• icon:

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

After a selection is made, the indices of the selected points are available from properties on the Selection object for a glyph data source. For example:

source.selected.indices

will hold the selected indices in the common case of a “scatter” type glyph.

PanTool¶

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

• icon:

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

You can configure the pan tool to act only on either the x-axis or the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool names 'xpan' and 'ypan', respectively.

PolySelectTool¶

• name: 'poly_select'

• icon:

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

After a selection is made, the indices of the selected points are available from properties on the Selection object for a glyph data source. For example:

source.selected.indices

will hold the selected indices in the common case of a “scatter” type glyph.

TapTool¶

• name: 'tap'

• icon:

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

After a selection is made, the indices of the selected points are available from properties on the Selection object for a glyph data source. For example:

source.selected.indices

will hold the selected indices in the common case of a “scatter” type glyph.

WheelZoomTool¶

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

• icon:

You can use the wheel zoom tool to zoom the plot in and out, centering on the current mouse location. It will respect any min and max values and ranges, preventing zooming in and out beyond these values.

You can configure the wheel zoom tool to act only on either the x-axis or the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool names 'xwheel_zoom' and 'ywheel_zoom', respectively.

WheelPanTool¶

• name: 'xwheel_pan', 'ywheel_pan'

• icon:

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

UndoTool¶

• name: 'undo'

• icon:

The undo tool restores the previous state of the plot.

RedoTool¶

• name: 'redo'

• icon:

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

ResetTool¶

• name: 'reset'

• icon:

The reset tool restores the plot ranges to their original values.

SaveTool¶

• name: 'save'

• icon:

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

ZoomInTool¶

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

• icon:

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

You can configure the wheel zoom tool to act only on either the x-axis or the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool names 'xzoom_in' and 'yzoom_in', respectively.

ZoomOutTool¶

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

• icon:

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

You can configure the wheel zoom tool to act only on either the x-axis or the y-axis by setting the dimensions property to a list containing width or height. Additionally, there are tool names 'xzoom_in' and 'yzoom_in', respectively.

CrosshairTool¶

• name: 'crosshair'

• menu icon:

The crosshair tool draws a crosshair annotation over the plot, centered on the current mouse position. You can configure the crosshair tool dimensions by setting the dimensions property to width, height, or both.

HoverTool¶

• name: 'hover'

• menu icon:

The hover tool is a passive inspector tool. It defaults to be on at all times, but you can change this in the inspector’s menu in the toolbar.

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

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

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'],
))

TOOLTIPS = [
    ("index", "$index"),
    ("(x,y)", "($x, $y)"),
    ("desc", "@desc"),
]

p = figure(width=400, height=400, tooltips=TOOLTIPS,
           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"}

hover_tool.formatters = { "$x": "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

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])

TOOLTIPS = [
    ('name', "$name"),
    ('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', tooltips=TOOLTIPS)
p.image(source=data, image='image', x='x', y='y', dw='dw', dh='dh', palette="Inferno256", name="Image Glyph")

show(p)

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

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://docs.bokeh.org/static/snake.jpg',
        'https://docs.bokeh.org/static/snake2.png',
        'https://docs.bokeh.org/static/snake3D.png',
        'https://docs.bokeh.org/static/snake4_TheRevenge.png',
        'https://docs.bokeh.org/static/snakebite.jpg'
    ],
    fonts=[
        '<i>italics</i>',
        '<pre>pre</pre>',
        '<b>bold</b>',
        '<small>small</small>',
        '<del>del</del>'
    ]
))

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(width=400, height=400, tooltips=TOOLTIPS,
           title="Mouse over the dots")

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

show(p)

BoxEditTool¶

• name: 'box_edit'

• menu icon:

The BoxEditTool() allows you to draw, drag, and delete Rect glyphs on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, you must pass the renderers to be edited 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 automatically modifies the columns of 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 point. Any newly added points will be inserted in the ColumnDataSource of the first supplied renderer.

It is often useful to limit the number of elements that can be drawn. For example, when specifying a certain number of regions of interest. Using the num_objects property, you can ensure that once the limit has been reached, the oldest box will be popped off the queue to make space for the newest box being added.

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 the 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.

FreehandDrawTool¶

• name: 'freehand_draw'

• menu icon:

The FreehandDrawTool() allows freehand drawing of lines and polygons using the Patches and MultiLine glyphs, by editing the underlying ColumnDataSource data. Like other drawing tools, you must pass the renderers to be edited as a list:

r = p.multi_line('xs', 'ys' source=source)
tool = FreehandDrawTool(renderers=[r])

The tool automatically modifies 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 points will be inserted in the ColumnDataSource of the first supplied renderer.

It is also often useful to limit the number of elements that can be drawn. For example, when specifying a specific number of regions of interest. Using the num_objects property, you can ensure that once the limit has been reached, the oldest patch/multi-line will be popped off the queue to make space for the new patch/multi-line being added.

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 Draw and Delete patches and multi-lines:

Draw patch/multi-line

Click and drag to start drawing and release the mouse button to finish drawing.

Delete patch/multi-line

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

To Delete multiple patches/lines at once:

Delete selection

Select patches/lines 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 you to add, drag, and delete point-like glyphs (of XYGlyph type) on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, you must pass the renderers to be edited as a list:

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

The tool automatically modifies 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 in the ColumnDataSource of the first supplied renderer.

It is also often useful to limit the number of elements that can be drawn. Using the num_objects property, you can ensure that once the limit has been reached, the oldest point will be popped off the queue to make space for the new point being added.

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 you to draw, select, and delete Patches and MultiLine glyphs on one or more renderers by editing the underlying ColumnDataSource data. Like other drawing tools, you must pass the renderers to be edited as a list.

The tool automatically modifies 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.

It is also often useful to limit the number of elements that can be drawn. For example, when specifying a specific number of regions of interest. Using the num_objects property, you can ensure that once the limit has been reached the oldest patch/multi-line will be popped off the queue to make space for the new patch/multi-line being added.

If a vertex_renderer with a point-like glyph is supplied, the PolyDrawTool will use it to display the vertices of the multi-lines/patches on all supplied renderers. This also enables the ability to snap to existing vertices while drawing.

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 the BACKSPACE key while the mouse is within the plot area.

PolyEditTool¶

• name: 'poly_edit'

• menu icon:

The PolyEditTool() allows you to edit the vertices of one or more Patches or MultiLine glyphs. You can define the glyphs to be edited with the renderers property. You can define the renderer for the vertices with the vertex_renderer. It must render a point-like Glyph (of XYGlyph type).

The tool automatically modifies 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.