banner

BeakerX: Beaker extensions for Jupyter

Build Status Gitter chat Release NPM version PyPI Version Anaconda-Server Badge Binder

BeakerX is a collection of JVM kernels and interactive widgets for plotting, tables, autotranslation, and other extensions to Jupyter Notebook.

The documentation consists of tutorial notebooks on GitHub. You can try it in the cloud for free with Binder. And here is the cheatsheet.

BeakerX is the successor to the Beaker Notebook (source code archive). It comes from Two Sigma Open Source. Yes we are hiring.

This README is for developers. Users should see the documentation on the homepage for how to install and run BeakerX.

Dependencies:

Build and Install (linux and mac)

conda env create -n beakerx -f configuration.yml
conda activate beakerx # For conda versions prior to 4.6, run: source activate beakerx
(cd beakerx; pip install -r requirements.txt --verbose)
beakerx install
beakerx_databrowser install

Build and Install (win)

conda env create -n beakerx -f configuration.yml
activate beakerx
cd beakerx
pip install -r requirements.txt --verbose
cd ..
beakerx install
beakerx_databrowser install

Build and Install for Jupyter Lab

conda env create -n labx -f configuration.yml
conda activate labx # For conda versions prior to 4.6, run: source activate labx
conda install -y -c conda-forge jupyterlab=1
(cd beakerx; pip install -r requirements.txt --verbose)
beakerx install
jupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build
(cd js/lab; jupyter labextension install . --no-build)
(cd js/lab-theme-dark; jupyter labextension install . --no-build)
(cd js/lab-theme-light; jupyter labextension install . --no-build)
jupyter lab build

Running with Docker

docker run -p 8888:8888 beakerx/beakerx

Update after Java change

The kernels are installed to run out of the repo, so just a local build should suffice:

(cd kernel; ./gradlew build)

Update after JS change

The notebook extensions are installed to run out of the repo, so just a local build should suffice:

(cd js/notebook; yarn run build)
beakerx install

Run TypeScript Unit Tests

The Java and TypeScript unit tests are run with every build. See test/README.md for how to run the e2e tests.

Run Python Unit Tests

(cd beakerx; python -m unittest)
(cd beakerx_tabledisplay; python -m unittest)

Groovy with Interactive Plotting:

screen shot

Autotranslation from Python to JavaScript and D3

screen shot

Interactive Tables

screen shot

Table Display from conda package

notebook

conda create --name beakerx_td
source activate beakerx_td
conda install beakerx_tabledisplay

lab

conda create --name labx_td
source activate labx_td
conda install -y -c conda-forge jupyterlab
conda install beakerx_tabledisplay
beakerx_tabledisplay install --lab

Architecture and Code Overview

BeakerX is a collection of kernels and extensions for Jupyter. The code is organized into subdirectories as follows:

Contributing

See CONTRIBUTING.md.

Releasing

See RELEASE.md.

FAQs

See FAQ.md.

Attribution

BeakerX contains and depends on many projects including:

The kernel is originally derived from lappsgrid, but has been rewritten in Java and refactored and expanded.

The Java support uses Adrian Witas' org.abstractmeta.toolbox.

ANTLR Copyright (c) 2012 Terence Parr and Sam Harwell

d3 Copyright (c) 2010-2015, Michael Bostock

IPython Copyright (c) 2008-2014, IPython Development Team Copyright (c) 2001-2007, Fernando Perez Copyright (c) 2001, Janko Hauser Copyright (c) 2001, Nathaniel Gray

The table of contents and init cells extensions come from: IPython-contrib Copyright (c) 2013-2015, IPython-contrib Developers

Scala Copyright (c) 2002-2015 EPFL Copyright (c) 2011-2015 Typesafe, Inc.

Guava Copyright (C) 2012 The Guava Authors

Apache Spark Copyright (C) 2014 and onwards The Apache Software Foundation.

H2 database engine This software contains unmodified binary redistributions for H2 database engine (http://www.h2database.com/), which is dual licensed and available under the MPL 2.0 (Mozilla Public License) or under the EPL 1.0 (Eclipse Public License). An original copy of the license agreement can be found at: http://www.h2database.com/html/license.html