Skip to content

bqplot

bqplot bqplot

bqplot is a python based 2-D visualization system for Jupyter, based on the constructs of Grammar of Graphics. In bqplot every component of the plot is an interactive widget. This allows the user to seamlessly integrate bqplot with other Jupyter widgets to create rich visualizations by using just python code!

Key Features

  • Core Plotting Support for core plotting is provided
  • Responsive Built using the same machinery that powers Jupyter widgets
    • Most of the attributes of figure and mark objects are implemented as traitlets which make the plots respond to data updates. After rendering the charts the attributes of the figures and marks can be updated in notebook cells down (or in callbacks) and changes are automatically reflected in the chart!
  • Selectors Selectors enable selecting slices of data
    • 1D selectors Select slices of data along one dimension (x or y)
    • 2D selectors Select slices of data along two dimensions (x and y) using rectangular brushing
    • Lasso Select slices of data along two dimensions (x and y) using a lasso
  • Jupyter Widget Integration Seamless integration and linking with Jupyter widgets
  • Extensibility Object Model can be extended to build re-usable compound plotting widgets and widget libraries
  • Dashboards/Apps Build rich interactive dashboards and apps by integrating bqplot with other Jupyter widget libraries and voila dashboarding tool

While bqplot provides support for static plotting for most of the chart types, it really shines in interactive plotting where data attributes are updated in an event-driven fashion (using ipywidgets, click handlers etc.)

Python API

Two APIs are provided in bqplot:

  • Pyplot

    • Context-based API similar to matplotlib's pyplot
    • Provides sensible default choices for most parameters
    • Concise API
    • Preferred API for most usecases
  • Object Model

    • Based on the constructs of Grammar of Graphics
    • Users need to explicitly create Scale, Mark, Axis and Figure objects
    • Verbose API
    • Fully customizable
    • Extensible

Usage

pyplot

pyplot is the best way to get started on bqplot. Creating a plot involves 3 steps:

  • Create a figure object
  • Create one or more marks (marks will be added to the above figure by default)
  • Render the figure which is an instance of DOMWidget

import bqplot.pyplot as plt
import numpy as np

fig = plt.figure(title="Sine")

# create data vectors
x = np.linspace(-10, 10, 200)
y = np.sin(x)

# create line mark
line = plt.plot(x, y)

# renders the figure in the output cell (with toolbar for panzoom, save etc.)
plt.show()
plot

Object Model

Object Model is a verbose (but fully customizable) API for creating plots. Creating a plot involves the following steps:

  • Create scales for data attributes (x, y, color etc.)
  • Create marks using the above scales
  • Create axes objects using the above scales
  • Finally create the figure object and pass the marks and axes as parameters

import numpy as np
import bqplot as bq

x = np.linspace(-10, 10, 200)
y = np.sin(x)

# create scales
xs = bq.LinearScale()
ys = bq.LinearScale()

# create mark objects
line = bq.Lines(x=x, y=y, scales={"x": xs, "y": ys})

# create axes objects
xax = bq.Axis(scale=xs, grid_lines="solid", label="X")
yax = bq.Axis(scale=ys, orientation="vertical", grid_lines="solid")

# create the figure object (renders in the output cell)
bq.Figure(marks=[line], axes=[xax, yax], title="Sine")
plot

Plot Enhancements

To enhance the plots (colors, grid lines, axes labels, ticks, legends etc.) you need to pass in additional parameters to the plotting widget constructors/methods. Let's look at an example:

fig = plt.figure(title="Sine", legend_location="top-left")
x = np.linspace(-10, 10, 100)
# multi line chart
y = [np.sin(x), np.cos(x)]

# customize axes
axes_options = {
    "x": {"label": "X"},
    "y": {"label": "Y", "tick_format": ".2f"}
}
curves = plt.plot(
    x,
    y,
    colors=["red", "green"],
    display_legend=True,
    axes_options=axes_options,
    labels=["Sine", "Cosine"]
)
fig
plot

Next Steps

Have a look at Usage section for more details on how to configure and customize various plots