Table of Contents

Using the JupyterLab Starter Pack

Brock Schmutzler Updated by Brock Schmutzler

JupyterLab is an open-source interactive development environment (created by Project Jupyter) that provides a next-generation Jupyter Notebook interface. To name a few improvements, JupyterLab has a new internal API, an accessible extension ecosystem, an integrated file tree and terminal, and a built-in table of contents for navigating Jupyter Notebooks (instead of having to install an extension). Overall, JupyterLab is very pleasant to use and the same kernels you would need for Jupyter Notebooks work agnostically with JupyterLab.

Creating Codio Assignments

The easiest way to create a Codio assignment with a JupyterLab environment is to use eCornell's JupyterLab Starter Pack because it has "starter files" pre-loaded in Codio's workspace, in addition to running eCornell's JupyterLab and RStudio stack called Ubuntu 22.04 + JupyterLab + RStudio (built from the Codio-certified JupyterLab stack for Ubuntu 22.04 LTS). The JupyterLab and RStudio stack includes several Python packages (e.g., numpy, pandas, seaborn) and R packages (e.g., ggplot2, tidyverse) that are commonly used for data science projects. The JupyterLab Starter Pack files are stored in /home/codio/workspace, whereas the JupyterLab stack is saved at the /home/codio level.

As its name suggests, eCornell's Ubuntu 22.04 + JupyterLab + RStudio stack also has RStudio installed. For help with RStudio, see Using the RStudio Starter Pack.

To use eCornell's JupyterLab Starter Pack, add a new Codio assignment by following these steps:

  1. Select Add assignment > New
    Add new Codio assignment
  2. Select the Starter Pack option as your starting point and then click browse
    Select "Starter Pack" as your starting point
  3. Search All starter packs for "JupyterLab Starter Pack"
    Search for "JupyterLab Starter Pack"
  4. Change your assignment name appropriately and then click Create
    Create assignment with JupyterLab Starter Pack

Editing Codio Assignments

After creating a new assignment, you will be taken to a screen that looks something like this:

Launcher tab in JupyterLab

To edit an assignment:

  1. Click the right sidebar to expand the collapsed Guide page
    Expand collapsed guide page
  2. Click Edit (upper right) to enter the Codio workspace
    Edit mode in Codio workspace
  3. Make your changes and then click Publish in the top Codio menu bar (if the green Publish button is available) or select Education > Publish Assignment from the Codio menu
    Codio menu option: Education > Publish Assignment
If the .codio-jupyter file is in the Codio workspace but there is no Jupyter Notebook (i.e., notebook.ipynb file) in the workspace, you will receive a publishing error because the presence of .codio-jupyter tells Codio to expect a Jupyter Notebook when publishing the assignment.
The name "Using Jupyter Notebooks in JupyterLab" of the Guide Editor page has been changed to "Using Jupyter" as of September 30, 2024.

Adding Jupyter Notebooks

After adding a Jupyter Notebook, see Using Code Formatters for instructions on how to format the code.

To add a Jupyter Notebook to your Codio workspace:

  1. Drag and drop your Jupyter Notebook (e.g., Demo_Notebook.ipynb file) into the workspace directory of the Filetree on the left side of your screen, or you can right-click the assignment name (e.g., Demo Assignment) and select Upload...
    Uploading a Jupyter Notebook
  2. Click the Layout button in the upper-right corner of the Guide Editor and put the name of your Jupyter Notebook file (e.g., Demo_Notebook.ipynb file) in the FILENAME field of Jupyter Lab tab in the Open Tabs section
    Add Jupyter Notebook file name to Jupyter Lab open tab in Guide Layout
  3. Click SAVE AND CLOSE SETTINGS
Note that the LAYOUT is "2 Panels", the TYPE of open tab is "Jupyter Lab", and the PANEL of the open tab is "Panel A". It is important to keep all the settings in this Guide Layout configuration, so a closer look is shown in the image below.
Guide Layout configuration

Creating New Stacks

When you create an assignment using eCornell's JupyterLab Starter Pack, the assignment comes with an underlying software stack called Ubuntu 22.04 + JupyterLab + RStudio. Since each series of courses should have its own stack, it is important to create a new stack for your courses by following the steps below.

Before reading the steps below, please be advised of the following warning:

DO NOT create a new version of the Ubuntu 22.04 + JupyterLab + RStudio stack because that new version would be used by future assignments created from the JupyterLab Starter Pack. If you believe the Ubuntu 22.04 + JupyterLab + RStudio stack should be updated, contact a member of the Instructional Technologies Group (ITG) for assistance.
  1. Go to Project > Stack > Create New...
    Go to Project > Stack > Create New...
  2. Make sure New Stack is selected, give your stack a name that matches the series of courses (e.g., DEMO120s Stack), select Public, and make eCornell the owner
    Create new stack for a series of courses
  3. Click CREATE and click YES when prompted with the CHANGE STACK CONFIRMATION dialog box. After clicking YES, you should see a message saying Stack build in progress. If you receive a strange error message, click CREATE again and the stack build should begin this time.
    Confirm stack update
    Creating new stack
  4. After your stack has been created, go to Project > Stack > Settings... to make sure the assignment is using the new stack you created. If your new stack is the CURRENT STACK for your assignment, proceed to step 6. If the CURRENT STACK for your assignment is still Ubuntu 22.04 + JupyterLab + RStudio, complete step 5 before going to step 6.
    Go to Project > Stack > Settings
  5. If the CURRENT STACK for your assignment is not the new stack you created, make sure you change the CURRENT STACK to your new stack before installing or updating any software. After changing the CURRENT STACK to your newly created stack, proceed to step 6.
    1. Click the drop-down menu to search for your new stack
      Check to make sure new stack has been loaded
    2. Search for your new stack (e.g., DEMO120s Stack)
      Search for your new stack
    3. Select your new stack (e.g., DEMO120s Stack) and click SAVE
      Select your new stack
    4. Confirm the stack change by entering the confirmation code in the CHANGE STACK CONFIRMATION dialog box and reload your browser after you receive a message saying Stack updated successfully
      Confirm stack change
      Stack updated successfully
  6. Update and/or install software on your new stack and then create a new version by going to Project > Stack > Create New... and selecting New Stack Version. Make sure to write a concise and descriptive CHANGELOG entry.
    Create new version of your new stack
  7. Go to Project > Stack > Settings... to confirm that a new stack version has been created and make sure that VERSION is set to Use the latest version
    Check that new stack version is created and being used
  8. Publish your assignment with the new stack version and write a concise and descriptive CHANGELOG entry. It may take a few minutes for the publishing process to complete and return a SUCCESSFUL message.
    Publish your assignment with new stack version
    Successful publish after changing to new stack version

Configuring Workspace Starter Files

The starter files in /home/codio/workspace are:

  • .guides/load.js
  • .guides/styles.css
  • .codio
  • .codio-jupyter
  • .codio-menu
  • .settings
  • nbgrader_config.py

For most use-cases, you will not need to modify any of these files. However, if you need modified versions for a specific course, high-level instructions are provided in the subsections below. When in doubt, please contact a member of the Instructional Technologies Group (ITG) for assistance.

If you are not using NbGrader, we recommend removing the .codio-jupyter file so that NbGrader does not process the Jupyter Notebooks in your Codio workspace. Even though it is not necessary to remove the .codio-jupyter file, doing so is beneficial because it will take less time to publish your assignment (since the NbGrader scripts are not running in the background). If you delete .codio-jupyter from your workspace, you should also remove the nbgrader_config.py file — otherwise, students will see the nbgrader_config.py file in their workspace when they open the assignment in Canvas. (Students do not see nbgrader_config.py when .codio-jupyter is present.)
.guides/load.js

The file .guides/load.js is a script that pulls guide text from AWS S3. It looks like this:

$("#guide").load("https://ecornell.s3.amazonaws.com/Codio/Reuseables/JupyterLab/JupyterLab_Guide.txt");

If you need to modify the text on the collapsable Guide page, copy the text file JupyterLab_Guide.txt from the S3 folder Codio/Reusables/JupyterLab and put a modified version in a folder on S3 that is specific to your series of courses and replace the link in load.js — e.g.,

$("#guide").load("https://ecornell.s3.amazonaws.com/Codio/Courses/DEMO120s/JupyterLab_Guide.txt");

DO NOT modify the JupyterLab_Guide.txt file in the S3 folder Codio/Reusables/JupyterLab because those changes will propagate to ALL courses whose guide text is linked to that file. The only people allowed to modify Codio/Reuseables/JupyterLab/JupyterLab_Guide.txt are members of the Instructional Technologies Group (ITG). Please contact ITG if you find a typo or believe the text should be changed.

.guides/styles.css

The file .guides/styles.css imports a CSS stylesheet from S3:

@import "https://ecornell.s3.amazonaws.com/Codio/CSS/styles.css";

The stylesheet Codio/CSS/styles.css controls the look of HTML elements in the Codio guide and is common to most Codio units developed by eCornell.

DO NOT modify the styles.css file in the S3 folder Codio/CSS because those changes will propagate to ALL courses linked to that file. In the unlikely scenario that you need to include additional styling elements, you can add them below the import statement in the .guides/styles.css file for your course-specific Codio units.
.codio

The .codio file contains code that configures the JupyterLab preview button that appears in the Codio menu bar across the top of your screen:

JupyterLab preview button configuration in .codio file

As shown in the image above, the contents of .codio look like this:

{
// Preview button configuration
"preview": {
"JupyterLab": "https://{{domain3000}}/lab"
}
}

Clicking the JupyterLab preview button opens an instance of JupyterLab while you are in Edit mode:

JupyterLab preview button opens Launcher tab

You have access to relevant JupyterLab file by opening the File Browser (click the folder icon):

JupyterLab preview File Browser

Note that this JupyterLab preview tab in Edit mode is different than what you see when you are in Preview mode (i.e., when you click the Preview button in the upper-right corner of the Guide Editor tab):

Edit mode to Preview mode

Preview mode will show you what the Codio unit looks like when it is embedded in Canvas:

Codio Jupyter Lab preview

In particular, note that the open tab is labeled Codio Jupyter Lab (the name is partially cutoff in the image). This indicates that the Jupyter Notebook is being served through Codio's own JupyterLab environment because you have specified the notebook file as an Open Tab with a TYPE of Jupyter Lab, as shown in the Adding Jupyter Notebooks section of this article. You can think of the Codio Jupyer Lab environment as a wrapper that ensures JupyterLab is properly integrated with Codio (without having to configure any system level settings manually). More on this aspect in the Creating NbGrader Assignments below.

.codio-jupyter

The .codio-jupyter file is intentionally blank — its main purpose is to tell Codio to use NbGrader, but it can also be used to configure NbGrader. For more details, please see the Codio documentation on NbGrader. That being said, here is a short synopsis:

  • The presence of .codio-jupyter in /home/codio/workspace tells Codio to process all the Jupyter Notebooks in your workspace using the JupyterLab extension nbgrader (more on NbGrader in the last section of this article).
  • The .codio-jupyter file can be left blank — with all the NbGrader configuration settings specified in the nbgrader_config.py file — but you can also configure NbGrader by writing code in .codio-jupyter.
  • Settings in nbgrader_config.py take precedence over configuration settings in .codio-jupyter.
We recommend leaving .codio-jupyter blank and using nbgrader_config.py for all configuration settings because doing so offers more flexibility in your configuration (e.g., you can make custom pre-processors) and settings in nbgrader_config.py override those in .codio-jupyter.
If you are not using NbGrader for an assignment and want to shorten the time it takes to publish the assignment, you can remove the .codio-jupyter file from the Codio workspace. Codio uses the presence of /home/codio/workspace/.codio-jupyter to trigger NbGrader, so removing .codio-jupyter speeds up publishing time because Codio does not run NbGrader scripts in the background. If you remove .codio-jupyter, you should also remove the nbgrader_config.py file — otherwise, students will see the nbgrader_config.py file in their workspace (students do not see it when .codio-jupyter is present).
.codio-menu

The .codio-menu file controls which menu options are shown to students in Canvas:

{
"Logo": false,
"Codio": false,
"Project": {
"Restart Box...": true,
"Resync File Tree": false,
"Export as Zip": false,
"Settings...": false,
"Stack": false,
"Permissions...": false,
"Box Info": false,
"Reset Box...": false,
"Create Copy...": false,
"Share...": false,
"QR Code for Preview URL": false,
"Delete...": false,
"Exit": false
},
"File": false,
"Edit": false,
"Find": false,
"View": false,
"Tools": false,
"Education": {
"Mark as Completed": true,
"Code Comments": false,
"Earsketch": false,
"Jupyter Lab": false
},
"Help": false,
"Run": false,
"Debugger": false,
"Status": false,
"Preview": false,
"Toggle sections list": false,
"Online": false
}

The configuration that comes with the JupyterLab Starter Pack only shows the options Project > Restart Box... and Education > Mark as Completed in the top Codio menu bar. These are typically the only options that are needed for a Codio unit using JupyterLab because all student work is done within the JupyterLab environment.

Project > Restart Box... allows students to restart their Codio box without losing their saved work. This is useful, for example, when a notebook becomes unresponsive or you receive the pop-up message "Jupyter Lab is not installed." After restarting, students will need to reload their browser.

If no auto-grading is necessary and facilitators will not be reviewing the work (e.g., in an ungraded practice activity), you can disable the Education > Mark as Completed button in the ASSIGNMENT settings (Overview > Settings) by toggling on the option DISABLE MARK AS COMPLETED (make sure to click the Save Changes button afterwards):

Assignment settings for an ungraded Codio unit
Disabling the Education > Mark as Completed button causes it to appear "grayed out" to indicate that it cannot be selected. All graded assignments (auto-graded or not) should have the MARK AS COMPLETED button enabled.

If you need to expose more Codio menu options to students, you can follow these steps:

  1. Copy /Codio/Reusables/JupyterLab/codio-menu.txt
  2. Add codio-menu.txt to a course-specific S3 folder (e.g., /Codio/Courses/DEMO120s)
  3. Modify the content of your course-specific codio-menu.txt file as needed
  4. Modify the file /home/codio/startup.sh as directed in How to Centralize the .codio-menu to One Location (steps 3b, 4b, and 5)
  5. Create a new course-specific stack version (DO NOT create a new version of Ubuntu 22.04 + JupyterLab + RStudio)

For example, here is a .codio-menu.txt file that would also expose the Project > Export as Zip menu option:

{
"Logo": false,
"Codio": false,
"Project": {
"Restart Box...": true,
"Resync File Tree": false,
"Export as Zip": true,
"Settings...": false,
"Stack": false,
"Permissions...": false,
"Box Info": false,
"Reset Box...": false,
"Create Copy...": false,
"Share...": false,
"QR Code for Preview URL": false,
"Delete...": false,
"Exit": false
},
"File": false,
"Edit": false,
"Find": false,
"View": false,
"Tools": false,
"Education": {
"Mark as Completed": true,
"Code Comments": false,
"Earsketch": false,
"Jupyter Lab": false
},
"Help": false,
"Run": false,
"Debugger": false,
"Status": false,
"Preview": false,
"Toggle sections list": false,
"Online": false
}

Project > Export to Zip gives students the ability to export all their workspace files to a ZIP file.
.settings

The .settings file controls the text editor settings of the Guide Editor. This file is automatically generated by Codio when the Guide is created — you will not need to make any changes to the .settings file.

nbgrader_config.py

The nbgrader_config.py file contains all (or most) of the configuration settings for NbGrader:

from nbgrader.preprocessors import NbGraderPreprocessor

class ClearTracebacks(NbGraderPreprocessor):
"""
Custom preprocessor to either remove traceback messages (i.e., `output["traceback"] = []`)
or replace them with another message (i.e., `output["traceback"] = ["replacement_message"]`).
"""
def preprocess_cell(self, cell, resources, cell_index):
# Remove or replace traceback messages in graded cells.
if "nbgrader" in cell.metadata and cell.metadata.nbgrader.grade == True:
for output in cell.outputs:
if "traceback" in output:
output["traceback"] = ["Traceback messages have been hidden for graded cells."]
# Remove or replace traceback messages in student answer cells.
#if "nbgrader" in cell.metadata and cell.metadata.nbgrader.solution == True:
# for output in cell.outputs:
# if "traceback" in output:
# output["traceback"] = ["Traceback messages have been hidden for solution cells."]
return cell, resources

# Retrieve the nbgrader configuration.
c = get_config()

# Configuration for the student version of the notebook that opens in Canvas.
c.ClearHiddenTests.begin_test_delimeter = "BEGIN HIDDEN TESTS"
c.ClearHiddenTests.end_test_delimeter = "END HIDDEN TESTS"
c.LockCells.lock_all_cells = False
c.LockCells.lock_grade_cells = True
c.LockCells.lock_readonly_cells = True
c.LockCells.lock_solution_cells = True
c.ExecutePreprocessor.interrupt_on_timeout = True
c.ExecutePreprocessor.timeout = 180
c.ClearSolutions.code_stub = {
"julia": "# YOUR CODE HERE\nerror(\"Your code is missing.\")\n# END OF YOUR CODE",
"python": "# YOUR CODE HERE\nraise NotImplementedError(\"Your code is missing.\")\n# END OF YOUR CODE",
"R": "# YOUR CODE HERE\nstop(\"Your code is missing.\")\n# END OF YOUR CODE",
}

# Clear hidden tests and tracebacks from the student feedback report
# that students see after their assignments are Marked as Completed.
c.GenerateFeedback.preprocessors = [
"nbgrader.preprocessors.GetGrades",
"nbconvert.preprocessors.CSSHTMLHeaderPreprocessor",
"nbgrader.preprocessors.ClearHiddenTests",
ClearTracebacks,
]

If you want to remove traceback messages from student answer cells in Codio's student feedback report, uncomment the four lines of code below the comment # Remove or replace traceback messages in student answer cells (not recommended for most use cases). If you do not want to clear hidden tests and tracebacks from Codio's student feedback report, comment out the last six lines. For more details, see the NbGrader documentation on the nbgrader_config.py file.

Creating NbGrader Assignments

You can perform auto-grading in Jupyter Notebooks using a JupyterLab extension called NbGrader (i.e., nbgrader).

If you are not using NbGrader, you can remove the .codio-jupyter and nbgrader_config.py files. This is not necessary, but the advantage is that publishing your Codio assignment will take less time because the absence of a .codio-jupyter file tells Codio to bypass the NbGrader processing that happens in the background when you publish an assignment with the .codio-jupyter file in /home/codio/workspace. The process for creating an ungraded activity in Canvas in the similar to the one described in the Ungraded Activities in Canvas section of Using the RStudio Starter Pack.
Codio Assignment

To create an NbGrader assignment in Codio:

  1. Add a Jupyter Notebook (see Adding Jupyter Notebooks section) that contains all the "solution code" needed to successfully run all the cells in the entire notebook
  2. Put ### BEGIN SOLUTION and ### END SOLUTION delimiters around the "solution code" you want students to provide when they work through the notebook in Canvas
    Include ### BEGIN SOLUTION and ### END SOLUTION delimiters around solution code
  3. In Preview mode, select Nbgrader > Create assignment from the JupyterLab menu
    Select "NbGrader > Create assignment" from JupyterLab menu
    Create assignment right sidebar
  4. In the right sidebar that appears, specify each cell as either "Autograded answer" type or "Read-only" type:
    1. "Autograded answer" type for each cell with ### BEGIN SOLUTION and ### END SOLUTION
    2. "Read-only" type for all other cells (to prevent students from modifying or deleting the cell)
      Specify cells as "Autograded answer" or "Read-only
    3. Below each "Autograded answer" cell you want to test, add a Code cell of "Autograded tests" type — make each "Autograded tests" cell worth one point even if there are multiple tests in the cell. NOTE: If you want some (or all) tests to be hidden from students in Canvas, put the code for those tests between ### BEGIN HIDDEN TESTS and ### END HIDDEN TESTS delimiters (similar to putting solution code between ### BEGIN SOLUTION and ### END SOLUTION delimiters).
      Add Code cell of type "Autograded tests"
  5. Unselect View > Appearance > Show Right Sidebar to close "Create assignment" sidebar (or press command+J)
    Unselect "View > Appearance > Show Right Sidebar"
  6. Save and checkpoint your changes by clicking the disk icon in the upper-left corner of your notebook tab (or press command+S)
    Save and checkpoint your changes
  7. Check that all your tests successfully pass by clicking the Validate button in the top menu bar of your notebook tab
    Click Validate button to check that all NbGrader tests pass
    Successful result of the Validate button
  8. Publish your assignment by selecting Education > Publish Assignment from the top Codio menu
    Publish your Codio assignment after creating NbGrader assignment
You can also check your NbGrader assignment by selecting Education > Validate Jupyter from the Codio menu — this runs a Codio script that returns more detailed information in the case when validation fails.
Sometimes the Validate button in Jupyter or the Education > Validate Jupyter script in the Codio menu will indicate that there is something wrong with your NbGrader assignment even though everything is fine. If you believe there is nothing wrong with your NbGrader assignment, try publishing the Codio unit. If the Codio unit publishes successfully, then all should be good.
If a cell has an NbGrader type of "Autograded answer" and none of the code in that cell is wrapped with ### BEGIN SOLUTION ... ### END SOLUTION delimiters, then the entire contents of the cell will be replaced with ### YOUR CODE HERE ... ### END OF YOUR CODE.
If ### BEGIN SOLUTION ... ### END SOLUTION appears in a cell that is not marked as an "Autograded answer" cell, you will receive a publishing error.
Canvas Assignment

To set up your Codio assignment in Canvas:

  1. Create a new Canvas assignment page
    Create Canvas assignment
  2. Configure assignment settings
    1. Use External Tool submission
    2. Create Codio Projects group
    3. Display grade as Percentage
      Canvas assignment external tool submissioin
  3. Configure Codio assignment settings (make sure to Save Changes for each setting)
    1. Read Only with Resubmit
      Read-only with resubmit
    2. ASSESSMENTS GRADING
      Assessments grading
    3. ASSESSMENTS GRADING and TEACHERS GRADING (does not have to be 50/50)
      Assessments grading and Teachers grading
  4. Test in Student View
    1. Enter solution code between # YOUR CODE HERE and # END OF YOUR CODE (delete the stop("Your code is missing.") command)
      Enter solution code in Jupyter Notebook
    2. Save your changes by pressing command+S
    3. Go to the Education menu and select Mark as Completed
    4. Check that Codio's student feedback report has the expected output
      Codio's student feedback form
      Student's answer in Codio's feedback report
      Test cell in Codio's student feedback report
Ungraded Assignments

You can also use NbGrader to create ungraded assignments. One advantage of doing this is that NbGrader provides an easy way to control whether a cell can be edited or deleted by simply changing the cell type. The steps are similar to creating a graded assignment with the following tweaks.

  1. Modify all the "Autograded tests" cells in the notebook in one of two ways:
    1. Make all "Autograded tests" cells worth zero points (with no hidden tests) in the notebook
    2. Change all "Autograded tests" cells to "Read-only" cells in the notebook
  2. Toggle off all the grading settings (i.e., Teachers, Assessments, Script) for the Codio unit

In Canvas, embed the Codio unit in a Canvas page using the Rich Content Editor (as opposed to creating a Canvas assignment), as described in the Ungraded Canvas Assignments section of Using the RStudio Starter Pack.

How did we do?

Codio Fundamentals for LSG

Using Code Formatters

Contact