instructor_guide.md

Instructor guide

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

Adding/updating packages

1. Modify environment.yml

2. Run

   ./extras/scripts/update_packages.sh

3. Manually update the notebooks with interactivity {% if id == "nyu" -%}

4. Update environment in JupyterHub

   mamba env update --file extras/environment.lock.yml --prune

{% endif -%}

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.

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 {{school_slug}} branch, run:

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

3. If on main or other branches, run:

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

Checking broken links

Once the site is built, you can check broken links with:

make linkcheck

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 HDMI
• On laptop, turn on:
  • Focus mode
  • Amphetamine
• Set phone to Do Not Disturb
• Run lecture notebook {% if id == "columbia" -%}
• Set up Zoom recording

{% else %}

• Set placeholders
• Adjust lights
• If first couple classes: take attendance for recording Academic Engagement {% endif -%}

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

{% if id == "columbia" -%}

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)

Updating the curve

1. Open {{lms_name}}
2. Go to Grades
3. Export -> Export Entire Gradebook
4. In the curve notebook, update the CSV filename
5. Re-run the notebook
6. Spot-check the new cutoffs
7. Update the course grading scheme {% else -%}

JupyterHub troubleshooting

Most of the issues are around Plotly rendering / PDF export. Things that have been hit repeatedly:

• Embedded image error in nbconvert
  • As of 11/30/24, JupyterHub is using too new a version of pandoc in the base environment.
• Plotly JupyterLab support
  • Needs to be installed on base environment as well
• PDF export fidelity
• orjson attribute error through Plotly
• PDF exporting crashes when there's a lot of data being output / in plots

See also: comments in environment.yml. Attempted to distill into the student troubleshooting guide. {%- endif %}

Contacts

{% if id == "columbia" -%}

• SIPA Academic Affairs
  • Primary contact: Jenny Labuga-Rumenik
• Job posts: [email protected] {%- else %}
• Wagner Faculty Support
  • Primary contact: Michelle Spatz
• Job posts: [email protected] {%- endif %}