The Bokeh magic extension for the IPython notebook simplifies some common tasks and offers some different operating modes for using Bokeh.
First, you need to load the extension!
Note: This extension is fully featured if you are using IPython 2.0 or above, thanks to a new callback system. The functionality is somewhat limited in IPython 1.x: you can not use the --figure
mode, and the --hold
mode can not be disabled without restarting the kernel.
import bokeh.bokeh_magic
Executing this import will enable %bokeh magic, and if necessar, will take care of the installation step too...
Note: You can also install the extension and load it in the canonical IPython-way:
%install_ext https://raw.github.com/ContinuumIO/bokeh/master/extensions/bokeh_magic.py
%load_ext bokeh_magic
However, we suggest you just call import bokeh.bokeh_magic
at the top of your notebooks, and you will always be ready to go.
Now, we need to activate the Bokeh notebook environment, you can easily do it just calling the --notebook argument of the bokeh magic:
%bokeh --notebook
Every Bokeh magic argument has shortcuts, so you can use %bokeh -n
for the previous case too.
Note: This magic command is equivalent to output_notebook()
.
You can always do %bokeh?
to see some information about the basic magic functionality.
After configuring the environment you have essentially three modes:
--show
--hold
--figure
Let's begin with the --show
mode. This mode add a call to the Bokeh show function after each cell, so you do not have to be aware to call this function to show your plots.
%bokeh --show
Now the --show
mode is enable, but you can disable at any time just doing:
%bokeh --show-off
The same goes for the other modes, you can disable them just doing:
%bokeh --hold-off
%bokeh --figure-off
Note: You can call the magic with several arguments in just one line, ie:
%bokeh --show --hold --figure
Now, time to make some plots. We will plot two scatterplots of sine curves.
import numpy as np
from bokeh.plotting import scatter
N = 100
x = np.linspace(0, 4*np.pi, N)
y = np.sin(x)
scatter(x, y,
color="black",tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="sin(x)"
)
scatter(x, 2*y,
color="orange", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="2*sin(x)"
)
# we will disable the `--show` mode to avoid the render of the last plot in the next code cell
%bokeh --show-off
You probably have noticed that we only have one sine curce and this is the expected behaviour. If we want to see both curves on one plot, we have to activate the --hold
mode:
%bokeh --hold
scatter(x, y,
color="black",tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="sin(x)"
)
scatter(x, 2*y,
color="orange", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="2*sin(x)"
)
%bokeh --show
We can also add more sines curves into the plot:
scatter(x, 3*y,
color="green", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="3*sin(x)"
)
scatter(x, 4*y,
color="blue", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="4*sin(x)"
)
# we will disable the `--show` mode to avoid the render of the last plot in the next code cell
%bokeh --show-off
And now, we can introduce the --figure
mode, which implicitly adds a call to the Bokeh figure
function at the beginning of each cell:
%bokeh --figure
%bokeh --show
scatter(x, y,
color="black",tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="sin(x)"
)
scatter(x, 2*y,
color="orange", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="2*sin(x)"
)
But now, because figure is activated, if we added two more sines waves:
scatter(x, 3*y,
color="green", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="3*sin(x)"
)
scatter(x, 4*y,
color="blue", tools="pan,wheel_zoom,box_zoom,reset,previewsave",
legend="4*sin(x)"
)
Only the two last sine curves will be displayed because we now have a new figure.
OK, this notebook is just a short introduction, so play with %bokeh magic and have fun!
The Bokeh team.