First steps 3: Adding legends, text, and annotations

In the previous first steps guide, you generated different glyphs and defined their appearance.

In this section, you will add and style a legend and a headline. You will also add additional information to your plot by including annotations.

Adding and styling a legend

Bokeh automatically adds a legend to your plot if you include the legend_label attribute when calling the renderer function. For example:

p.circle(x, y3, legend_label="Objects")

This adds a legend with the entry “Objects” to your plot.

Use the properties of the Legend object to customize the legend. For example:

from bokeh.plotting import figure, show

# prepare some data
x = [1, 2, 3, 4, 5]
y1 = [4, 5, 5, 7, 2]
y2 = [2, 3, 4, 5, 6]

# create a new plot
p = figure(title="Legend example")

# add circle renderer with legend_label arguments
line = p.line(x, y1, legend_label="Temp.", line_color="blue", line_width=2)
circle = p.circle(
    x,
    y2,
    legend_label="Objects",
    fill_color="red",
    fill_alpha=0.5,
    line_color="blue",
    size=80,
)

# display legend in top left corner (default is top right corner)
p.legend.location = "top_left"

# add a title to your legend
p.legend.title = "Obervations"

# change appearance of legend text
p.legend.label_text_font = "times"
p.legend.label_text_font_style = "italic"
p.legend.label_text_color = "navy"

# change border and background of legend
p.legend.border_line_width = 3
p.legend.border_line_color = "navy"
p.legend.border_line_alpha = 0.8
p.legend.background_fill_color = "navy"
p.legend.background_fill_alpha = 0.2

# show the results
show(p)

See also

To learn more about legends, see Legends in the annotations section and Styling legends in the styling section of the user guide. The entry Legend in the reference guide contains a list of all available attributes for legends.

See Interactive legends in the user guide to learn about using legends to hide or mute glyphs in a plot.

Customizing headlines

Most of the examples so far have included a headline. You did this by passing the title argument to the figure() figure function:

p = figure(title="Headline example")

There are various ways to style the text for your headline. For example:

from bokeh.plotting import figure, show

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

# create new plot
p = figure(title="Headline example")

# add line renderer with a legend
p.line(x, y, legend_label="Temp.", line_width=2)

# change headline location to the left
p.title_location = "left"

# change headline text
p.title.text = "Changing headline text example"

# style the headline
p.title.text_font_size = "25px"
p.title.align = "right"
p.title.background_fill_color = "darkgrey"
p.title.text_color = "white"

# show the results
show(p)

See also

For more information on working with title, see Titles in the user guide. In the reference guide, the entry for Title contains a list of all available properties.

Using annotations

Annotations are visual elements that you add to your plot to make it easier to read. For more information on the various kinds of annotations, see Adding annotations in the user guide.

One example are box annotations. You can use box annotations to highlight certain areas of your plot:

To add box annotations to your plot, you first need to import the BoxAnnotation class from Bokeh’s models collection:

from bokeh.models import BoxAnnotation

Next, create the BoxAnnotation objects. If you do not pass a value for bottom or top, Bokeh automatically extends the box’s dimension to the edges of the plot:

low_box = BoxAnnotation(top=80, fill_alpha=0.1, fill_color='red')
mid_box = BoxAnnotation(bottom=80, top=180, fill_alpha=0.1, fill_color='green')
high_box = BoxAnnotation(bottom=180, fill_alpha=0.1, fill_color='red')

Finally, you need to add the BoxAnnotation objects to your existing figure. Use the add_layout() method to add your boxes:

p.add_layout(low_box)
p.add_layout(mid_box)
p.add_layout(high_box)

This is what the finished code looks like:

import random

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

# generate some data (1-50 for x, random values for y)
x = list(range(0, 51))
y = random.sample(range(0, 100), 51)

# create new plot
p = figure(title="Box annotation example")

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

# add box annotations
low_box = BoxAnnotation(top=20, fill_alpha=0.1, fill_color="red")
mid_box = BoxAnnotation(bottom=20, top=80, fill_alpha=0.1, fill_color="green")
high_box = BoxAnnotation(bottom=80, fill_alpha=0.1, fill_color="red")

# add boxes to existing figure
p.add_layout(low_box)
p.add_layout(mid_box)
p.add_layout(high_box)

# show the results
show(p)

See also

To find out more about the different kinds of annotations in Bokeh, see Adding annotations in the user guide.