First steps 4: Customizing your plot#

In the previous first steps guides, you generated different glyphs and added more information such as a title, legend, and annotations.

In this section, you will customize the appearance of the plot as a whole. This includes resizing your plot, changing its lines and colors, and customizing the axes and tools.

Using Themes#

With Bokeh’s themes, you can quickly change the appearance of your plot. Themes are a set of pre-defined design parameters such as colors, fonts, or line styles.

Bokeh comes with five built-in themes: caliber, dark_minimal, light_minimal, night_sky, and contrast. Additionally, you can define your own custom themes.

To use one of the built-in themes, assign the name of the theme you want to use to the theme property of your document:

from bokeh.io import curdoc
from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# apply theme to current document
curdoc().theme = "dark_minimal"

# create a plot
p = figure(sizing_mode="stretch_width", max_width=500, height=250)

# add a renderer
p.line(x, y)

# show the results
show(p)

You can also create your own themes to use across multiple plots. Bokeh’s themes can be either in a YAML or JSON format. To learn more about creating and using customized themes, see Creating custom themes in the user guide.

See also

For more information on using themes with Bokeh, see Using themes in the user guide and bokeh.themes in the reference guide.

Resizing your plot#

Bokeh’s Plot objects have various attributes that influence the way your plot looks.

Setting width and height#

To set the size of your plot, use the attributes width and height when calling the figure() function:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a new plot with a specific size
p = figure(
    title="Plot sizing example",
    width=350,
    height=250,
    x_axis_label="x",
    y_axis_label="y",
)

# add circle renderer
circle = p.circle(x, y, fill_color="red", size=15)

# show the results
show(p)
⋯

Similar to changing the design of an existing glyph, you can change a plot’s attributes at any time after its creation:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a new plot with a specific size
p = figure(
    title="Plot resizing example",
    width=350,
    height=250,
    x_axis_label="x",
    y_axis_label="y",
)

# change plot size
p.width = 450
p.height = 150

# add circle renderer
circle = p.circle(x, y, fill_color="red", size=15)

# show the results
show(p)
⋯

Enabling responsive plot sizing#

To make your plot automatically adjust to your browser or screen size, use the attribute sizing_mode:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a new plot with responsive width
p = figure(
    title="Plot responsive sizing example",
    sizing_mode="stretch_width",
    height=250,
    x_axis_label="x",
    y_axis_label="y",
)

# add circle renderer
circle = p.circle(x, y, fill_color="red", size=15)

# show the results
show(p)
⋯

See also

To learn more about how to control the size of plots, see Styling plots in the user guide and the entry for Plot in the reference guide.

For more information on responsive sizing, see Sizing modes in the user guide and sizing_mode in the reference guide.

Customizing axes#

You can set various attributes to change the way the axes in your plot work and look.

Setting your axes’ appearance#

Options for customizing the appearance of your plot include:

  • setting labels for your axes

  • styling the numbers displayed with your axes

  • defining colors and other layout properties for the axes themselves

For example:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Customized axes example",
    sizing_mode="stretch_width",
    max_width=500,
    height=350,
)

# add a renderer
p.circle(x, y, size=10)

# change some things about the x-axis
p.xaxis.axis_label = "Temp"
p.xaxis.axis_line_width = 3
p.xaxis.axis_line_color = "red"

# change some things about the y-axis
p.yaxis.axis_label = "Pressure"
p.yaxis.major_label_text_color = "orange"
p.yaxis.major_label_orientation = "vertical"

# change things on all axes
p.axis.minor_tick_in = -3
p.axis.minor_tick_out = 6

# show the results
show(p)

Defining axis ranges#

When drawing the axes for your plot, Bokeh automatically determines the range each axis needs to cover in order to display all your values. For example, if the values on your y-axis are between 2 and 17, Bokeh automatically creates a y-axis that ranges from a little below 2 to a little above 17.

To define the range for your axes manually, use the y_range() function or the y_range() properties of your Plot object when you call the figure() function:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a new plot with responsive width
p = figure(
    y_range=(0, 25),
    title="Axis range example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add circle renderer with additional arguments
circle = p.circle(x, y, size=8)

# show the results
show(p)
⋯

Formatting axis ticks#

You can format the text that appears alongside your axes with Bokeh’s TickFormatter objects. Use these formatters to display currency symbols on your y-axis, for example:

⋯

To display dollar amounts instead of just numbers on your y-axis, use the NumeralTickFormatter:

First, import the NumeralTickFormatter from bokeh.models:

from bokeh.models import NumeralTickFormatter

Then, after creating your plot with the figure() function, assign the NumeralTickFormatter to the formatter property of your plot’s yaxis:

p.yaxis[0].formatter = NumeralTickFormatter(format="$0.00")

The NumeralTickFormatter supports different formats, including "$0.00" to generate values such as "$7.42".

This is what the completed code looks like:

from bokeh.models import NumeralTickFormatter
from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create new plot
p = figure(
    title="Tick formatter example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# format axes ticks
p.yaxis[0].formatter = NumeralTickFormatter(format="$0.00")

# add renderers
p.circle(x, y, size=8)
p.line(x, y, color="navy", line_width=1)

# show the results
show(p)

See also

For more information about formatting ticks, see Tick label formats in the user guide. For a list of all available tick formatters, see formatters in the reference guide.

Enabling logarithmic axes#

You can also change the axis type altogether. Use y_axis_type="log" to switch to logarithmic axes:

from bokeh.plotting import figure, show

# prepare some data
x = [0.1, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
y0 = [i**2 for i in x]
y1 = [10**i for i in x]
y2 = [10**(i**2) for i in x]

# create a new plot with a logarithmic axis type
p = figure(
    title="Logarithmic axis example",
    sizing_mode="stretch_width",
    height=300,
    max_width=500,
    y_axis_type="log",
    y_range=[0.001, 10 ** 11],
    x_axis_label="sections",
    y_axis_label="particles",
)

# add some renderers
p.line(x, x, legend_label="y=x")
p.circle(x, x, legend_label="y=x", fill_color="white", size=8)
p.line(x, y0, legend_label="y=x^2", line_width=3)
p.line(x, y1, legend_label="y=10^x", line_color="red")
p.circle(x, y1, legend_label="y=10^x", fill_color="red", line_color="red", size=6)
p.line(x, y2, legend_label="y=10^x^2", line_color="orange", line_dash="4 4")

# show the results
show(p)

Enabling datetime axes#

Set the x_axis_type or y_axis_type to datetime to display date or time information on an axis. Bokeh then creates a DatetimeAxis.

To format the ticks of a DatetimeAxis, use the DatetimeTickFormatter.

import random
from datetime import datetime, timedelta

from bokeh.models import DatetimeTickFormatter, NumeralTickFormatter
from bokeh.plotting import figure, show

# generate list of dates (today's date in subsequent weeks)
dates = [(datetime.now() + timedelta(day * 7)) for day in range(0, 26)]

# generate 25 random data points
y = random.sample(range(0, 100), 26)

# create new plot
p = figure(
    title="datetime axis example",
    x_axis_type="datetime",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add renderers
p.circle(dates, y, size=8)
p.line(dates, y, color="navy", line_width=1)

# format axes ticks
p.yaxis[0].formatter = NumeralTickFormatter(format="$0.00")
p.xaxis[0].formatter = DatetimeTickFormatter(months="%b %Y")

# show the results
show(p)
⋯

See also

See Styling axes in the user guide for more information on customizing axes. The entry for Axis in the reference guide contains a list of all available attributes you can use to customize the axes of your plot.

Customizing the grid#

To change the appearance of the grid, set the various properties of the xgrid(), ygrid(), and grid() methods of your Plot object.

Styling lines#

Change what the horizontal and vertical lines of your grid look like by setting the various grid_line properties:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Customized grid lines example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add a renderer
p.line(x, y, line_color="green", line_width=2)

# change things only on the x-grid
p.xgrid.grid_line_color = "red"

# change things only on the y-grid
p.ygrid.grid_line_alpha = 0.8
p.ygrid.grid_line_dash = [6, 4]

# show the results
show(p)
⋯

See also

For more information on lines and minor lines, see Lines in the user guide.

Using bands and bounds#

Another way to make reading your plot easier is to use bands and bounds.

Bands and bounds are more examples of the annotations you learned about in Using annotations.

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Bands and bonds example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add a renderer
p.line(x, y, line_color="green", line_width=2)

# add bands to the y-grid
p.ygrid.band_fill_color = "olive"
p.ygrid.band_fill_alpha = 0.1

# define vertical bonds
p.xgrid.bounds = (2, 4)

# show the results
show(p)
⋯

See also

For more information on styling bands and bounds, see Bands and Bounds in the user guide.

Setting background colors#

You have several options to define colors in Bokeh. For example:

  • Use one of the named CSS colors (for example, "firebrick")

  • Use hexadecimal values, prefaced with a # (for example "#00ff00")

  • Use a 3-tuple for RGB colors (for example, (100, 100, 255)

  • Use a 4-tuple for RGBA colors (for example (100, 100, 255, 0.5))

To change the appearance of the plane that Bokeh draws your plot elements on, use the various fill_color attributes of your Plot object:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Background colors example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add a renderer
p.line(x, y, line_color="green", line_width=2)

# change the fill colors
p.background_fill_color = (204, 255, 255)
p.border_fill_color = (102, 204, 255)
p.outline_line_color = (0, 0, 255)

# show the results
show(p)
⋯

See also

For more information on colors in Bokeh, see the entry for Color in the reference guide.

Customizing the toolbar#

Bokeh comes with a powerful toolbar to explore plots. You saw those tools in your very fist visualization, as part of first step guide 1.

Positioning the toolbar#

To define the position of the toolbar, use the toolbar_location attribute with one of these values: above, below, left, right

Pass a value to toolbar_location when creating your figure:

p = figure(title="Toolbar positioning example", toolbar_location="below")

Another option is to change the attribute toolbar_location at any time after creating your figure:

p.toolbar_location = "below"

Deactivating and hiding the toolbar#

To deactivate the toolbar completely, set toolbar_location to None.

p.toolbar_location = None

To make your toolbar hide automatically, set autohide to True:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Toolbar autohide example",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# activate toolbar autohide
p.toolbar.autohide = True

# add a renderer
p.line(x, y)

# show the results
show(p)

With autohide set to True, Bokeh will hide the toolbar unless the mouse is inside the plot area or you tap inside the plot area:

⋯

Similarly, use the logo property of the Toolbar to deactivate the Bokeh logo:

p.toolbar.logo = None

Customizing available tools#

You can customize which tools Bokeh displays in the toolbar. For a detailed list of all available tools, see Configuring plot tools in the user guide.

To customize which tools to use, you first need to import the relevant tools. For example:

from bokeh.models.tools import BoxZoomTool, ResetTool

Next, define which tools to use when creating a new figure by passing the tools attribute to the figure() function.

The tools attribute accepts a list of tools. This example enables only the BoxZoomTool and ResetTool:

p = figure(tools = [BoxZoomTool(), ResetTool()])

This way, only the box zoom tool and the reset tool will be available in the toolbar:

To change the available tools at any time after creating your figure, you need to use the add_tools() function.

All tools also offer various properties to define how they can be used. With the PanTool, for example, you can limit the movement to only horizontal or vertical panning. The default behavior is to allow panning in both directions.

from bokeh.models import BoxZoomTool, PanTool, ResetTool
from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

# create a plot
p = figure(
    title="Modifying tools example",
    tools=[BoxZoomTool(), ResetTool()],
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add an additional pan tool
# only vertical panning is allowed
p.add_tools(PanTool(dimensions="width"))

# add a renderer
p.circle(x, y, size=10)

# show the results
show(p)

In this example, you first include the box zoom tool and the reset tool when creating your function. Next, you add a pan zoom tool. This results in all three tools being available:

See also

To learn more about tools and toolbars, see Configuring plot tools. For detailed information about all tools and their respective properties, see tools and Toolbar in the reference guide.

Adding tooltips#

Tooltips are little windows that appear when you hover your mouse over a data point or when you tap on a data point:

Tooltips are based on the HoverTool. The hover tool is part of Bokeh’s toolbar.

There are several ways to enable tooltips in Bokeh. This is the quickest:

  1. Import the HoverTool class from bokeh.models.tools.

  2. Include HoverTool() in the list passed to the tools argument when calling the figure() function.

  3. Include the tooltips argument when calling the figure() function.

The tooltips argument accepts a string with a special syntax. Use the “@” symbol to include the name of the source for the data you want Bokeh to display. This example includes @x and @y. When the browser displays a tooltip, Bokeh replaces both those fields with the actual data from the lists x and y .

This is what the code looks like:

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

# prepare some data
x = [1, 2, 3, 4, 5]
y = [4, 5, 5, 7, 2]

p = figure(
    y_range=(0, 10),
    toolbar_location=None,
    tools=[HoverTool()],
    tooltips="Data point @x has the value @y",
    sizing_mode="stretch_width",
    max_width=500,
    height=250,
)

# add renderers
p.circle(x, y, size=10)
p.line(x, y, line_width=2)

# show the results
show(p)

See also

The user guide contains much more information on using the hover tool to create tooltips. See Basic Tooltips for more details. More information is also available at the entry for HoverTool in the reference guide.