Styling Visual Attributes
Palettes are sequences (lists or tuples) of RGB(A) hex strings that define a
colormap and be can set as the palette attribute of all chart types from
bokeh.charts and as the color attribute of many plot objects from
bokeh.plotting. Bokeh offers many of the standard Brewer palettes, which
can be imported from the bokeh.palettes module. For example, importing
“Spectral6” gives a six element list of RBG(A) hex strings from the Brewer
“Spectral” colormap.
>>> from bokeh.palettes import Spectral6
>>> Spectral6
['#3288bd', '#99d594', '#e6f598', '#fee08b', '#fc8d59', '#d53e4f']
All of the standard palettes included in bokeh can be found at
Standard Palettes. Custom palettes can be made by creating sequences of
RGB(A) hex strings.
In order to style the visual attributes of Bokeh plots, you first must
know what the available properties are. The full Reference Guide will
list all the properties of every object individually, though there are three
broad groups of properties that show up often. They are:
- line properties line color, width, etc.
- fill properties fill color, alpha, etc.
- text properties font styles, colors, etc.
Below is more detail about each of these.
line_color- color to use to stroke lines with
line_width- line stroke width in units of pixels
line_alpha- floating point between 0 (transparent) and 1 (opaque)
line_joinhow path segments should be joined together
line_caphow path segments should be terminated
line_dash- array of integer pixel distances that describe the on-off pattern of dashing to use
line_dash_offset- the distance in pixels into the
line_dash that the pattern should start from
fill_color- color to use to fill paths with
fill_alpha- floating point between 0 (transparent) and 1 (opaque)
text_font- font name, e.g.,
'times', 'helvetica'
text_font_size- font size in px, em, or pt, e.g.,
'12pt', '1.5em'
text_font_stylefont style to use
'normal' normal text'italic' italic text'bold' bold text
text_color- color to use to render text with
text_alpha- floating point between 0 (transparent) and 1 (opaque)
text_align- horizontal anchor point for text:
'left', 'right', 'center'
text_baselinevertical anchor point for text
'top''middle''bottom''alphabetic''hanging'
Note
There is currently only support for filling text. An interface to stroke
the outlines of text has not yet been exposed.
Colors properties are used in many places in Bokeh, to specify the colors to
use for lines, fills or text. Color values can be provided in any of the
following ways:
- any of the 147 named CSS colors, e.g
'green', 'indigo'
- an RGB(A) hex value, e.g.,
'#FF0000', '#44444444'
- a 3-tuple of integers (r,g,b) between 0 and 255
- a 4-tuple of (r,g,b,a) where r, g, b are integers between 0 and 255 and a is a floating point value between 0 and 1
Color alpha can be specified in multiple ways for the visual properties. This
can be by specifying the alpha directly with line|fill_alpha, or by
providing the alpha through the RGBA 4-tuple for the line|fill_color.
Additionally, there is also the freedom to use a combination of the two, or no
alpha at all. The following figure demonstrates each possible combination of
the inputs for line and fill alphas:
Note
If using the bokeh.plotting interface, another option is to specify
color and/or alpha as a keyword, as well as the demonstrated color
properties. These inputs work by applying the provided value to both of the
corresponding line and fill properties. However, you can still
provide fill|line_alpha or fill|line_color in combination with
the color/alpha keywords, and the former will take precedence.
As described in Defining Key Concepts, Bokeh plots comprise graphs of
objects that represent all the different parts of the plot: grids, axes,
glyphs, etc. In order to style Bokeh plots, it is necessary to first find
the right object, then set its various attributes. Some objects have
convenience methods to help find the objects of interest (see Axes,
Grids, and Legends). But there is also a select() method on Plot
that can be used to query for Bokeh plot objects more generally.
For example, you can query for objects by type. The following snippet
returns all the PanTool objects a plot has:
>>> p.select(type=PanTool)
[<bokeh.models.tools.PanTool at 0x106608b90>]
The select() method can query on other attributes as well:
>>> p.circle(0, 0, name="mycircle")
<bokeh.plotting.Figure at 0x106608810>
>>> p.select(name="mycircle")
[<bokeh.models.renderers.GlyphRenderer at 0x106a4c810>]
This sort of query can be especially useful for styling visual attributes
of Glyphs.
Plot objects themselves have many visual characteristics that can be styled:
the dimensions of the plot, backgrounds, borders, outlines, etc. This section
describes how to change these attributes of a Bokeh plot. The example code
primarily uses the bokeh.plotting interface to create plots, however the
instructions apply regardless of how a Bokeh plot was created.
The dimensions (width and height) of a Plot are controlled by plot_width
and plot_height attributes. These values are in screen units, and they
control the size of the entire canvas area, including any axes or titles (but
not the toolbar). If you are using the bokeh.plotting or bokeh.charts
interfaces, then these values can be passed to figure() or the Chart function
as a convenience:
from bokeh.plotting import figure, output_file, show
output_file("dimensions.html")
# create a new plot with a title
p = figure(plot_width=700)
p.plot_height = 300
p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)
show(p)
In addition, you can use the responsive attribute. The responsive attribute
causes the plot to fill the container it’s sitting in, and to respond to
changes in browser size. Responsive web elements are common-place in web
development and the responsive flag may be useful if you are trying to
present your plot on a website where you want it to conform to a number of
browsers. If you set the responsive flag, the plot_width and plot_height will
immediately change when a plot is rendered to fill the container. However,
those parameters will be used to calculate the initial aspect ratio for your
plot, so you may want to keep them. Plots will only resize down to a minimum of
100px (height or width) to prevent problems in displaying your plot.
Warning
This feature is known not to work when combined with HBox.
This is a new feature and may have other issues when used in different circumstances.
Please report these issues on the Bokeh GitHub repository or the Bokeh mailing list.
The styling of the plot title is controlled by a set of Text Properties
on the Plot, that are prefixed with title_. For instance, to set the
color of the title text, use title_text_color:
from bokeh.plotting import figure, output_file, show
output_file("title.html")
# create a new plot with a title
p = figure(plot_width=400, plot_height=400, title="Some Title")
p.title_text_color = "olive"
p.title_text_font = "times"
p.title_text_font_style = "italic"
p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)
show(p)
The background fill color is controlled by the background_fill property
of the Plot object:
from bokeh.plotting import figure, output_file, show
output_file("background.html")
# create a new plot with a title
p = figure(plot_width=400, plot_height=400)
p.background_fill = "beige"
p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)
show(p)
The border fill color is controlled by the border_fill property
of the Plot object. You can also set the minimum border on each side
(in screen units) with the properties
min_border_left
min_border_right
min_border_top
min_border_bottom
Additionally, setting min_border will apply a minimum border setting
to all sides as a convenience. The min_border default value is 40px.
from bokeh.plotting import figure, output_file, show
output_file("border.html")
# create a new plot with a title
p = figure(plot_width=400, plot_height=400)
p.border_fill = "whitesmoke"
p.min_border_left = 80
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
show(p)
The styling of the outline of the plotting area is controlled by a set of
Line Properties on the Plot, that are prefixed with outline_. For
instance, to set the color of the outline, use outline_line_color:
from bokeh.plotting import figure, output_file, show
output_file("outline.html")
# create a new plot with a title
p = figure(plot_width=400, plot_height=400)
p.outline_line_width = 7
p.outline_line_alpha = 0.3
p.outline_line_color = "navy"
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
show(p)
To style the fill, line, or text properties of a glyph, it is first
necessary to obtain a specific GlyphRenderer. When using the
bokeh.plotting interface, the glyph functions return the renderer:
>>> r = p.circle([1,2,3,4,5], [2,5,8,2,7])
>>> r
<bokeh.models.renderers.GlyphRenderer at 0x106a4c810>
Then, the glyph itself is obtained from the .glyph attribute of a
GlyphRenderer:
>>> r.glyph
<bokeh.models.markers.Circle at 0x10799ba10>
This is the object to set fill, line, or text property values for:
from bokeh.plotting import figure, output_file, show
output_file("axes.html")
p = figure(plot_width=400, plot_height=400)
r = p.circle([1,2,3,4,5], [2,5,8,2,7])
glyph = r.glyph
glyph.size = 60
glyph.fill_alpha = 0.2
glyph.line_color = "firebrick"
glyph.line_dash = [6, 3]
glyph.line_width = 2
show(p)
The styling of selected and non-selected glyphs can be customized by
setting the selection_glyph and/or nonselection_glyph attributes
of the GlyphRenderer either manually or by passing them to add_glyph().
from bokeh.io import output_file, show
from bokeh.plotting import figure
from bokeh.models import Circle
output_file("styling_selections.html")
p = figure(plot_width=400, plot_height=400, tools="tap", title="Select a circle")
p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=50, name="mycircle")
selected_circle = Circle(fill_alpha=1, fill_color="firebrick", line_color=None)
nonselected_circle = Circle(fill_alpha=0.2, fill_color="blue", line_color="firebrick")
renderer = p.select(name="mycircle")
renderer.selection_glyph = selected_circle
renderer.nonselection_glyph = nonselected_circle
show(p)
Click/Tap to select circles on the plot above to see the effect on the nonselected glyphs.
Click in the plot, but not on a circle, to see their original state (this
is set by the original call p.circle()).
The same could be achieved with the models interface as follows:
p = Plot()
source = ColumnDataSource(dict(x=[1, 2, 3], y=[1, 2, 3]))
initial_circle = Circle(x='x', y='y', fill_color='blue', size=50)
selected_circle = Circle(fill_alpha=1, fill_color="firebrick", line_color=None)
nonselected_circle = Circle(fill_alpha=0.2, fill_color="blue", line_color="firebrick")
p.add_glyph(
source,
initial_circle,
selection_glyph=selected_circle,
nonselection_glyph=nonselected_circle
)
Note
Only the visual properties of selection_glyph and
nonselection_glyph are considered when renderering. Changing
positions, sizes, etc. will have no effect.
In this section you will learn how to change various visual properties
of Bokeh plot axes.
To set style attributes on Axis objects, use the xaxis, yaxis, and
axis methods on Plot to first obtain a plot’s Axis objects:
>>> p.xaxis
[<bokeh.models.axes.LinearAxis at 0x106fa2390>]
This returns a list of Axis objects (since there may be more than
one). But note that, as convenience, these lists are splattable,
meaning that you can set attributes directly on this result, and
the attributes will be applied to all the axes in the list:
p.xaxis.axis_label = "Temperature"
will change the value of axis_label for every x-axis (however
many there may be).
Below is code that will set some of the properties of axes. You can
execute this code, and try setting other properties as well.
from bokeh.plotting import figure, output_file, show
output_file("axes.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
# change just some things about the x-axes
p.xaxis.axis_label = "Temp"
p.xaxis.axis_line_width = 3
p.xaxis.axis_line_color = "red"
# change just some things about the y-axes
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(p)
The text of an overall label for an axis is controlled by the axis_label
property. Additionally, there are Text Properties prefixed with
axis_label_ that control the visual appearance of the label. For instance
to set the color of the label, set axis_label_text_color. Finally, to
change the distance between the axis label and the major tick labels, set
the axis_label_standoff property:
from bokeh.plotting import figure, output_file, show
output_file("bounds.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.xaxis.axis_label = "Lot Number"
p.xaxis.axis_label_text_color = "#aa6666"
p.xaxis.axis_label_standoff = 30
p.yaxis.axis_label = "Bin Count"
p.yaxis.axis_label_text_font_style = "italic"
show(p)
Sometimes it is useful to limit the bounds where axes are drawn. This can be
accomplished by setting the bounds property of an axis object to a 2-tuple
of (start, end):
from bokeh.plotting import figure, output_file, show
output_file("bounds.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.xaxis.bounds = (2, 4)
show(p)
Bokeh has several “ticker” models that can choose nice locations for ticks.
These are configured on the .ticker property of an axis. With the
bokeh.plotting and bokeh.charts interfaces, choosing an approriate ticker
type (categorical, datetime, linear or log scale) normally happens
automatically. However, there are cases when more explicit control is
useful.
FixedTicker
This ticker model allows users to specify exact tick locations
explicitly.
from bokeh.plotting import figure, output_file, show
from bokeh.models import FixedTicker
output_file("axes.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.xaxis[0].ticker=FixedTicker(ticks=[2, 3.5, 4])
show(p)
The visual appearance of the major and minor ticks is controlled by
a collection of Line Properties, prefixed with major_tick_ and
minor_tick_, respectively. For instance, to set the color of the
major ticks, use major_tick_line_color. To hide either set of ticks,
set the color to None. Additionally, you can control how far in and
out of the plotting area the ticks extend, with the properties
major_tick_in/major_tick_out and minor_tick_in/minor_tick_out.
These values are in screen units, and negative values are acceptable.
from bokeh.plotting import figure, output_file, show
output_file("axes.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.xaxis.major_tick_line_color = "firebrick"
p.xaxis.major_tick_line_width = 3
p.xaxis.minor_tick_line_color = "orange"
p.yaxis.minor_tick_line_color = None
p.axis.major_tick_out = 10
p.axis.minor_tick_in = -3
p.axis.minor_tick_out = 8
show(p)
The orientation of major tick labels can be controlled with the
major_label_orientation property. This property accepts the
values "horizontal" or "vertical" or a floating point number
that gives the angle (in radians) to rotate from the horizontal:
from math import pi
from bokeh.plotting import figure, output_file, show
output_file("gridlines.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.xaxis.major_label_orientation = pi/4
p.yaxis.major_label_orientation = "vertical"
show(p)
There are more properties that Bokeh axes support configuring.
For a complete listing of all the various attributes that can be set
on different types of Bokeh axes, consult the bokeh.models.axes
section of the Reference Guide.
In this section you will learn how to set the visual properties of grid
lines and grid bands on Bokeh plots.
Similar to the convenience methods for axes, there are xgrid, ygrid,
and grid methods on Plot that can be used to obtain a plot’s Grid
objects:
>>> p.grid
[<bokeh.models.grids.Grid at 0x106fa2278>,
<bokeh.models.grids.Grid at 0x106fa22e8>]
These methods also return splattable lists, so that you can set an attribute
on the list, as if it was a single object, and the attribute is changed
for every element of the list:
Note
The xgrid property provides the grid objects that intersect the
x-axis (i.e., are vertical). Correspondingly, ygrid provides
the grid objects that intersect the y-axis (i.e., are horizontal).
The visual appearance of grid lines is controlled by a collection of
Line Properties, prefixed with grid_. For instance, to set the
color of grid lines, use grid_line_color. To hide grid lines, set
their line color to None.
from bokeh.plotting import figure, output_file, show
output_file("gridlines.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
# change just some things about the x-grid
p.xgrid.grid_line_color = None
# change just some things about the y-grid
p.ygrid.grid_line_alpha = 0.5
p.ygrid.grid_line_dash = [6, 4]
show(p)
The visual appearance of minor grid lines is controlled by a collection of
Line Properties, prefixed with minor_grid_. For instance, to set the
color of grid lines, use minor_grid_line_color. By default, minor grid
lines are hidden (i.e., their line color is set to None).
from bokeh.plotting import figure, output_file, show
output_file("minorgridlines.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
# change just some things about the y-grid
p.ygrid.minor_grid_line_color = 'navy'
p.ygrid.minor_grid_line_alpha = 0.1
show(p)
It is also possible to display filled, shaded bands between adjacent
grid lines. The visual appearance of these bands is controlled by a
collection of Fill Properties, prefixed with band_. For instance,
to set the color of grid bands, use band_fill_color. To hide grid
bands, set their fill color to None (this is the default).
from bokeh.plotting import figure, output_file, show
output_file("gridbands.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
# change just some things about the x-grid
p.xgrid.grid_line_color = None
# change just some things about the y-grid
p.ygrid.band_fill_alpha = 0.1
p.ygrid.band_fill_color = "navy"
show(p)
Grids also support setting explicit bounds between which they are drawn.
They are set in an identical fashion to axes bounds, with a 2-tuple
of (start, end):
from bokeh.plotting import figure, output_file, show
output_file("bounds.html")
p = figure(plot_width=400, plot_height=400)
p.circle([1,2,3,4,5], [2,5,8,2,7], size=10)
p.grid.bounds = (2, 4)
show(p)
There are other properties that Bokeh grids support configuring. For a
complete listing of all the various attributes that can be set on Bokeh
plot grids, consult the bokeh.models.grids section of the
Reference Guide.
Similar to the convenience methods for axes and grids, there is a
legend method on Plot that can be used to obtain a plot’s legend
objects:
>>> p.legend
[<bokeh.models.annotations.Legend at 0x106fa2278>]
This method also returns a splattable list, so that you can set an attribute
on the list, as if it was a single object, and the attribute is changed
for every element of the list:
p.legend.label_text_font = "times"
Note
The examples in this section use NumPy to more easily generate better
data suitable for demonstrating legends.
The location of the legend labels is controlled by the orientation
property. Valid values for this property are:
"top_right"
"top_left"
"bottom_left"
"bottom_right"
The default location is "top_right".
import numpy as np
from bokeh.plotting import figure, show, output_file
x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)
output_file("legend_labels.html")
p = figure()
p.circle(x, y, legend="sin(x)")
p.line(x, y, legend="sin(x)")
p.line(x, 2*y, legend="2*sin(x)",
line_dash=[4, 4], line_color="orange", line_width=2)
p.square(x, 3*y, legend="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend="3*sin(x)", line_color="green")
p.legend.orientation = "bottom_left"
show(p)
Note
It is not currently possible to position a legend outside the plot area,
or using absolute coordinates. These and other improvements are planned.
The visual appearance of the legend labels is controlled by a collection of
Text Properties, prefixed with label_. For instance, to set the font
style of the labels, use label_text_font_style.
import numpy as np
from bokeh.plotting import output_file, figure, show
x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)
output_file("legend_labels.html")
p = figure()
p.circle(x, y, legend="sin(x)")
p.line(x, y, legend="sin(x)")
p.line(x, 2*y, legend="2*sin(x)",
line_dash=[4, 4], line_color="orange", line_width=2)
p.square(x, 3*y, legend="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend="3*sin(x)", line_color="green")
p.legend.label_text_font = "times"
p.legend.label_text_font_style = "italic"
p.legend.label_text_color = "navy"
show(p)
The visual appearance of the legend border is controlled by a collection of
Line Properties, prefixed with border_. For instance, to set the color
of the border, use border_line_color. To make the border invisible, set
the border line color to None.
import numpy as np
from bokeh.plotting import output_file, figure, show
x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)
output_file("legend_border.html")
p = figure()
p.circle(x, y, legend="sin(x)")
p.line(x, y, legend="sin(x)")
p.line(x, 2*y, legend="2*sin(x)",
line_dash=[4, 4], line_color="orange", line_width=2)
p.square(x, 3*y, legend="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend="3*sin(x)", line_color="green")
p.legend.border_line_width = 3
p.legend.border_line_color = "navy"
p.legend.border_line_alpha = 0.5
show(p)
The visual appearance of the legend background is controlled by a collection
of Fill Properties, prefixed with background_. For instance, to set the
color of the background, use background_fill_color. To make the background
transparent, set the background_fill_alpha to 0.
import numpy as np
from bokeh.plotting import output_file, figure, show
x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)
output_file("legend_background.html")
p = figure()
p.circle(x, y, legend="sin(x)")
p.line(x, y, legend="sin(x)")
p.line(x, 2*y, legend="2*sin(x)",
line_dash=[4, 4], line_color="orange", line_width=2)
p.square(x, 3*y, legend="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend="3*sin(x)", line_color="green")
# 3*sin(x) curve should be under this legend at initial viewing, so
# we can see that the legend is transparent
p.legend.orientation = "bottom_right"
p.legend.background_fill_color = "navy"
p.legend.background_fill_alpha = 0.5
show(p)
There are several properties that can be used to control the layout,
spacing, etc. of the legend components:
-
label_standoff
property type: Int
The distance (in pixels) to separate the label from its associated glyph.
-
label_width
property type: Int
The width (in pixels) of the area that legend labels should occupy.
-
label_height
property type: Int
The height (in pixels) of the area that legend labels should occupy.
-
glyph_width
property type: Int
The width (in pixels) that the rendered legend glyph should occupy.
-
glyph_height
property type: Int
The height (in pixels) that the rendered legend glyph should occupy.
-
legend_padding
property type: Int
Amount of padding around the legend.
-
legend_spacing
property type: Int
Amount of spacing between legend entries.
import numpy as np
from bokeh.plotting import output_file, figure, show
x = np.linspace(0, 4*np.pi, 100)
y = np.sin(x)
output_file("legend_labels.html")
p = figure()
p.circle(x, y, legend="sin(x)")
p.line(x, y, legend="sin(x)")
p.line(x, 2*y, legend="2*sin(x)",
line_dash=[4, 4], line_color="orange", line_width=2)
p.square(x, 3*y, legend="3*sin(x)", fill_color=None, line_color="green")
p.line(x, 3*y, legend="3*sin(x)", line_color="green")
p.legend.label_standoff = 5
p.legend.glyph_width = 50
p.legend.legend_spacing = 10
p.legend.legend_padding = 50
show(p)
