Defining key concepts#
These are the most important concepts and terms that you will encounter throughout Bokeh’s documentation:
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.
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 necessary objects.
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.
Bokeh offers a variety of ways to produce interactive output. The following two functions are the most common:
Generate simple standalone HTML documents for Bokeh visualizations.
Display Bokeh visualizations in Jupyter/Zeppelin notebooks.
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)
This script generates an HTML file called
output.html that contains a line
plot. You can execute it with
python foo.py, where
foo.py is the name
of the script.
These functions are often useful in interactive settings or for creating standalone Bokeh documents to serve from backend web applications.
Another way to generate various kinds of output is by using Bokeh’s powerful command line tool.
There are various global settings that influence how Bokeh operates. You can use several methods to change Bokeh’s configuration: Directly in the Python code, in a YAML configuration file, or with environment variables, for example. The full list of all available settings and how to change them is available at bokeh.settings.
Some of most useful settings are:
Set this configuration value to the browser you want Bokeh to use (for example when calling
show()). Valid values are any of the predefined browser names of the Python webbrowser module. For example:
windows-default. You can also set this variable to the full path of your browser. For example:
$Env:BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"
set BOKEH_BROWSER="C:/Program\ Files/Google/Chrome/Application/chrome.exe %s &"
Set this configuration value to
Trueto enable support for legacy browsers (IE and phantomjs).
To display interactive visualizations in a browser, Bokeh needs to load BokehJS. Set this configuration value to define where to load BokehJS from. For example:
cdnto load BokehJS from Bokeh’s Content Delivery Network (CDN)
serverto load from a Bokeh server
relativeto load a local version relative to the given directory.
All available options are listed at
You can combine some of the values for this variable with other configuration values, such as
BOKEH_ROOTDIR). See bokeh.settings for details.
Bokeh provides a simple and intuitive interface for users like data scientists and domain experts who do not wish to be distracted by complex details of the software. At the same time, Bokeh also caters to people such as 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 users.
The bokeh.plotting interface#
The bokeh.plotting interface lets you focus on relating glyphs to data. It automatically assembles plots with default elements such as axes, grids, and tools for you.
figure() function is at the core of the bokeh.plotting interface. This
function creates a
Figure model that includes methods for adding different
kinds of glyphs to a plot. This function also takes care of composing the
various elements of your visualization, such as axes, grids, and tools.
Below is an example of bokeh.plotting, 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)
figure() function is all it takes to create a basic plot object. To
add data renderers to your plot object, call a glyph method such as
Figure.circle. You don’t have to worry about axes and grids (although you can
configure them if you want to), and you only need to list the tools you want to
add. To display your visualization in a browser, in most cases, all you need to
do is call the output function
With the bokeh.plotting interface, you have many more possibilities to create an customize your visualization. For example:
saving the plot to an HTML file instead of showing it
styling and removing axes, grids, annotations, and interactive elements
adding more data renderers
arranging multiple plots and widgets into layouts
For an easy to follow guide to building your first visualizations with Bokeh, see the first steps guides.
The bokeh.models interface#
With Bokeh’s low-level bokeh.models interface, you have complete control over how Bokeh creates all elements of your visualization. However, Bokeh’s low-level interface doesn’t help you assemble the various elements in meaningful or correct ways. It is entirely up to you to put them together.
Therefore, unless you have special applications that require finer control, you will probably want to use the bokeh.plotting interface described above.
To be able to use the bokeh.models interface, you need to understand the basic principle by which Bokeh enables you to generate interactive, browser-based visualizations. Behind the scenes, Bokeh consists of two libraries:
BokehJS runs in the browser. This library handles rendering and user interactions. It takes a collection of declarative JSON objects as its input and uses them as instructions on how to handle the various aspects of your visualization in a browser. For example:
plots and widgets
layouts and arrangements
tools and renderers
In the browser, BokehJS converts these JSON objects into BokehJS models and renders them according to corresponding BokehJS views.
- Bokeh, the Python library
The Python library generates the JSON objects that BokehJS uses to render your visualization in a browser.
At its lowest level, the Python library uses a set of
modelclasses that exactly mirror the set of models that BokehJS creates in a browser.
modelclasses are able to validate their content and attributes and serialize themselves to JSON. Most of the models are very simple and usually consist of only a few property attributes and no methods. You can configure the attributes of those models either by setting them when creating a model or later by setting attribute values on the model object.
You can access all low-level
model objects through Bokeh’s bokeh.models
For example, to create and configure a
Rect glyph object:
# configure attributes when initializing a model object glyph = Rect(x="x", y="y2", w=10, h=20, line_color=None) # assign values to attributes to an existing model object glyph.fill_alpha = 0.5 glyph.fill_color = "navy"
You can generally configure all Bokeh models this way. Since all Bokeh interfaces ultimately produce collections of Bokeh models, this lets you style and configure plots and widgets the same way regardless of the interface.
The Python library allows for binding with other languages that can produce appropriate JSON output. For more details and available bindings, see Contribute to language bindings.