Defining Key Concepts¶

Glossary¶

In order to make the best use of this User Guide, it is important to have context for some high level concepts and terms. Here is a small glossary of some of the most important concepts in Bokeh.

Application: A Bokeh application is a rendered Bokeh document, running in a browser.
BokehJS: The JavaScript client library that actually renders the visuals and handles the UI interactions for Bokeh plots and widgets in the browser. Typically, users will not have to think about this aspect of Bokeh much (“We write the JavaScript, so you don’t have to!”) but it is good to have basic knowledge of this dichotomy. For full details, see the BokehJS chapter of the Developer Guide.
Charts: Schematic statistical plots such as bar charts, horizon plots, time series, etc. that may include faceting, grouping, or stacking based on the structure of the data. Bokeh provides a high level bokeh.charts interface to quickly construct these kinds of plots. See Making High-level Charts for examples and usage.
Documents: 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 of including Bokeh plots and widgets into web apps and pages, or the IPython notebook. See Embedding Plots and Apps for more details.
Glyphs: The basic visual building blocks of Bokeh plots, e.g. lines, rectangles, squares, wedges, patches, etc. The bokeh.plotting interface provides a convenient way to create plots centered around glyphs. See Plotting with Basic Glyphs for more information.
Models: The lowest-level objects that comprise Bokeh “scenegraphs”. These live in 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, so it is important to understand them enough to configure their attributes and properties. See Styling Visual Attributes for more information.
Server: The Bokeh server is an optional component that can be used for sharing and publishing Bokeh plots and apps, for handling streaming of large data sets, or for enabling sophisticated user interactions based off of widgets and selections. See Running a Bokeh Server for more explanation.
Widgets: User interface elements outside of a Bokeh plot such as sliders, drop down menus, buttons, etc. Events and updates from widgets can inform additional computations, or cause Bokeh plots to update. Widgets can be used in both standalone applications or with the Bokeh server. For examples and information, see Adding Interactions.

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 notebook cells.
output_server: For installing Bokeh applications on a running Bokeh server.

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 server 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

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

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 bokeh Commands.

Interfaces¶

Bokeh is intended to be useful to data-scientists and domain experts, working at a very high level, as well as 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 programming interfaces appropriate to different levels, as well as some compatibility interfaces to make use of existing code from other libraries. This section provides an overview of the different 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 plotting, go to Plotting with Basic Glyphs or Making High-level Charts.

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 Backbone Models in the browser, and are rendered by corresponding Backbone 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 Backbone 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 one of the higher level interfaces described below, unless they have specialized requirements that necessitate finer control. For more information about the details of all Bokeh models, consult the Reference Guide.

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 class. This is a subclass of the basic Plot model, that includes methods for easily adding different kinds of glyphs to a plot. Additionally it composes default axes, grids, and tools in the proper way without any extra effort. Typically, users will want to create Figure objects by using the figure() function.

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(width=300, 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 plots 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.

Note

The output functions output_file() and show(), etc. are defined in the bokeh.io module, but are also importable from bokeh.plotting for convenience.

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.

bokeh.charts¶

Bokeh also provides a very high-level bokeh.charts interface for quickly creating statistical charts. As with bokeh.plotting, the main purpose of the interface is to help simplify the creation of Bokeh object graphs by encapsulating patterns of assembling Bokeh models. The bokeh.charts interface may also take the additional step of performing necessary statistical or data processing for the user. The interface presents functions for common, schematic statistical charts. Additionally, the chart functions can take care of automatically coloring and faceting based on group structure.

The interface includes chart types such as: Bar(), BoxPlot(), Histogram(), TimeSeries(), and many others. One simple example using Scatter() is shown below:

from bokeh.charts import Scatter, output_file, show

# prepare some data, a Pandas GroupBy object in this case
from bokeh.sampledata.autompg import autompg as df

# create a scatter chart
p = Scatter(df, x='mpg', y='hp', color='cyl',
            title="MPG vs HP (colored by CYL)",
            legend='top_right',
            xlabel="Miles Per Gallon",
            ylabel="Horsepower")

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

# display the figure
show(p)

Important to note is that the same output functions are used across different interfaces. As with bokeh.plotting, the output functions output_file() and show(), etc. that are defined in bokeh.io, are also importable from bokeh.charts as a convenience.

other interfaces¶

Bokeh provides some level of Matplotlib compatibility, by using the third-party mplexporter library. Although it does not provide 100% coverage of Matplotlib capabilities, it is still quite useful. For instance, in addition to many Matplotlib plots, it is often possible to convert plots created using the python Seaborn and ggplot.py libraries into Bokeh plots very easily. There are several examples in the Gallery. Here is a quick example that shows a Seaborn plot converted to a Bokeh plot with just one additional line of code:

import seaborn as sns

from bokeh import mpl
from bokeh.plotting import output_file, show

tips = sns.load_dataset("tips")

sns.set_style("whitegrid")

ax = sns.violinplot(x="day", y="total_bill", hue="sex",
                    data=tips, palette="Set2", split=True,
                    scale="count", inner="stick")

output_file("violin.html")

show(mpl.to_bokeh())