Usage and Output

Usage and Output#

Otter Assign is called using the otter assign command. This command takes in two required arguments. The first is master, the path to the master notebook (the one formatted as described above), and the second is result, the path at which output shoud be written. Otter Assign will automatically recognize the language of the notebook by looking at the kernel metadata; similarly, if using an Rmd file, it will automatically choose the language as R. This behavior can be overridden using the -l flag which takes the name of the language as its argument.

The default behavior of Otter Assign is to do the following:

  1. Filter test cells from the master notebook and create test objects from these

  2. Add Otter initialization, export, and Notebook.check_all cells

  3. Clear outputs and write questions (with metadata hidden), prompts, and solutions to a notebook in a new autograder directory

  4. Write all tests to the notebook metadata of the autograder notebook

  5. Copy autograder notebook with solutions removed into a new student directory

  6. Remove all hidden tests from the notebook in the student directory``

  7. Copy files into autograder and student directories

  8. Generate a Gradescope autograder zipfile from the autograder directory

  9. Run all tests in autograder/tests on the solutions notebook to ensure they pass

These behaviors can be customized using command line flags; see the CLI Reference for more information.

An important note: make sure that you run all cells in the master notebook and save it with the outputs so that Otter Assign can generate the test files based on these outputs. The outputs will be cleared in the copies generated by Otter Assign.

Export Formats and Flags#

By default, Otter Assign adds an initialization cell at the top of the notebook with the contents

# Initialize Otter
import otter
grader = otter.Notebook()

To prevent this behavior, add the init_cell: false configuration in your assignment metadata.

Otter Assign also automatically adds a check-all cell and an export cell to the end of the notebook. The check-all cells consist of a Markdown cell:

To double-check your work, the cell below will rerun all of the autograder tests.

and a code cell that calls otter.Notebook.check_all:

grader.check_all()

The export cells consist of a Markdown cell:

## Submission

Make sure you have run all cells in your notebook in order before running the cell below, so
that all images/graphs appear in the output. **Please save before submitting!**

and a code cell that calls otter.Notebook.export with HTML comment filtering:

# Save your notebook first, then run this cell to export.
grader.export("/path/to/notebook.ipynb")

For R assignments, the export cell looks like:

# Save your notebook first, then run this cell to export.
ottr::export("/path/to/notebook.ipynb")

These behaviors can be changed with the corresponding assignment metadata configurations.

Note: Otter Assign currently only supports HTML comment filtering. This means that if you have other cells you want included in the export, you must delimit them using HTML comments, not using cell tags.

Otter Assign Example#

Consider the directory stucture below, where hw00/hw00.ipynb is an Otter Assign-formatted notebook.

hw00
├── data.csv
└── hw00.ipynb

To generate the distribution versions of hw00.ipynb (after changing into the hw00 directory), you would run

otter assign hw00.ipynb dist

If it was an Rmd file instead, you would run

otter assign hw00.Rmd dist

This will create a new folder called dist with autograder and student as subdirectories, as described above.

hw00
├── data.csv
├── dist
│   ├── autograder
│   │   ├── hw00.ipynb
│   │   └── tests
│   │       ├── q1.(py|R)
│   │       └── q2.(py|R)  # etc.
│   └── student
│       ├── hw00.ipynb
│       └── tests
│           ├── q1.(py|R)
│           └── q2.(py|R)  # etc.
└── hw00.ipynb

In generating the distribution versions, you can prevent Otter Assign from rerunning the tests using the --no-run-tests flag:

otter assign --no-run-tests hw00.ipynb dist
Contents