OpenDreamKit

A project funded by the Horizon 2020

European Research Infrastructures Work Program

Authoring interactive books with Jupyter notebooks

Marcin Kostur - 19 Oct 2019

Introduction

The ease of authoring manuscripts is a key to wide application of any new technology in educational practice. Generally speaking, academic teachers lecturing on computer science tend to be fluent in all kinds of computer technology and happily adopt new ones. However, as topics get further and further from computer science as in theoretical mechanics or dynamical systems technology, technology literacy becomes a barrier. It can often happen that such subjects are not integrated with computer technologies during teaching at all.

Scenario

John is lecturing theoretical mechanics and wants to integrate computer algebra calculation in his course. He already has examples and ideas how to use SageMath to creatively improve problem solving in mechanics. He wants to use a single system for both his own experiments with algebra involved in mechanics and for authoring materials for students. Additionally, he wants students to be able to:

Suggestion of solution

  1. He uses Jupyter notebook with SageMath kernel, mixing prose, code, visualization, together with resources: source code, data, media;

  2. He publishes them on a publicly hosted repository using a template. In this example the repository is Binder-ready; for details, see the Binder documentation

  3. He shares the link to the repository with students.

Some instances

Alternative solutions

There are many other possibilities to write interactive textbooks. This workflow can be adapted to use automatic tests that can reexecute all the material in the notebook to verify that the newly calculated outputs match up to trivial differences, with the recorded outputs. This uses the NBVAL tool – developed as part of OpenDreamKit and is implemented in Introduction to Python for Computational Science and Engineering textbook.

One can use more sophisticated typesetting and documentation tools. One possibility is Sphinx system, which is used to build documentation for Python packages. It is capable of better control of the format of the book. Examples are interative textbooks on Linear Algebra and Nonlinear Processes in Biology which have been developed as part of OpenDreamKit D2.9. In this scenario, authoring is done using reStructuredText format. It provides the ability to create interactive code cells using SageCell or thebelab. It requires more effort to setup the environment and to author materials, but one gain better interactivity features and more control onver the output. Addtionally, using the sphinx system one can produce high quality “static” PDF format.

Discussion

By publishing the course materials in the form of notebooks and using provided the template repository, John easily achieves following:

  1. He can compile selected notebooks to a book form using LaTeX typesetting software. It can be printed and used in non-interactive way as a regular book.

  2. Using Binder, notebooks can be launched at any time without any authorization. In this way is it possible to use in during lecture or a tutorial as live interactive examples.

  3. The repository can be cloned and on students computers. This allows for individual work of students on their assignments or exploration of the subject.

Time and expertise required

Assuming John is familiar with version control and Jupyter (basic lab skills taught at Software Carpentry, and is fluent in using Jupyter notebook, the initial setup of the course repository could take few hours the first time. Further development should not generate any significant overhead compared to regular use of Jupyter notebook.

What’s new since OpenDreamKit started

OpenDreamKit contribution

Jupyter Use Cases Open Science and Reproducibility Best Practice Reproducibility Binder

<