jupyter-nbgrader-helper

Installation

• clone repository
• python setup.py sdist
• pip install dist/nbhelper-<VERSION>.tar.gz

I probably won't add this to PyPI since it lacks polish and have no plans to update or maintain it outside of when I am using it, that being said, I don't see any of the functionality here breaking anytime soon.

Usage

Override settings

• use these to change directories if you aren't using the default directory structure of nbgrader
• use select to perform a check or fix only on specific students

Fixing notebooks

• if you forgot to make your notebook into an assignment before releasing or have answers without nbgrader metadata (try not to do this!), use add
• if you want to add extra test cells after releasing an assignment (you're better off adding empty test cells just in case and modifying them later), use add
• if nbgrader autograde is complaining about test case points or duplicate grade_ids, use fix (and instruct students not to mess with cells)
• if there are other metadata issues with cells, use meta to fix assignment cells with the correct metadata from the source
• if there are still issues with the students notebook, use rmcells to remove everything not specifically part of the assignment
• if the notebook still won't autograde, use forcegrade (these won't appear in gradebook.db and feedback won't be generated from them)
• if you are having permission issues, use chmod (convenient wrapper to run chmod on all submissions)

Getting grades

• use the arguments under notebook checks after running nbgrader autograde and generate_feedback

Emailing feedback

• if you don't have an exchange setup, or your university has a policy against students viewing the grades and feedback of others (nbgrader release_feedback uses the outbound exchange which all students have read permission for)
• use zip to collect all feedbacks
• use ckdir to test your command and folder structure
• replace ckdir with email in your command and follow the prompts

Backing up

• REMEMBER TO BACKUP YOUR NOTEBOOKS REGULARLY with backup, submitted and source are most important

Deprecated features

• these probably still work, but aren't really useful

Command Line Interface

usage: nbhelper.py [-h] [--nbhelp]
                   [--cdir path] [--sdir path] [--odir path]
                   [--add AssignName NbName.ipynb]
                   [--fix AssignName NbName.ipynb]
                   [--meta AssignName NbName.ipynb]
                   [--forcegrade AssignName NbName.ipynb]
                   [--sortcells AssignName NbName.ipynb]
                   [--rmcells AssignName NbName.ipynb]
                   [--select StudentID [StudentID ...]]
                   [--info AssignName]
                   [--mknb AssignName NbName.ipynb FileName.extension]
                   [--moss AssignName] [--getmoss]
                   [--dist AssignName] [--fdist AssignName]
                   [--email AssignName|zip NbName.html|feedback.zip]
                   [--ckdir AssignName NbName.extension]
                   [--ckgrades AssignName]
                   [--ckdup NbName.extension]
                   [--chmod rwx AssignName]
                   [--avenue-collect submissions.zip AssignName]
                   [--zip AssignName [AssignName ...]]
                   [--zipfiles NbName.html [NbName.html ...]]
                   [--backup nbgrader_step]

A collection of helpful functions for use with jupyter nbgrader. Designed to
be placed in <course_dir>/nbhelper.py by default with the structure:
<course_dir>/<nbgrader_step>/[<student_id>/]<AssignName>/<NbName>.<ipynb|html>
where nbgrader_step = source|release|submitted|autograded|feedback

optional arguments:
  -h, --help            show this help message and exit
  --nbhelp              READ THIS FIRST

override settings:

  --cdir path           Override path to course_dir (default: current
                        directory)
  --sdir path           Override path to source directory
  --odir path           Override path to the submitted, autograded, or
                        feedback directory
  --select StudentID [StudentID ...]
                        Select specific students to fix their notebooks
                        without having to run on the entire class (WARNING:
                        moves student(s) to <course_dir>/nbhelper-select-tmp
                        then moves back unless an error was encountered)

notebook fixes:

  --add AssignName NbName.ipynb
                        Add missing nbgrader cell metadata and test cells to
                        submissions using the corresponding file in source as
                        a template by matching function names (python only),
                        template must be updated with nbgrader cells
  --fix AssignName NbName.ipynb
                        Update test points by using the corresponding file in
                        source as a template and matching the cell's grade_id,
                        also combines duplicate grade_ids
  --meta AssignName NbName.ipynb
                        Fix cell metadata by replacing with that of source,
                        matches based on grade_id
  --forcegrade AssignName NbName.ipynb
                        For particularly troublesome student notebooks that
                        fail so badly they don't even autograde or produce
                        proper error messages (you should run this command
                        with --select), this partially does autograders job:
                        combines the hidden test cases with the submission but
                        places it in <course_dir>/nbhelper-
                        autograde/<student_id>/<AssignName>/<NbName.ipynb>
                        then tries executing it via command line. You can also
                        run and test this notebook yourself, then move this
                        'autograded' notebook to the autograded directory and
                        use --dist to 'grade' it (make sure failed tests
                        retain their errors or they'll count as 'correct',
                        grades are not entered in gradebook.db)
  --sortcells AssignName NbName.ipynb
                        Sort cells of student notebooks to match order of
                        source, matches based on grade_id
  --rmcells AssignName NbName.ipynb
                        MAKE SURE YOU BACKUP FIRST - Removes all student cells
                        that do not have a grade_id that matches the source
                        notebook (and sorts the ones that do) - this function
                        is destructive and should be used as a last resort
  --chmod rwx AssignName
                        Run chmod rwx on all submissions for an assignment
                        (linux only)

notebook checks:

  --moss AssignName     Exports student answer cells as files and optionally
                        check with moss using <course_dir>/moss/moss.pl
  --getmoss             Downloads moss script with your userid to
                        <course_dir>/moss/moss.pl then removes it after use
  --dist AssignName     Gets distribution of scores across test cells from
                        autograded notebooks and writes each student's results
                        to <course_dir>/reports/<AssignName>/dist-<NbName>.csv
  --fdist AssignName    Gets distribution of scores across test cells from
                        feedback (factoring in manual grading) and writes each
                        student's results to
                        <course_dir>/reports/<AssignName>/fdist-<NbName>.csv
  --ckdir AssignName NbName.extension
                        Check <course_dir>/feedback directory (change with
                        --odir) by printing studentIDs and matching files to
                        make sure it is structured properly
  --ckgrades AssignName
                        Checks for consistency between 'nbgrader export',
                        'dist', and 'fdist', and writes grades to
                        <course_dir>/reports/<AssignName>/grades-<NbName>.csv

notebook management:

  --email AssignName|zip NbName.html|feedback.zip
                        Email feedback to students (see EMAIL_CONFIG in
                        script, prompts for unset fields)
  --avenue-collect submissions.zip AssignName
                        Basically zip collect but tailored to avenue (LMS by
                        D2L), uses <course_dir>/classlist.csv to lookup
                        Student IDs using names from submissions, overwrites
                        submissions in submitted directory, backup first!
  --zip AssignName [AssignName ...]
                        Combine multiple feedbacks into
                        <course_dir>/feedback/<student_id>/zip/feedback.zip
  --zipfiles NbName.html [NbName.html ...]
                        Same as zip but matches files instead of assignment
                        folders
  --backup nbgrader_step
                        Backup nbgrader_step directory to
                        <course_dir>/backups/<nbgrader_step-mm-dd-hh-mm>.zip

deprecated features:

  --info AssignName     Get some quick info (student id, file size, cell
                        count, total execution count, [grade id : execution
                        count]) of all submissions and writes to
                        <course_dir>/reports/<AssignName>/info-<NbName>.csv
  --mknb AssignName NbName.ipynb FileName.extension
                        Try and make an autogradable notebook from a plain
                        source code file by cramming everything in the first
                        answer cell then appending all the test cells
  --ckdup NbName.extension
                        Checks all submitted directories for NbName.extension
                        and reports subfolders containing multiple files of
                        the same extension