Instructor guide

Instructor guide#

While this is meant as internal documentation for the instructor, others are welcome to read it.

Adding/updating packages#

  1. Modify the dependencies in pyproject.toml

  2. Run

    make update_packages

  3. Manually update the notebooks with interactivity

Slides#

While the lecture notes can be viewed as a plain notebook, they are also visible as slides.

make slides lec=N

Site#

The site is generated using JupyterBook and deployed to ReadTheDocs. Markdown (.md) files and the files and folders that start with an underscore (_) are related to JupyterBook.

Publishing#

This repository produces separate versions of the course site for Columbia and NYU. The source of truth is the main branch; the columbia and nyu branches contain generated, school-specific source files and their rendered sites.

For each school, the workflow:

  1. Checks out the repository and installs the Python dependencies.

  2. Switches to the corresponding school branch and merges the pushed branch using Git’s ours strategy. It then restores the pushed branch’s working tree. This records that the school branch includes the source revision without using the school branch’s generated files as merge inputs.

  3. Commits that preliminary source tree.

  4. Runs school_ci.sh with the school ID. The script removes files that do not belong in a published school version, including development tools and tests.

  5. Calls school.sh to render school-specific templates.

    • Jinja templating is used throughout the source files (Markdown, notebooks, etc.), rendered using nbconvert with a custom preprocessor.

    • Variables (such as Columbia University, https://courseworks2.columbia.edu/courses/233960, and Reader) are replaced with the values from the configuration file for the selected school.

    • It uses {% if id == "columbia" %} and {% if id == "nyu" %} conditionals for school-only content; the generated files must contain neither Jinja tags nor identifiers for the other school.

    • For notebooks, school.sh first removes cells tagged for the other school (columbia-only or nyu-only) and cells tagged remove. It then renders each remaining cell source with the same Jinja variables, while resetting notebook kernel metadata to the default Python kernel for Colab.

  6. Runs make site, which builds the Jupyter Book HTML into _build/html.

  7. When the push is to main, the workflow pushes the amended commit to the relevant school branch. Pushes to other branches still render both versions and upload their HTML, but do not update either published branch.

  8. ReadTheDocs is notified of updates to the school-specific branches, which are then built as separate versions.

The HTML can be downloaded as an artifact from the latest Publish Action.

Building locally#

  1. Stage changes in Git, as they will be overwritten.

  2. If on the columbia branch, run:

    make site

  3. If on main or other branches, run:

    ./extras/scripts/school_ci.sh <school>

Notebook cleanup#

To ensure that notebooks have the correct execution order and output, run them non-interactively.

./extras/scripts/update.sh <file>.ipynb

Start of class checklist#

  • Put out attendance sheet

  • Connect to screen

  • Start Amphetamine

  • Set phone and laptop to Do Not Disturb

  • Run lecture notebook

  • Put out power strips

Data sets#

Canonical copies of data are in a Google Drive folder, synced locally with Google Drive for desktop. Data is then compressed and uploaded to a Google Cloud Storage bucket via Terraform. Descriptions of the data sets.

gcloud auth application-default login

Student enrollment activity#

This only shows students coming off the wait list.

  1. Visit SSOL

  2. View the Wait List Activity

  3. Open the Console

  4. Paste the script

  5. Do the same for the other section(s)

End of course#

  1. Open CourseWorks

  2. Go to Grades

  3. Update the curve

    1. Export -> Export Entire Gradebook

    2. In the curve notebook, update the CSV filename

    3. Re-run the notebook

    4. Spot-check the new cutoffs

    5. Update the course grading scheme

  4. Calculate the attendance scores

  5. Confirm all Gradebook cells are filled in

Contacts#