Defining Key Concepts¶
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.
- A Bokeh application is a rendered Bokeh document, running in a browser.
- 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.chartsinterface to quickly construct these kinds of plots. See Making High-level Charts for examples and usage.
- 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 of including Bokeh plots and widgets into web apps and pages, or the IPython notebook. See Embedding Plots and Apps for more details.
- The basic visual building blocks of Bokeh plots, e.g. lines, rectangles,
squares, wedges, patches, etc. The
bokeh.plottinginterface provides a convenient way to create plots centered around glyphs. See Plotting with Basic Glyphs for more information.
- The lowest-level objects that comprise Bokeh “scenegraphs”. These live
bokeh.modelsinterface. 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.
- 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.
- 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.
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 notebook cells.
- For installing Bokeh applications on a running Bokeh server.
These functions are most often used together with the
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
However, Bokeh also comes with a powerful command line tool
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 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,
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.
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 is actually composed of two library components.
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 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
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
figure() function, then using the glyph methods like
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.
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:
TimeSeries(), and many others. One simple example using
Scatter() is shown
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
show(), etc. that are defined in bokeh.io, are also importable from
bokeh.charts as a convenience.
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())