Teaching with Jupyter and COMET

Author

Jonathan Graves

Published

2 October 2024

This guide is an introduction to how you can use COMET and Jupyter notebooks for teaching. We will mainly discuss Jupyter Notebooks, for reasons explained in Section 1, but most of this advice is easy to adapt to other forms of notebook-based instruction such as R Markdown or Quarto.

In this guide, we will discuss:

The advantages and disadvantages of different notebook-based systems for classroom instruction.
How to use COMET-style notebooks in different classroom settings, including an outline of how to plan a lesson.
How to develop interactive learning activities to accompany a COMET-style notebooks, including some classroom-tested suggestions.
An introduction to developing your own COMET-style notebooks for classroom instruction.

Want the Basics?

Just looking for a quick overview of how Jupyter notebooks work? Try out getting started introduction to Jupyter notebook, then come back here.

As most of our experience is in post-secondary education, this guide is intended for educators teaching students at the university level. However, it is probably also suitable for upper-year high school students, with sufficient experience¹.

1 Why Jupyter Notebooks?

Why are Jupyter Notebooks a valuable tool for teaching? There are two main reasons:

First, there are the advantages of Notebooks for teaching.
Second, there are the advantages of Jupyter for teaching.

Combining these advantages creates a very valuable tool.

1.1 Why Notebooks?

A notebook refers to a digital document which combines rich text (including hyperlinks, formatting, and images) with cells that can perform computations. A user is able to change the content of the notebook, such as performing a computation or changing the text.

Notebooks teach students three important skills, useful for data science and applied social science research:

First, they teach students how to perform literate coding. Literate programming dates back to Knuth (1984), and has become extremely popular in sciences that use data. As Kery et al. (2018) explains, combining notes and context with code creates a self-documenting research notebook that addresses many common problems novice (and experienced) researchers face when analyzing data.
Second, they encourage replicable and reproducible data analysis. The non-reproducability of empirical results (see Camerer et al. (2018)) has reached crisis-levels in some fields. Because notebooks need to be run from the top-down, they naturally encourage students to make their analyses replicable. The structure of a notebook also encourage transparency when experimenting with analyses. This makes the work more likely to be reproducible.
Third, they teach industry-relevant skills. Notebooks are extensively used by employers who conduct data science research, or who use data science in their work. Understanding how to write and use notebooks is a valuable skill in itself.

These properties make notebooks ideal to teach to students. Creating notebooks for classroom instruction turns them from a research tool into a pedagogical tool.

1.2 Why Jupyter?

Jupyter is not the only option for notebooks (see Section 1.3). However, it has some advantages for teaching not shared by alternatives:

No installation necessary: when used through a JupyterHub, Jupyter notebooks do not require students to install any software or have a powerful computer. Even students with just a Chromebook or tablet can use Jupyter notebooks.
- This eliminates many of the most time-consuming and frustrating parts of teaching student data science, including: installing software, troubleshooting package conflicts, issues sharing files and data, and computer problems.
Simple Github integration: through nbgitpuller it is easy to share notebooks directly into a JupyterHub. This means that starting a class using notebooks is as easy as sharing a link with your students.
Language independence: although the Jupyter framework is written in Python, it uses kernels to perform computation. There are dozens of kernels available, including those for popular languages such as R, Julia, Java, C, STATA, and Python itself.

The biggest strength of Jupyter is its hub-based design. This is also its biggest weakness, since it relies on an internet connection and someone to manage the hub. However, there are many free, well-maintained, hubs online such as:

You can also set up your own, or work with non-profits like 2i2c to develop your own hub.

1.3 What are the Alternatives?

Jupyter Notebooks are not the only option for teaching using notebooks. In fact, there are significant advantages to other notebook styles, which may be more effective for certain kinds of teaching.

Jupyter Notebooks

Jupyter notebooks are the most widely-used framework for notebook-based content, and are the easiest to use for students. However, they are not always the easiest to develop or maintain. We recommend Jupyter for online and student use.

Advantages

Widely used, many tutorials and guides online.
No software installation needed for users.
Many public, free, hubs (including Google Collab).
Large, open-source community.

Disadvantages

Complex and difficult local set-up.
JSON-based file type; hard to maintain.
Limited display and render options.

Learn more about Jupyter Notebooks.

Quarto Notebooks

Quarto is a strong improvement over R Markdown and supports multiple languages. However, it is still in development and is more complicated. We recommend Quarto for development and offline use².

Advantages

Interoperable with R Markdown, but not R specific.
Very rich output and render options.
Easy-to-install locally.
Default, enterprise-supported editor (RStudio).

Disadvantages

No easy-to-use free hubs available.
More complex than comparable notebook formats.
New, still in development.

Learn more about Quarto.

R Markdown Notebooks

R Markdown is an excellent alternative to Jupyter for offline-only applications that only use R.

Advantages

Very widely-used, many tutorials and guides online.
Easy-to-install locally.
Default, enterprise-supported editor (RStudio).
Many render options for output, rich output.

Disadvantages

Idiosyncratic syntax.
No easy-to-use free hubs available.
Only supports R coding, no other languages.

Learn more about R Markdown.

Observable Notebooks

Observable is the newest format on the market, and looks very professional. It is designed for enterprise clients, and is the most complex of the alternatives.

Advantages

Non-language specific framework.
Extremely rich output formats.
Strong dashboarding and interactive support.
Large enterprise developer.

Disadvantages

Large enterprise developer, no free hubs.
Most complex of the alternatives.
New, still in development.

Learn more about Observable and D3.js.

2 Teaching with Jupyter Notebooks

We have tried several ways of using Jupyter Notebooks when teaching, and found that they fit most teaching styles. We have found them particularly effective in:

Lecture.
Flipped classrooms.
Workshops or labs.

You can find advice on lesson planning in these formats in the tabs below.

Direct Instruction or Lectures

Jupyter notebooks are most effective in lecture when you use them as a demonstration tool which students can follow along with.

The power of a Jupyter notebook is the interactive nature of the different cells.
This allows you to enhance your lecture content by immediately and interactively demonstrating principles by running cells and changing their values.

Essentially, you make can your slides or visualizations interactive by running or editing cells.

You can either do this directly, by showing the notebook, or you can turn the notebook into a slideshow using either nbcovert or RISE, which create a RevealJS presentation from your notebook.
- RevealJS is a powerful HTML-based presentation framework, widely used on the web and in computation.
There are also powerful libraries for interactive visualization, such as plotly and ggplotly.³

See Section 3.1 for a guide to creating presentations using Jupyter notebooks.

We have found it is usually best to give students the Jupyter notebook of the presentation, as a kind of “hand-out,” while you demonstrate using the presentation display of the notebook. This avoids the problem of having to make sure students have a suitable presentation display tool installed.

Suggestions for Teaching

Try demonstrating a cell, then asking students to predict what happen when you make a different change. Then do it!
- This works great with classroom response systems such as iClicker or TopHat.
Spend time thinking about how interacting with the cell can show the concept more effectively than a static visualization.
- We have found this to be particularly useful for dynamics in visualizations, such as showing a change.
Spend time on each interactive part of your presentation, and walk through the changes.
Use encapsulation by placing code in auxillary files to make the demonstrations easier to follow.
- If students don’t need to know how it works, only what it does, consider re-writing the code to hide the details.

Flipped Classrooms

A flipped classroom refers to a teaching model where activities traditional done in the classroom are done at while, while activities done at home are done in the classroom (Akçayır and Akçayır (2018)). “Flipping” the lecture demonstration, outlined above, using Jupyter Notebooks is a natural fit.

Most flipped classroom experiences tend to use videos (see Akçayır and Akçayır (2018)), and this is quite feasible with Jupyter Notebooks. Record yourself demonstrating the notebook, and have students follow along. We can done this for some of the COMET notebooks (see our project notebooks for example).

However, the interactivity of notebooks makes them ideal for doing as “pre-reading” assignment instead, or in addition, to videos. The active learning created by interacting with the notebook, and completing self-test exercises, makes them more effective than just doing a reading.

A good flipped-classroom notebook:

Introduces the topic in a narrative, systematic way, and does not require any significant external references to follow along.
Includes regularly-spaced interactive cells, which require students to evaluate and inspect the results.
Has a series of self tests (see Section 3.2) at regular intervals, to check and reinforce student understanding.

Suggestions for Teaching

When in the classroom, we recommend following-up the notebook with a formative or summative assessment using the same skills, but in a new setting or in a more sophisticated way.

For example, you could assign students a pre-reading of classification and clustering before class. In the class, you could then introduce a new dataset and have them explore it using clustering methods.
Many of our COMET notebooks, especially the intermediate ones are built with this structure, where one “Part” of the notebook can be turned into the classroom part of the flipped classroom.⁴

Workshops or Labs

We have also found it effective to teach using Jupyter notebooks in small group settings, such as workshops. A typical Jupyter workshop in our experience:

Divide the students into groups of about 4-5, and have them physically move so that they are seated next to one another.
- This also works well online, using a feature like Zoom’s breakout rooms.
Once they are settled, or before moving people into their breakout rooms, introduce the purpose of the workshop. Identify what students are supposed to do, and how they will interact with the Jupyter Notebooks.
Allow students to work together on the notebooks, while you move around the room discussing with the groups.

It is often effective to design your notebooks so that they have several identifiable “tasks” or stopping points, where you can bring the workshop back together.

Many of our COMET notebooks, especially the intermediate ones are built with this structure.
Make sure you build in time for students to introduce themselves to one another, if this is their first time meeting.

Suggestions for Teaching

When in the classroom, we recommend following-up the notebook with a formative or summative assessment using the same skills, but in a new setting or in a more sophisticated way.

Many of the tools and techniques for flipped classroom instruction work well in a workshop format too. Just make sure there is sufficient support so students can follow the notebooks together.
Encourage students to work together to troubleshoot problems if they encounter them, so you are not running around too often.
An effective strategy is to have the students collaborate on a single “final” version of the notebook together, while experimenting on their own. Nominating one student as the “scribe” is a good way to keep this organized.

At the end of the workshop, having students hand in their Notebook is an effective way of measuring participation, and encourages participation.

3 Developing your own Notebooks for Teaching

It is easier than you might expect to develop notebooks for teaching. Some of our favourite examples are:

Word Embeddings: an advanced, workshop-style, .ipynb format notebook.
Visualization: a basic, lecture-style, introduction with time for experimentation.
Exporting Output: a flipped-classroom style book or workshop for STATA output.

Poke around and see some more!

3.1 Presenting and Slideshows

When teaching with Jupyter, effective presentation skills require a little planning. There are several options, depending on what kind of presentation you want to give.

3.1.1 Presenting a Notebook

Presenting a Notebook as a notebook, such as in a demonstration or workshop, is easy.

In JupyterLab, the easiest way is use the View menu:
- Uncheck all of the un-necessary bars, such as the top bar and status bar.
- Turn on “Simple View”, which only shows your activate notebook tab.
- Turn on “Presentation Mode.”

This will create a large-format, interactive, version of your notebook suitable for presenting on an overhead projector or monitor.

3.1.2 Presenting a Slideshow

If you want to turn your notebook into a slideshow, things are more complicated depending on whether you want it to be interactive or not. However, in general you create a slideshow by designating individual cells are either whole slides, or fragments of slides:

A slide is a single higher-level slide. When the presentation advances from one slide to another, it will “slide” right-to-left.
A sub-slide is like a lower-level slide. When the presentations advances from to a sub-slide, it will “slide” from up-to-down.
A fragment is part of a slide. It appears by sliding up, into the slide, keep the previous content visible. This is how you can reveal information or advance content.

You designate cells as the different part of a presentation by clicking on the gear icon, then selecting the cell. A dropdown menu that says “Slide type” will be visible. Use this to set up your presentation.

If you don’t care about interactivity, at this point you can go to “File > Save and Export Notebook as…” then select “Reveal.js Slides.” This will download an .html file with your presentation in it. Learn more about Reveal.js to see how this file works in more detail.

If you want to run code in your presentation and edit it as you present, things are more complicated. To make your presentation editable, you need to install a JupyterLab extension called RISE.

RISE is easiest to install on your own computer, not on a JupyterHub unless you have administrator privileges.
In the terminal, run pip install jupyterlab_rise then re-launch your server.
You can read more about RISE above; it’s still in development so things might change.

3.2 Writing Self-Tests

Writing self-tests is an important part of providing formative feedback to students. It can be somewhat complicated, but the basic idea is to write cells in your notebooks that look like:

#an R self test

answer_1 <- #fill in the correct value here

test_1()

The function test_1() is stored in an auxillary file, and performs a test on the answer. It also gives feedback to the student, such as whether the answer was correct.

This requires some set-up, and is slightly different for different languages. To make this easier, we provide a detailed guide for R and Python in our writing self-tests documentation.

3.3 Development Tips

Developing notebooks as a one-off is straightforward if you author them in JupyterLab: what you see is what you get. However, if you have a more complex project some planning helps. This includes multiple notebooks, or notebooks you need to collaborate on over time.

We strongly recommend not developing directly in .ipynb notebooks long term. Draft your initial notebook in .ipynb, then switch to another framework for longer-term development.
- The reason is because editing an .ipynb edits the state of the program, making it easy to accidentally evaluate or delete something.
- It’s also hard to maintain and doesn’t play nicely with version control systems like git because the documents are very complicated in structure.
Our recommended format is .qmd which can render .ipynb notebooks from the source code. The underlying document is just text, which makes it easy to edit and maintain.

Using .qmd notebooks is much easier: think of these as the “source code” and the .ipynb as the “output.” This also has an advantage of begin able to create other output formats, like PDFs, websites, or presentations directly from the source code.

4 Teaching Offline

While we think that teaching using a JupyterHub is the best option, that may not always be desired or possible. If you want to use COMET notebooks, or similar teaching tools, without a JupyterHub you have two main options:

Option 1: have students install one of the alternative frameworks.
Option 2: have students install Jupyter locally, on their own computers.

Be prepared to troubleshoot installation issues.

5 Further Reading

You can see some of our other publications on our dissemination page.

6 References

Akçayır, Gökçe, and Murat Akçayır. 2018. ‘The Flipped Classroom: A Review of Its Advantages and Challenges’. Computers & Education 126: 334–45.

Camerer, Colin F, Anna Dreber, Felix Holzmeister, Teck-Hua Ho, Jürgen Huber, Magnus Johannesson, Michael Kirchler, et al. 2018. ‘Evaluating the Replicability of Social Science Experiments in Nature and Science Between 2010 and 2015’. Nature Human Behaviour 2 (9): 637–44.

Graves, Jonathan L, Emrul Hasan, and Trish L Varao-Sousa. 2024. ‘Understanding the Hybrid Classroom in Economics: A Case Study’. International Review of Economics Education 45: 100282.

Kery, Mary Beth, Marissa Radensky, Mahima Arya, Bonnie E John, and Brad A Myers. 2018. ‘The Story in the Notebook: Exploratory Data Science Using a Literate Programming Tool’. In Proceedings of the 2018 CHI Conference on Human Factors in Computing Systems, 1–11.

Knuth, Donald Ervin. 1984. ‘Literate Programming’. The Computer Journal 27 (2): 97–111.

Footnotes

We have taught several of these notebooks to 1st year students during intake events, who were fresh out of high school.↩︎
We use Quarto to develop the COMET project.↩︎
Plotly comes in several flavours for different languages, such as `plotly-r ↩︎
This was actually our original use for the notebooks, before COMET! See Graves, Hasan, and Varao-Sousa (2024)↩︎