2 Customising the Jupyter Environment
An unextended Jupyter notebook or JupyterLab environment provides a minimal interactive environment for creating and working with Jupyter notebooks.
However, by pre-configuring a Jupyter notebook environment with a range of pre-installed and pre-enabled notebook extensions, we can create a much richer environment for authoring and working with notebooks.
By authoring learning materials in a way that exploits the use or application of particular extensions, we can create a much more powerful teaching and learning environment.
This document will review a range of extensions that may be used to support:
- authoring materials;
- editing materials;
- using materials.
Where Jupyter notebooks accessed via a Jupyter notebook environment are the intended delivery medium, and the OU has control or influence over how that environment is configured, preinstalled and pre-enabled extensions potentially provide a richer canvas for authoring in at least three respects:
- how materials are rendered;
- what they can do, and
- the actions learners can take within them.
Note that the Jupyter environment may also be used as pure authoring environment to author structure materials. Such materials can then be published and rendered in formats other than the Jupyter notebook, such as HTML book formats or “print” (PDF, docx) materials.
An OU Teach and Learn project is currently under submission (May, 2021) to explore pathways for converting between OU-XML and Jupyter .ipynb document formats which would allow the Jupyter notebook environment to become a generally availably authoring environment for authoring and editing OU-XML mediated content, such as VLE content.
2.1 Extension Flavours
There are three main ways in which a Jupyter notebook environment may be extended:
- notebook extensions: these extensions add functionality to the Jupyter notebook user interface, and typically install additional Javascript into the user interface that can modify the behaviour of the interface; a particulat
- server extensions: these extensions modify the behaviour of the server; for example, server extensions might allow novel document formats to be opened into the notebook environment or exported from it;
- IPython magics: IPython magics can be defined that either act as “macro” style commands, or that modify the behaviour of a code cell (block cell magics); for example, block cell magics can be used to transform a code cell connected to a Python kernel to one that accepts SQL code that the Python kernel can then use as part of a query onto a connected database.
A further class of “extension” comes in the form of packages installed in the Python (or R) kernel that are capable of generating “rich” output. For example, a wide variety of packages exist that make it easy to output an interactive map into a code cell output, or musical notation according to a provided score.
For a wide range of examples of packages that can produce static and interactive (rich) media outputs as part of a Jupyter Authoring system, see SubjectMatterNotebooks.
For an excellent guide to notebook extensions, see the Unofficial Jupyter Notebook Extensions.
For creating Jupyter which transform code cell text using calls to the active kernel, see KernelExecOnCells library .
2.3 Customising the Teaching and Learning Environment
TLDR: Jupyter notebooks can be customised we can provide students with a to test/review materials as designed, you need to test them in the environment they were designed for.
An ongoing point of contention both within and across module teams using or exploring Jupyter notebooks relates to the extent to which we should or should not author notebooks for use in a particular environment.
A key point to bear in mind here is the idea of the “notebook environment”. The default, classic Jupyter notebook UI is a minimal affair. (The same could be argued for JupyterLab framework environments.)
A wide variety of extensions can be installed that enrich the Jupyter notebook experience. Typically, these notebook extensions customise notebook user interface. Installing an extension typically requires downloading and installing a Python package, which typically installs the extension into the notebook server automatically. Extensions may also need to be enabled, which can be done automatically in a provided environment or manually via the notebook nbextensions configurator. Installed notebook extensions may be enabled or disabled by the user at any time via the nbextensions configurator.
In TM351, notebooks are written that exploit the preconfigured environment we provide students with. For example, notebooks are tagged to show various coloured sections for activities or highlight calls to action, answers or sample solutions are hidden, coloured “info-boxes” highlight particular items and so on.
In an off-the-shelf environment, none of these enhancements will be visible. We could argue the display degrades gracefully for each extension that is not available and not enabled. This degradation may be made more graceful by reinforcing certain distinctions. For instance, tagged “info-box” content ordinarily coloured by an extension might be presented using italicised text to reinforce the distinction from main flow text. Even without the the colour, the distinction remains.
In a certain sense, we might argue that there is an implicit dependence on certain extensions in some materials. To the student, there may be nothing in the notebook that makes them think there is anything missing in the notebook. For example, if an activity cell is not coloured, so what? There may be ambiguity about when the activity ends, but that is often clear from the structure of the text. The colour enriches the message that something is activity related, but is not required for that message.
In some cases, there may be clues that something is missing. For example, the call out to “click the triangle at the side to reveal the answer” in a collapsed answer doesn’t make sense if there is no triangle and the answer is displayed. We could tweak the text to fix that: “if the answer is hidden, click the triangle to the side to reveal it”. Or we could update the extension so that it’s a bit cleverer and inserts the text on how to reveal the answer if the extension is enabled and responsible for hiding the answer.
Other notebooks may make explicit calls on the availability of a particular extension or some functionality that it provides. The extension developed for TM351 to render an image showing the current structure of a connected database is explicitly referenced and used in the text, as well as being available as a tool students can use on their own initiative to visually check the state of their database.
Explicit references may also be made in the text that refer to operations the student needs to perform using notebook toolbar buttons that are installed by particular extensions: no extension = no button = no access to functionality referenced in the material.
These explicit references do not necessarily degrade gracefully unless they are used in an optional or nice to have way that is not on the critical path of an activity or notebook narrative. More likely, if the extension is not available, the materials will be “broken” in the sense that something referred to is not available.
There are implications here for user-testing or review of materials: the notebooks should be tested in the assumed provided environment. Further testing in an off-the-shelf / unextended environment may be advisable to see just how broken the experience might be in such an environment with a view to making materials work at some acceptable level in such environments.
There are also implications for recommending emerging best practice or conventions used successfully in one module to other modules. One way of disseminating practice across module teams is for particular individuals associated with module to work on another; another route is for editors to share practice. IET(?) attempt to get module teams to engage in learning design at the start of a module production process but do not make technology related recommendations or suggestions and have not engaged with TM351 or Tm129 module practices in terms of capturing, evaluating or critiquing emerging notebook practice.
The following table captures some of the arguments for and against providing a customised environment. It is not intended to be exhaustive.
| FOR customised environments | AGAINST customised environments |
|---|---|
| Value add feature | Reduced potential audience |
| Materials can be enhanced by exploiting extension behaviours | Materials are broken without extensions |
| Provided environment comes with preinstalled and pre-configured extensions so no student overhead | Students must use the provided environment or try to upgrade a third party or off-the-shelf environment themselves to work with our materials |
2.4 A Question of Defaults
When providing an environment to authors, or distributing an environment to students, it is possible to pre-install certain components but not necessarily pre-enable them,
This means that users may selectively choose to enable notebook extensions and customise their environment without having to install any additional packages.
When students use a supplied environment, extensions enabled by default provide students with preconfigured environment that may reflect:
- the opinion of the module team regarding extensions that students may find useful;
- extensions that the module team have designed the notebooks to work with in the expectation that they will be provided as part of a provided notebook environment.
In abstract terms, we might think of a layered model when it comes to defining the user environment
| Layer | Role |
|---|---|
| Base environment | common base environment; eg in Dockerised virtual environment, the base operating system or base container |
| Base Jupyter environment | A core Jupyter environment to build on, common to the sort of environment that might be expected of-the-shelf |
| Extended Jupyter environment | Includes: branding; preinstalled extensions; pre-enabled extensions |
| Base computing environment | For example, the basic kernel(s) accessed from the base Jupyter environment |
| Module specific computing environment | Module specific packages, as for example installed as requirements of a single, otherwise empty, module package |
| Generic content | For example, general purpose Jupyter notebook tutorials that may be used across modules |
| Module specific content | For example, module specific Jupyter notebooks |
Note that a significant point of difference arises between:
- environments that are installed by students using off-the-shelf installers or services which we might term pure self-service environments;
- environments that are provided by the OU but installed by students themselves, which we might term provided self-service environments;
- environments that are provided in a preconfigured form by the OU with no installation requirement placed on students, which we might term provided environments
In terms of providing environments to students across modules, a question arises regarding the extent to which module teams might customise the environment or use a configuration that is, insofar as is possible, common to and consistent across all modules.
Where students are required to install an environment in a pure self-service model, a question arises as to how they should install any additional packages or extensions required by the module, or whether the module should prima facie be designed to work the the off-the shelf environment the student is expected to install or sign up to in the case of an “off-the-shelf” hosted service environment.