This grading script is intended to automate the grading process of CS 161 by automatically applying various grading policies such as slip days and drops as well as allowing for per-student accommodations and extensions on assignments.
The script will take in four required files: a CSV roster export from CalCentral, a CSV grade report from Gradescope, a CSV containing assignment category data, and a CSV containing assignment data. You may optionally also specify a CSV file containing per-student extensions and a CSV file containing per-student accommodations for homework drops and slip days.
The script automatically runs all the grade calculations and outputs a grade report for each student to STDOUT, formatted as a CSV. This may then be imported into any spreadsheet program for further analysis.
You will need Python 3 to run this script.
python3 main.py <roster> <grades> <categories> <assignments> [--clobbers CLOBBERS] [--extensions EXTENSIONS] [--accommodations ACCOMMODATIONS] -o output.csv
Example inputs are provided in the examples folder, with a single student and
the assignment/category layout taken from Summer 2020.
The CalCentral roster is used to output grades for only students who are enrolled in the class. The following columns are required (and are automatically generated by CalCentral):
| Column | Description |
|---|---|
Name |
A student's name, in Last, First format |
Student ID |
A student's SID |
Note that many other fields are included in a standard CalCentral roster export.
The Gradescope grades is the main source of grading data, exported from the Assignments page of Gradescope. This contains the raw score, the max score, the submission time, and the lateness of each submission for each student. The following columns are required (and are automatically generated by Gradescope):
| Column | Description |
|---|---|
SID |
A student's SID |
ASSIGNMENT |
The student's score on ASSIGNMENT |
ASSIGNMENT - Lateness (H:M:S) |
How late the student submitted ASSIGNMENT, formatted as (HH:MM:SS) |
Each of the last three columns is included for each assignment, so there will be a variable number of columns in the Gradescope export depending on the number of assignments in Gradescope. Grades will not be processed if not present in the assignments CSV.
Note that several other fields are included in a standard Gradescope export.
The categories CSV contains categories that each assignment must be a part of. It defines the behavior of each category and which grading policies will be applied to assignments in each category. The following columns are required:
| Column | Description |
|---|---|
Name |
The name of the category |
Weight |
The weight of the category |
Drops |
The number of drops provided in this category |
Slip Days |
The number of slip days provided in this category |
Has Late Multiplier |
0 if the category does not allow late work and 1 if the category allows a late multiplier |
The values in Weight must sum to 1.0---the script will not verify this.
The assignments CSV defines assignments that will be handled as part of grading. These assignment names must match exactly their names on Gradescope. The following columns are required:
| Column | Description |
|---|---|
Name |
The name of the assignment |
Category |
The name of the assignment's category |
Possible |
The number of points possible on the assignment |
Weight |
The weight of the assignment within the category |
Slip Group |
Used to group assignments together so that they share a lateness and slip day application (e.g. a writeup and autograder for the same project due at the same time). A -1 means that no slip days can be applied, so a standalone assignment must still have its own slip group. |
The Weight field is different in that the columns need not sum to 1.0, since
we allow drops to any arbitrary assignment, which can affect category scores in
different ways. Thus, for all assignments to be weighted equally, you may have a
1.0 in every assignment.
The overrides CSV defines student-specific grade overrides. This exists so that Gradescope exports can be used without a pre-processing step every time it is re-downloaded from Gradescope, instead keeping one-off changes in a sepaate data file. The following columns are required:
| Column | Description |
|---|---|
SID |
The student's SID |
Assignment |
The name of the assignment being overriden |
Score |
The overridden score, as a raw number of points |
The clobber CSV defines categories that should clobber each other, where a category's grade is replaced by a grade from another category, taking the highest of the two. The following columns are required:
| Column | Description |
|---|---|
Scope |
The type of item clobbered, either ASSIGNMENT or CATEGORY |
From |
The name of the assignment or category as the source of the clobber |
To |
The name of the assignment or category being clobbered |
Type |
The method of calculating clobbers, either ZSCORE or SCALED |
Scale |
The percentage to clobber by, in decimal. 1.0 is a full clobber, 0.8 is an 80% clobber, etc. |
Z-score clobbers convert the student's score to a Z-score using the mean and standard deviation and then applies that Z-score to the clobber assignment using its mean and standard deviation. Scaled clobbers take the percentage earned on the assignment and applies that percentage to the clobbered assignment.
Partial clobbers mean that the final score will be a fractional portion of the resulting clobber score. For example, if you scored 80% on the final, which clobbers the midterm at 80% using a scaled clobber, the midterm would be clobbered to 64% if the midterm's score was lower.
The extension CSV defines assignment deadline extensions to students such that the late multiplier will not be applied. The following columns are required:
| Column | Description |
|---|---|
SID |
The student's SID |
Assignment |
The name of the assignment whose deadline is being extended |
Days |
The number of days the deadline is extended by |
The accommodations CSV defines individual accommodations given to students in the form of additional slip days or drops within specific categories. The following columns are required:
| Column | Description |
|---|---|
SID |
The student's SID |
Category |
The category relevant to the accommodation |
Drop Adjust |
The number of additional drops to grant in the category |
Slip Day Adjust |
The number of additional slip days to grant in the category |
Drop Adjust and Slip Day Adjust may technically be negative, which would
have the effect of removing slip days and drops the student would otherwise
receive, but this likely is not a useful feature.
This script is constructed to enumerate all possibilities of applying grading
policies (such as all ways to assign slip days and/or drops) and choosing the
option that most benefits the student. Each Student represents one possibility
of applying policy. Each application of course policies and individual
accommodations will take one such Student and return a list of Students, so
that each policy can branch out to multiple possibilities, such as applying slip
days in different combinations. For simpler policies, such as extensions, the
returned list can be one element, so the possibility list will essentially be
mapped one-to-one to another list mutated in place without adding new
possibilities for the sake of efficiency and reasonable optimization (e.g.
there is no circumstance in which not applying a homework drop would be more
beneficial).
After all policies and accommodations are applied, the grade calculation is run for all policies for each student, and the final grade assigned to them is the highest possible grade they can receive. A grade report is also generated that shows the breakdown for each assignment and category, their contributions to the final grade, and comments showing policies applied for the sake of transparency.
- Slip days within categories, allowing a certain number of late days across all assignments without a late multiplier
- Drops within categories, dropping the assignment that most negatively impacts
the grade
- Does not guarantee optimal grade for student with unequally weighted assignments for the time being
- Extensions on assignments for individual students
- Additional slip days in categories for individual students
- Additional drops in categories for individual students
- Late multipliers
- Currently fixed at
[0.9, 0.8, 0.6], or 10%, 20%, 40% grade reduction
- Currently fixed at
This script is written with extensibility in mind, needing only to branch out more possibilities or mutate existing possibilities for students. However, ideally, this script will not do more than it needs to, since features such as grade bins can be done externally. As a rule of thumb, if you can do it easily in Excel, use Excel on the output of this script.
That being said, logical additions for future features include the following:
- Manual grade overrides on individual assignments, with an optional comment
- This handles individual clobber accommodations and other one-off grade overrides
- Nicholas Ngai ([email protected]): Initial creation in Summer 2020, contributions through Spring 2021