bqplot: Plotting for Jupyter¶
Introduction¶
bqplot is a Grammar of Graphics-based interactive plotting framework for the Jupyter notebook.
In bqplot, every single attribute of the plot is an interactive widget. This allows the user to integrate any plot with IPython widgets to create a complex and feature rich GUI from just a few simple lines of Python code.
Goals¶
- provide a unified framework for 2-D visualizations with a pythonic API.
- provide a sensible API for adding user interactions (panning, zooming, selection, etc)
Two APIs are provided
- Users can build custom visualizations using the internal object model, which is inspired by the constructs of the Grammar of Graphics (figure, marks, axes, scales), and enrich their visualization with our Interaction Layer.
- Or they can use the context-based API similar to Matplotlib’s pyplot, which provides sensible default choices for most parameters.
Installation¶
Using pip:
pip install bqplot
jupyter nbextension enable --py --sys-prefix bqplot # can be skipped for notebook version 5.3 and above
Using conda
conda install -c conda-forge bqplot
Usage¶
Examples¶
Using the pyplot API
import numpy as np
from bqplot import pyplot as plt
plt.figure(1, title='Line Chart')
np.random.seed(0)
n = 200
x = np.linspace(0.0, 10.0, n)
y = np.cumsum(np.random.randn(n))
plt.plot(x, y)
plt.show()
Using the bqplot internal object model
import numpy as np
from IPython.display import display
from bqplot import (
OrdinalScale, LinearScale, Bars, Lines, Axis, Figure
)
size = 20
np.random.seed(0)
x_data = np.arange(size)
x_ord = OrdinalScale()
y_sc = LinearScale()
bar = Bars(x=x_data, y=np.random.randn(2, size), scales={'x': x_ord, 'y':
y_sc}, type='stacked')
line = Lines(x=x_data, y=np.random.randn(size), scales={'x': x_ord, 'y': y_sc},
stroke_width=3, colors=['red'], display_legend=True, labels=['Line chart'])
ax_x = Axis(scale=x_ord, grid_lines='solid', label='X')
ax_y = Axis(scale=y_sc, orientation='vertical', tick_format='0.2f',
grid_lines='solid', label='Y')
Figure(marks=[bar, line], axes=[ax_x, ax_y], title='API Example',
legend_location='bottom-right')
API Reference Documentation¶
BQPlot Package¶
Each plot starts with a Figure object. A Figure has a number of Axis objects (representing scales) and a number of Mark objects. Mark objects are a visual representation of the data. Scales transform data into visual properties (typically a number of pixels, a color, etc.).
from bqplot import *
from IPython.display import display
x_data = range(10)
y_data = [i ** 2 for i in x_data]
x_sc = LinearScale()
y_sc = LinearScale()
ax_x = Axis(label='Test X', scale=x_sc, tick_format='0.0f')
ax_y = Axis(label='Test Y', scale=y_sc,
orientation='vertical', tick_format='0.2f')
line = Lines(x=x_data,
y=y_data,
scales={'x': x_sc, 'y': y_sc},
colors=['red', 'yellow'])
fig = Figure(axes=[ax_x, ax_y], marks=[line])
display(fig)
Scales¶
Scale (**kwargs) |
The base scale class. |
LinearScale (**kwargs) |
A linear scale. |
LogScale (**kwargs) |
A log scale. |
DateScale (**kwargs) |
A date scale, with customizable formatting. |
OrdinalScale (**kwargs) |
An ordinal scale. |
ColorScale (**kwargs) |
A color scale. |
DateColorScale (**kwargs) |
A date color scale. |
OrdinalColorScale (**kwargs) |
An ordinal color scale. |
GeoScale (**kwargs) |
The base projection scale class for Map marks. |
Mercator (**kwargs) |
A geographical projection scale commonly used for world maps. |
AlbersUSA (**kwargs) |
A composite projection of four Albers projections meant specifically for the United States. |
Gnomonic (**kwargs) |
A perspective projection which displays great circles as straight lines. |
Stereographic (**kwargs) |
A perspective projection that uses a bijective and smooth map at every point except the projection point. |
Marks¶
Mark (**kwargs) |
The base mark class. |
Lines (**kwargs) |
Lines mark. |
FlexLine (**kwargs) |
Flexible Lines mark. |
Scatter (**kwargs) |
Scatter mark. |
Hist (**kwargs) |
Histogram mark. |
Bars (**kwargs) |
Bar mark. |
Graph (**kwargs) |
Graph with nodes and links. |
GridHeatMap (**kwargs) |
GridHeatMap mark. |
HeatMap (**kwargs) |
HeatMap mark. |
Label (**kwargs) |
Label mark. |
OHLC (**kwargs) |
Open/High/Low/Close marks. |
Pie (**kwargs) |
Piechart mark. |
Map (**kwargs) |
Map mark. |
Market Map¶
MarketMap (**kwargs) |
Waffle wrapped map. |
SquareMarketMap (**kwargs) |
Interacts¶
BrushIntervalSelector (**kwargs) |
Brush interval selector interaction. |
BrushSelector (**kwargs) |
Brush interval selector interaction. |
HandDraw (**kwargs) |
A hand-draw interaction. |
IndexSelector (**kwargs) |
Index selector interaction. |
FastIntervalSelector (**kwargs) |
Fast interval selector interaction. |
MultiSelector (**kwargs) |
Multi selector interaction. |
OneDSelector (**kwargs) |
One-dimensional selector interaction |
Interaction (**kwargs) |
The base interaction class. |
PanZoom (**kwargs) |
An interaction to pan and zoom wrt scales. |
Selector (**kwargs) |
Selector interaction. |
TwoDSelector (**kwargs) |
Two-dimensional selector interaction. |
Pyplot¶
figure ([key, fig]) |
Creates figures and switches between figures. |
show ([key, display_toolbar]) |
Shows the current context figure in the output area. |
axes ([mark, options]) |
Draws axes corresponding to the scales of a given mark. |
plot (*args, **kwargs) |
Draw lines in the current context figure. |
scatter (x, y, **kwargs) |
Draw a scatter in the current context figure. |
hist (sample[, options]) |
Draw a histogram in the current context figure. |
bar (x, y, **kwargs) |
Draws a bar chart in the current context figure. |
ohlc (*args, **kwargs) |
Draw OHLC bars or candle bars in the current context figure. |
geo (map_data, **kwargs) |
Draw a map in the current context figure. |
clear () |
Clears the current context figure of all marks axes and grid lines. |
close (key) |
Closes and unregister the context figure corresponding to the key. |
current_figure () |
Returns the current context figure. |
scales ([key, scales]) |
Creates and switches between context scales. |
xlim (min, max) |
Set the domain bounds of the current ‘x’ scale. |
ylim (min, max) |
Set the domain bounds of the current ‘y’ scale. |
axes ([mark, options]) |
Draws axes corresponding to the scales of a given mark. |
xlabel ([label, mark]) |
Sets the value of label for an axis whose associated scale has the dimension x. |
ylabel ([label, mark]) |
Sets the value of label for an axis whose associated scale has the dimension y. |