Defining Key Concepts

Glossary

These are the most important concepts and terms that you will encounter throughout Bokeh’s documentation:

Annotation

Visual aids that make reading the plot easier. This includes titles, legends, labels, or bands, for example. See Adding Annotations in the User guide for more information and examples.

Application

A Bokeh application is a recipe for generating Bokeh documents. Typically, this is Python code run by a Bokeh server whenever a new sessions is created.

BokehJS

The JavaScript client library that actually renders the visuals and handles the UI interactions for Bokeh plots and widgets in the browser. In most cases, Bokeh handles all interactions with BokehJS automatically (“We write the JavaScript, so you don’t have to”). For more details, see the BokehJS chapter of the developers guide.

Document

An organizing data structure for Bokeh applications. Documents contain all the Bokeh models and data needed to render an interactive visualization or application in the browser.

Embedding

Various methods that help with including Bokeh plots and widgets in web apps, web pages, or Jupyter notebooks. See Embedding Bokeh content in the User guide for more details.

Glyph

API objects that draw vectorized graphics to represent data. Glyphs are the basic visual building blocks of Bokeh plots. This includes elements such as lines, rectangles, squares, wedges, or the circles of a scatter plot. The bokeh.plotting interface provides a convenient way to create plots centered around glyphs. See Plotting with Basic Glyphs in the User guide for more information.

Layout

A collection of Bokeh objects. This can be several plots and widgets, arranged in nested rows and columns. See Creating layouts in the User guide for more information and examples.

Model

The lowest-level objects that Bokeh visualizations consist of. Bokeh’s models are part of the bokeh.models interface. Most users will not use this level of interface to assemble plots directly. However, ultimately all Bokeh plots consist of collections of models. It is helpful to understand them enough to configure their attributes and properties. See Styling Visual Attributes in the User guide for more information.

Plot

Containers that hold all the various objects (such as renderers, glyphs, or annotations) of a visualization. The bokeh.plotting interface provides the figure() function to help with assembling all the necessary objects.

Renderer

General term for any method or function that draws elements of the plot. Examples of elements that are generated by renderers are glyphs or annotations.

Server

The Bokeh server is an optional component. You can use the Bokeh server to share and publish Bokeh plots and apps, to handle streaming of large data sets, or to enable complex user interactions based on widgets and selections. See Running a Bokeh Server in the User guide for more information and examples.

Widget

User interface elements that are not directly part of a Bokeh plot, such as sliders, drop-down menus, or buttons. You can use events and data from widgets in your Python code, or you can use input from widgets to update you Bokeh plot itself. You can use widgets in standalone applications or with the Bokeh server. For examples and information, see Making Interactions in the User guide.

Output Methods

As we will see demonstrated frequently throughout the User Guide, there are various ways to generate output for Bokeh documents. The most common for interactive usage are:

output_file

For generating simple standalone HTML documents for Bokeh visualizations.

output_notebook

For displaying Bokeh visualizations inline in Jupyter/Zeppelin notebook cells.

These functions are most often used together with the show or save functions. Scripts that output with these typically look something like:

from bokeh.plotting import figure, output_file, show

output_file("output.html")

p = figure()
p.line(x=[1, 2, 3], y=[4,6,2])

show(p)

If this script is called foo.py then executing python foo.py will result in an HTML file output.html being generated with the line plot. These functions are often useful in interactive settings, or for creating standalone Bokeh documents to serve from (Flask, Django, etc.) web applications.

However, Bokeh also comes with a powerful command line tool bokeh that can also be used to generate various kinds of output:

bokeh html

Create standalone HTML documents from any kind of Bokeh application source: e.g., python scripts, app directories, JSON files, and others.

bokeh json

Generate a serialized JSON representation of a Bokeh document from any kind of Bokeh application source.

bokeh serve

Publish Bokeh documents as interactive web applications.

An advantage of using the bokeh command is that the code you write does not have to specify any particular output method or format. You can write just the visualization code once, and decide later to output in different ways. The above example would be simplified to:

from bokeh.plotting import figure, curdoc

p = figure()
p.line(x=[1, 2, 3], y=[4,6,2])
curdoc().add_root(p)

Now, you can run bokeh html foo.py to generate a standalone HTML file, or bokeh serve foo.py to start serving this document as a web application. For more information on the command line tool see Using the Command Line.

Interfaces

Bokeh is intended to provide a quick and simple interface to data scientists and domain experts who do not want to be distracted by the details of the software, and also provide a richly detailed interface to application developers and software engineers who may want more control or access to more sophisticated features. Because of this, Bokeh takes a layered approach and offers different programming interfaces appropriate to different levels of use. This section provides an overview of the various interfaces that are available to Bokeh users, as well as more context about the most important concepts central to the library. If you’d like to jump right into basic plotting, go to Plotting with Basic Glyphs.

bokeh.models

Bokeh is actually composed of two library components.

The first component is a JavaScript library, BokehJS, that runs in the browser. This library is responsible for all of the rendering and user interaction. Its input is a collection of declarative JSON objects that comprise a “scenegraph”. The objects in this scenegraph describe everything that BokehJS should handle: what plots and widgets are present and in what arrangement, what tools and renderers and axes the plots will have, etc. These JSON objects are converted into BokehJS Models in the browser, and are rendered by corresponding BokehJS Views.

The second component is a library in Python (or other languages) that can generate the JSON described above. In the Python Bokeh library, this is accomplished at the lowest level by exposing a set of “model” classes that exactly mirror the set of BokehJS Models that are created in the browser. These Python model classes know how to validate their content and attributes, and also how to serialize themselves to JSON. All of these low level models live in the low-level bokeh.models interface. Most of the models are very simple, usually consisting of a few property attributes and no methods. Model attributes can either be configured when the model is created, or later by setting attribute values on the model object. Here are some examples for a Rect glyph object:

# properties can be configured when a model object is initialized
glyph = Rect(x="x", y="y2", w=10, h=20, line_color=None)

# or by assigning values to attributes on the model later
glyph.fill_alpha = 0.5
glyph.fill_color = "navy"

These methods of configuration work in general for all Bokeh models. Because of that, and because all Bokeh interfaces ultimately produce collections of Bokeh models, styling and configuring plots and widgets is accomplished in basically the same way, regardless of which interface is used.

Using the bokeh.models interface provides complete control over how Bokeh plots and Bokeh widgets are put together and configured. However, it provides no help with assembling the models in meaningful or correct ways. It is entirely up to developers to build the scenegraph “by hand”. For this reason, most users will probably want to use the bokeh.plotting interface described below, unless they have specialized requirements that necessitate finer control. For more information about the details of all Bokeh models, consult the Reference.

bokeh.plotting

Bokeh provides a mid-level general purpose bokeh.plotting interface, which is similar in specificity to Matplotlib or Matlab style plotting interfaces. It is centered around having users relate the visual glyphs they would like to have displayed to their data, and otherwise taking care of putting together plots with sensible default axes, grids, and tools. All the hard work to assemble the appropriate Bokeh Models to form a scenegraph that BokehJS can render is handled automatically.

The main class in the bokeh.plotting interface is the figure() function. This creates a Figure model that includes methods for adding different kinds of glyphs to a plot. Additionally, it composes default axes, grids, and tools in the proper way without any extra effort.

A prototypical example of the bokeh.plotting usage is show below, along with the resulting plot:

from bokeh.plotting import figure, output_file, show

# create a Figure object
p = figure(plot_width=300, plot_height=300, tools="pan,reset,save")

# add a Circle renderer to this figure
p.circle([1, 2.5, 3, 2], [2, 3, 1, 1.5], radius=0.3, alpha=0.5)

# specify how to output the plot(s)
output_file("foo.html")

# display the figure
show(p)

The main observation is that the typical usage involves creating plot objects with the figure() function, then using the glyph methods like Figure.circle to add renderers for our data. We do not have to worry about configuring any axes or grids (although we can configure them if we need to), and specifying tools is done simply with the names of tools to add. Finally, we use some output functions to display our plot.

There are many other possibilities: saving our plot instead of showing it, styling or removing the axes or grids, adding additional renderers, and laying out multiple plots together. The Plotting with Basic Glyphs section of this User guide will walk through many more examples and common use cases of using the bokeh.plotting interface.