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)

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)

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)