These are the most important concepts and terms that you will encounter
throughout Bokeh’s documentation:
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.
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.
handles the UI interactions for Bokeh plots and
widgets in the browser. In most cases, Bokeh handles all
don’t have to”). For more details, see the BokehJS
chapter of the developers guide.
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.
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.
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
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
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.
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
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.
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.
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.
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:
For generating simple standalone HTML documents for Bokeh visualizations.
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
p = figure()
p.line(x=[1, 2, 3], y=[4,6,2])
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
However, Bokeh also comes with a powerful command line tool bokeh that
can also be used to generate various kinds of output:
Create standalone HTML documents from any kind of Bokeh application
source: e.g., python scripts, app directories, JSON files, and others.
Generate a serialized JSON representation of a Bokeh document from any
kind of Bokeh application source.
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])
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.
bokeh html foo.py
bokeh serve foo.py
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 is actually composed of two library components.
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 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)
# display the figure
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.