Nicolas M. Thiéry - 23 Jul 2018

Scenario

Viviane is writing slides for a talk; she would like to include live SageMath computations in her slides. She also would like to publish her slides online, letting anyone – during and after her talk – browse the slides and play around with the provided examples.

Note: most of this blog can be adapted for any other computational system that can be run in Jupyter like, for mathematics, GAP, Pari/GP, or Singular.

Some instances

• The Rise contact involution on Tamari Intervals, Viviane Pons (GitHub repository, Live slides)

  

• Computing huge subspaces of polynomials: Symmetries to the rescue!, Nicolas M. Thiéry (GitHub repository, Live slides)

  

Suggestion of solution

We will use the above slides from the repository https://github.com/nthiery/harmonic-modules as running example.

Components involved

• SageMath (Sage for short) is a Python based general purpose system for computational mathematics.

• Jupyter is a web application for authoring and sharing documents that contain live code, equations, visualizations and narrative text.

• RISE is a Jupyter extension to render Jupyter notebooks as slides, based on the popular HTML presentations framework reveal.js.

• Binder is a service that lets any user on the internet define, run, and share temporary virtual environments equipped with an arbitrary software stack (examples).

Installation

Install Jupyter’s RISE extension in Sage. From the terminal:

sage -pip install RISE

Notes:

• The instructions above assume that the Sage command is available as sage; otherwise adapt the command accordingly.

• The instructions above assume that you have write access to the Sage installation.

• The instructions above have a bit of additional complexity because they require accessing pip and jupyter from the Sage distribution; in general, one would just do:

    pip install RISE
  

• The first instruction may fail complaining about OpenSSL. This will happen when Sage has not been compiled with SSL support which is needed for the pip package manager which, alas, happens too often. The installation instructions may help fix that.

Authoring and showing slides

Open the Jupyter notebook that you want to turn into slides – or create a new one – ; we will assume it’s called talk.ipynb. Activate the Slideshow metadata:

View -> Cell Toolbar -> Slideshow

Choose the role each cell should play: for example start a new slide (Slide), add a fragment to the current slide (Fragment), or don’t show up (Note).

Activate the slideshow by clicking in the corresponding button in the toolbar.

For further details on authoring, showing, and configuring the slideshow, see the RISE documentation.

Publishing the slides on a web page

This assumes that you have access on a web server to publish HTML files that embed javascript.

The slides can be converted to static HTML pages with embedded javascript with:

jupyter nbconvert talk.ipynb --to slides

The produced file talk.slides.html can then be copied to the web server. Readers will be able to see and navigate the slides; however they won’t be able to modify and run the examples.

Publishing live slides on Binder

Add the notebook to a public git repository, for example on github.

Specifying software dependencies

Add metadata to that git repository to specify the software required to run the computations. For SageMath, you can add the following Dockerfile at the root of the repository:

FROM sagemath/sagemath:8.7

# Make sure the contents of the repository is in ${HOME}
COPY --chown=sage:sage . ${HOME}

Specifying additional software dependencies (optional)

The sagemath base docker image contains the required software needed to be compatible with binder. If the notebook uses additional software in addition to SageMath, they need to be specified as well in the Dockerfile. For example, if you are using RISE slides, add this line:

RUN sage -pip install RISE

In general a Python package available from pypi can be installed with:

RUN sage -pip install <package name>

Sage packages can be installed with:

RUN sage -i <package name>

Debian/Ubuntu packages can be installed with:

RUN apt-get update && apt-get install -y <package name>

Hence, to have dot2tex graphics, you would use:

RUN apt-get update && apt-get install -y graphviz
RUN sage -pip install dot2tex

See also the section Preparing your docker file from the binder documentation.

Accessing the notebook in Binder

Go to mybinder.org, specify the address of the git repository (here https://github.com/nthiery/harmonic-modules/ ) and the name of the file (here talk.ipynb`). Click launch, and voilà!

Note: the SageMath docker image is relatively big. Therefore the first time the slides are accessed, or if it has not been accessed in a while, Binder will typically take a couple minutes to launch: it indeed needs to fetch the base SageMath image, build the new image containing the Jupyter extensions and the notebook, and then copy this image around between it’s various machines (that building the image, that storing them, and those running them).

Publishing the Binder link

From Binder’s main page, you can get a URL to access directly the live notebook, or even a badge to copy-paste in your web page.

Alternatives

Instead of publishing on Binder, one may author the slides on cocalc, and use its publish feature. (TODO: double check that RISE works on cocalc).

Instead of using a Jupyter notebook, one may author in HTML (or some format that can be converted to HTML), and use ThebeLab or [SageCell][http://sagecell.sagemath.org/]to enable live computations.

Advantages and drawbacks

Traditionally, most mathematicians author their slides using LaTeX+Beamer, and display and publish them in PDF format.

• Authoring slides with Jupyter+RISE tends to be more lightweight

• LaTeX+Beamer gives fine control on the layout for authoring complex slides; some fine control can be achieved with Jupyter+RISE, using explicit html+css, but this is not as convenient.

• One may include live computations

• One may easily include multimedia documents

• One may edit the slides on the fly

• The semantic structure tends to get lost in PDF files, which goes in the way of accessibility. On the other hand, HTML based documents tend to support well web-based accessibility tools like screen readers.

To do

• Estimate the number of instances;
• Provide a template.

Time and expertise required

Assuming Viviane is familiar with Jupyter, writing her first slides using RISE will take a few minutes and mastering it a few hours.

Assuming Viviane is familiar with version control and Jupyter (basic lab skills taught at Software Carpentry, and the required software required is packaged (conda, debian, docker container, …), the publishing part could take two hours the first time, and minutes later on (typically by having a preconfigured repository where one stores all of one’s presentations)..

What’s new since OpenDreamKit started

• Apparition of Binder;
• Expansion of the Jupyter technology;
• Apparition of RISE
• Better packaging and interfacing of math software.

OpenDreamKit contribution

• Development and contributions to Jupyter interfaces (kernels) for math software (GAP, Pari/GP, SageMath, Singular) and C++; see D.47.
• Contributions to the packaging of math software (GAP, Pari/GP, SageMath, Singular, …); see D3.1 and D3.10;
• Early adoption of Binder;
• Contributions to the deployment of new Binder instances;
• Advertising, training, providing a template (TODO!), …

SageMath Front Page Jupyter Use Cases Open Science and Reproducibility Best Practice Reproducibility Binder