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.

Please see Creating NbGrader Assignments for more information about NbGrader.

How did we do?

Codio Fundamentals for LSG

Using Code Formatters

Contact