Bokeh Annotations and Legends: A Complete Guide to Interactive Chart Labels and Visual Explanations

Creating an informative chart involves more than simply plotting data points. Users need context to understand trends, identify important events, and distinguish between multiple datasets. Bokeh provides a rich collection of annotations and legends that help explain visualizations without cluttering the chart.

Annotations allow you to highlight specific regions, add notes, draw reference lines, or emphasize important values. Legends help users identify each plotted dataset, making multi-series charts much easier to read.

In this tutorial, you'll learn how to use Bokeh's annotation models and legend features to create polished, interactive, and professional data visualizations.

---

What Are Annotations?

Annotations are graphical elements that provide additional information on a chart without representing actual data points.

Common annotation types include:

• Labels
• Label Sets
• Arrows
• Spans
• Boxes
• Bands
• Color Bars
• Titles

Annotations improve readability by drawing attention to significant information.

---

What Are Legends?

Legends identify different glyphs or data series displayed on a chart.

A legend typically shows:

• Series name
• Color
• Marker style
• Line style

Legends become especially useful when visualizing multiple datasets within a single figure.

---

Creating a Basic Plot

Start with a simple figure.

from bokeh.plotting import figure, show

plot = figure(
    title="Monthly Sales",
    width=700,
    height=400
)

plot.line(
    [1,2,3,4,5],
    [10,14,12,18,20],
    legend_label="Sales",
    line_width=3
)

show(plot)

The legend_label parameter automatically creates a legend entry.

---

Adding Labels

Labels display text at specific coordinates.

Example:

from bokeh.models import Label

label = Label(
    x=3,
    y=18,
    text="Highest Sales"
)

plot.add_layout(label)

Labels are useful for highlighting important values or milestones.

---

Using LabelSet

A LabelSet displays multiple labels from a data source.

from bokeh.models import ColumnDataSource, LabelSet

source = ColumnDataSource(data={
    "x":[1,2,3],
    "y":[5,8,6],
    "names":["A","B","C"]
})

labels = LabelSet(
    x="x",
    y="y",
    text="names",
    source=source
)

plot.add_layout(labels)

This approach is ideal when every data point requires a label.

---

Drawing Reference Lines with Span

A Span creates horizontal or vertical reference lines.

from bokeh.models import Span

span = Span(
    location=15,
    dimension="width",
    line_color="red",
    line_dash="dashed",
    line_width=2
)

plot.add_layout(span)

Reference lines are commonly used to indicate:

• Targets
• Thresholds
• Averages
• Critical limits

---

Highlighting Regions with BoxAnnotation

A BoxAnnotation highlights an area of the plot.

from bokeh.models import BoxAnnotation

box = BoxAnnotation(
    left=2,
    right=4,
    fill_alpha=0.2,
    fill_color="green"
)

plot.add_layout(box)

This is useful for emphasizing important time periods or value ranges.

---

Using Band Annotations

Bands display shaded confidence intervals or acceptable ranges.

from bokeh.models import Band

Bands are widely used in:

• Scientific research
• Statistical analysis
• Forecasting
• Machine learning

They help communicate uncertainty and variability.

---

Adding Arrows

Arrows draw attention to specific features.

from bokeh.models import Arrow, NormalHead

arrow = Arrow(
    end=NormalHead(),
    x_start=2,
    y_start=8,
    x_end=4,
    y_end=16
)

plot.add_layout(arrow)

Arrows are useful for pointing out trends, peaks, or noteworthy events.

---

Using Color Bars

Color bars explain numerical color mappings.

from bokeh.models import ColorBar

They are commonly paired with:

• Heatmaps
• Geographic maps
• Density plots
• Scientific visualizations

Color bars make gradient-based charts much easier to interpret.

---

Customizing Legends

Legends can be styled extensively.

plot.legend.location = "top_left"

plot.legend.click_policy = "hide"

Popular locations include:

• top_left
• top_right
• bottom_left
• bottom_right
• center

The click_policy allows users to hide or mute individual data series interactively.

---

Legend Styling

Improve the appearance of legends.

plot.legend.label_text_font_size = "12pt"

plot.legend.background_fill_alpha = 0.6

plot.legend.border_line_color = "gray"

Thoughtful styling ensures the legend complements the visualization without distracting from the data.

---

Multiple Legends

Charts containing many datasets can include multiple legends.

This is particularly useful in:

• Financial dashboards
• Scientific comparisons
• Engineering reports
• Business intelligence applications

Organized legends improve readability when displaying numerous glyphs.

---

Interactive Legends

One of Bokeh's most powerful features is interactive legends.

plot.legend.click_policy = "mute"

Available options include:

• hide
• mute

Users can quickly focus on specific data series without reloading the visualization.

---

Combining Multiple Annotations

Annotations can work together.

Example:

• Label
• Span
• Arrow
• BoxAnnotation
• Legend

Combining these elements creates highly informative dashboards and reports.

---

Styling the Plot

Complete the visualization with professional styling.

plot.title.text_font_size = "18pt"

plot.xaxis.axis_label = "Month"

plot.yaxis.axis_label = "Revenue"

plot.background_fill_color = "#f8f9fa"

plot.grid.grid_line_alpha = 0.3

A clean design improves readability and user experience.

---

Best Practices

For effective annotations and legends:

• Keep labels concise.
• Avoid overlapping annotations.
• Use contrasting colors.
• Position legends away from important data.
• Use reference lines sparingly.
• Highlight only significant information.
• Maintain consistent styling.
• Test interactive legend behavior.

These practices improve chart clarity without overwhelming the viewer.

---

Common Mistakes

Avoid these common issues:

• Too many annotations.
• Oversized legends.
• Overlapping labels.
• Poor color contrast.
• Inconsistent formatting.
• Excessive visual clutter.
• Legends that cover important data.

Simple, focused annotations communicate insights more effectively.

---

Real-World Applications

Annotations and legends are widely used in:

• Business dashboards
• Financial reports
• Healthcare analytics
• Scientific publications
• Weather forecasting
• Manufacturing monitoring
• Educational materials
• Geographic information systems
• Marketing analytics

They help transform raw charts into meaningful visual stories.

---

Conclusion

Annotations and legends are essential tools for creating professional Bokeh visualizations. Labels, arrows, spans, box annotations, bands, and color bars provide valuable context, while interactive legends make it easier for users to explore multiple datasets.

By mastering these features, you can build charts that are not only visually appealing but also highly informative and user-friendly. Whether you're developing business dashboards, scientific applications, or educational tools, effective annotations and well-designed legends will significantly improve the clarity and impact of your data visualizations.