Bokeh (pronounced boh-Kay) is an implementation of Grammar of Graphics for Python, that also supports the customized rendering flexibility of Protovis and d3. Although it is a Python library, its primary output backend is HTML5 Canvas.
There are many excellent plotting packages for Python, but they generally do not optimize for the particular needs of statistical plotting (easy faceting, bulk application of aesthetic and visual parameters across categorical variables, pleasing default color palettes for categorical data, etc.). The goal of Bokeh is to provide a compelling Python equivalent of ggplot in R.
A related project is Pandas, whose DataFrame objects are directly used by Bokeh. Bokeh will also interface with the NDTable objects in Blaze.
Bokeh has a function-oriented interface that closely resembles ggplot. These functions can be used interactively from the Python prompt, or from within a script (a la Matplotlib). Behind the scenes, these functions construct a scenegraph and data transformation pipeline that consists of nodes which can export their state into JSON.
The JSON representation of the graphic is then embedded in an HTML document which also contains the Bokeh JS runtime. This runtime is built on a port of Protovis to HTML5 Canvas, and consists of some higher-level canned plot layouts built on top of the Protovis framework.
With the git commandline:
git clone git://github.com/ContinuumIO/Bokeh.git
or as a ZIP Archive
cd into the source directory.
For the initial prototype, Bokeh is implemented as a wrapper on top of the Chaco plotting system, and displays its output using Chaco. This will change as we implement the Javascript/HTML backend.
You can install the following with easy_install, "pip install", or they may be available for your Linux system via the system package management. If you are using a distribution like Anaconda Community Edition, Enthought Python Distribution, or Python(X,Y), then you already have most of them installed.
If not, you should install these either with pip:
pip install -r requirements.txt
Or use your distributions package manager.
Python Modules:
Other:
Redis is required for dynamically linked graphs.
After installing the dependencies (chaco, etc.), run the following in the source directory:
pip install .
The setup.py will automatically grab the latest compiled javascript from github, so you don't need coffeescript in order to use Bokeh.
Bokeh was started in March 2012, and still remains in the experimental/prototype stage. It is under active development by contributors at Continuum Analytics, and with the recent award of a grant from DARPA, we are able to devote more resources into it, along with collaborators from Indiana University.
Bokeh can currently output to chaco, as well as dumping html, or interfacing with our bokeh web server, which will push plots out to a browser window using websockets. The following examples assume you have bokeh installed
- start a redis-server anywhere, using
$ redis-server & - install the bokeh module
$ python setup.py develop - execute
$ python startlocal.py - navigate to
http://localhost:5006/bokeh - execute
$ python examples/webplot_example.py
$ python tests/web/facetgrid.py- open up the generated
grid.htmlin a web browser
- start Redis server according to your distro
- execute
python startlocal.pyin Bokeh source directory - in another terminal
cd examples - execute
ipython notebook
"Bokeh" is a photography term for the aesthetic quality of blurring of an image's background, to focus attention on a foreground subject.
We're developing most of the javascript using coffeescript, in the bokehjs github repository which has been included as a subtree. To develop Bokeh you will need to install coffeescript, which depends on node.js. I recommend using npm -g to install coffeescript globally.
We're using our own fork of hem to manage the build process.
Please clone this repo: https://github.com/ContinuumIO/hem as a subdirectory of the Bokeh repo.
hem will compile coffeescript, combine js files, and support node.js require syntax on the client side
install it by executing
$ sudo npm link inside the hem repo.
This will link hem to your working copy so you get hem changes as we push it out
- Inside bokeh/server of the Bokeh repo, execute
$ hem server &. The hem server will serve up coffeescript, compiling them on the fly. - If you are developing Bokeh, you should use the debug webserver.
start it by executing$ python startlocaldebug.py. The debug webserver is configured to ask the hem server for compiled javascript, rather than read the pre-compiled js off of disk. - For the embedded plotting examples, or the production server, you will
need to compile the js yourself, by executing
$ hem build -d, the-doption will prevent hem from uglifying the js, which breaks the notebook export at the moment.