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",
)
# chage 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 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,
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)
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:
Import the
HoverTool
class frombokeh.models.tools
.Include
HoverTool()
in the list passed to thetools
argument when calling thefigure()
function.Include the
tooltips
argument when calling thefigure()
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.