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, plot_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 plot_height and plot_width 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",
    plot_width=350,
    plot_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",
    plot_width=350,
    plot_height=250,
    x_axis_label="x",
    y_axis_label="y",
)

# chage plot size
p.plot_width = 450
p.plot_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",
    plot_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,
    plot_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,
    plot_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’s models collection:

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,
    plot_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",
    plot_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,
    plot_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,
    plot_height=250,
)

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

# change just some things about the x-grid
p.xgrid.grid_line_color = "red"

# change just some things about 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,
    plot_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,
    plot_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.

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:

Import the HoverTool class from bokeh.models.tools.
Include HoverTool() in the list passed to the tools argument when calling the figure() function.
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.tools 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,
    plot_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.

First steps 4: Customizing your plot¶

Using Themes¶

Resizing your plot¶

Setting width and height¶

Enabling responsive plot sizing¶

Customizing axes¶

Setting your axes’ appearance¶

Defining axis ranges¶

Formatting axis ticks¶

Enabling logarithmic axes¶

Enabling datetime axes¶

Customizing the grid¶

Styling lines¶

Using bands and bounds¶

Setting background colors¶

Customizing the toolbar¶

Positioning the toolbar¶

Deactivating and hiding the toolbar¶

Customizing available tools¶

Adding tooltips¶