Get startedGet started for free

Configuration tools

1. Configuration tools

Well done so far! Now let's walk through some of the configuration tools Bokeh has on offer and their uses.

2. The default toolbar

Notice the buttons along the right-hand side of the plot? This is called the toolbar. At the top is the Bokeh logo, linking to the website, and at the bottom is a question mark, which opens the configuration tools documentation. In between, there are 5 tools by default, running from top to bottom: PanTool, BoxZoomTool, WheelZoomTool, Save, and Reset. Each tool name is listed, with its code syntax and icon beneath.

3. Configuration tools

Bokeh has 6 groups of tools; we will introduce three of these - Pan/Drag, Click/Tap, and Scroll/Pinch, and show how they can be included in a toolbar. We will also cover HoverTool, a type of Inspector, later in the chapter. Actions, Edit tools, and other Inspectors are outside the scope of this course. A link to the configuration tools documentation is included in the slide.

4. Pan/drag tools

Pan/drag tools are used to select an area of a plot. There are four tools in this category, used by our mouse on desktop or by hand if we are on a touch-screen device. PanTool is used to drag the plot in a direction of our choice. On the right, we can see pan in action. BoxSelectTool enables us to draw a rectangular selection, which highlights observations within the selection and shades out everything else. BoxZoomTool also allows rectangular selections but will instead zoom the plot, so the edges of the selection are the new boundaries for the view. Lastly, LassoSelectTool is used to make a selection of any shape. The image on the right shows the effect of Lasso Select.

5. Click/tap tools

Click/tap tools allow us to click or tap on points to highlight either single observations or selections. There are two tools: PolySelectTool allows a polygon selection using multiple clicks or taps, depending on the device we use, and is shown on the right. TapTool is used to select a single observation. If we have a legend and multiple categories, then, by default, this will highlight the selected observation along with any from different categories. It can therefore be useful to contrast with other groups. Here is an example in the bottom right.

6. Scroll/pinch tools

There are two scroll/pinch tools, both of which use the mouse wheel. First is WheelZoomTool, where the mouse wheel allows us to zoom in on wherever we have hovered within the plot. The top right-hand corner shows it in action. WheelPanTool enables the mouse wheel to scroll left to right or top to bottom, depending on whether we specify xwheel pan or ywheel pan.

7. Customizing the toolbar

There are two ways to change the tools in a toolbar. We can import the specific tool we require from bokeh-dot-models; for example, the first line imports BoxSelectTool. We create our figure and add glyphs, then we call fig-dot-add tools, calling the tool we imported. This adds the specified tool while keeping the default tools, so is useful if we just need to include one more tool.

8. Custom list of tools

Alternatively, if we need a custom set of tools, we can create a list. We then set up our figure and pass our list to the tools keyword argument. This replaces default tools with only those we manually included, so tends to be the best approach if we need three or more specific tools.

9. Let's practice!

As we saw, Bokeh's configuration tools have extensive functionality and offer solutions to many use-cases. Let's put these tools to use!