feat: include bonus
Pipeline / check (pull_request) Successful in 12m11s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped

This commit is contained in:
alexm committed 2026-11-02 08:22:07 -05:00
1 parent c8d6f4a5dd
commit 15175f64fd
16 files changed
+773 -83

No files matched your search

+44
View File
@@ -592,6 +592,7 @@ pub fn apply(set: &mut ResponseSet, decoder: &FormDecoder, numbering: Numbering)
// something else entirely. Nothing downstream can tell them apart, so the
// collision has to be caught here.
let recorded: BTreeSet<u32> = decoder.numbers().collect();
let last_recorded = recorded.iter().next_back().copied().unwrap_or(0);
for row in &mut set.rows {
let belongs = row
@@ -604,6 +605,17 @@ pub fn apply(set: &mut ResponseSet, decoder: &FormDecoder, numbering: Numbering)
}
let Some(map) = decoder.lookup(row.item_number, numbering) else {
// A curve was never on the paper, so being off the form is expected.
// It still needs a number of its own: the positions past the end of
// the form can be numbers the record uses once a question was pulled
// before printing, and discarding it would lose points from the total.
if row.is_curve() {
if recorded.contains(&row.item_number) {
row.item_number =
last_recorded + row.item_number.saturating_sub(decoder.len() as u32);
}
continue;
}
unmapped_positions.insert(row.item_number);
if recorded.contains(&row.item_number) {
colliding_positions.insert(row.item_number);
@@ -802,6 +814,38 @@ mod tests {
assert_eq!(set.rows[0].item_number, 7, "left as found");
}
fn curve(number: u32) -> Response {
let mut r = row(number, "A");
r.selected = Vec::new();
r.correct = None;
r.bonus = true;
r.score = 3.6;
r
}
#[test]
fn a_curve_off_the_end_of_the_form_is_kept_quietly() {
let mut set = ResponseSet::new();
set.rows.push(row(1, "A"));
set.rows.push(curve(3));
let warnings = apply(&mut set, &decoder(), Numbering::Printed);
assert!(warnings.is_empty(), "{warnings:?}");
assert_eq!(set.rows[1].item_number, 3);
}
#[test]
fn a_curve_on_a_recorded_number_moves_past_the_record() {
// Two printed questions recorded as 1 and 9, and a curve as the ninth file
// of the export: position 9 is off the form, but number 9 is a real question.
let mut set = ResponseSet::new();
set.rows.push(row(1, "A"));
set.rows.push(curve(9));
let warnings = apply(&mut set, &decoder(), Numbering::Printed);
assert!(warnings.is_empty(), "{warnings:?}");
assert_eq!(set.rows.len(), 2, "the points are not discarded");
assert_eq!(set.rows[1].item_number, 16);
}
#[test]
fn a_perfect_fit_says_nothing() {
let fits = vec![FormFit {
+264 -35
View File
@@ -5,9 +5,10 @@
//! Reading Gradescope's per-question CSV exports.
//!
//! Gradescope exports one file per question, named `1.csv` through `N.csv`, in
//! wide form. Every assumption encoded here was checked against a real 32-question,
//! 24-student export rather than inferred from documentation, because several of
//! them are not what the format suggests.
//! wide form, with the title appended when the question has one: `39_Curve.csv`.
//! Every assumption encoded here was checked against a real 32-question, 24-student
//! export rather than inferred from documentation, because several of them are not
//! what the format suggests.
//!
//! The layout is:
//!
@@ -43,6 +44,12 @@
//! *Bonus questions have `max_points` of zero* while a rubric column still
//! carries points. Key detection therefore uses the largest value across the
//! maximum *and* every column, not the maximum alone.
//!
//! *A curve is a question too.* It is usually the last file, worth zero points,
//! with no option columns: a rubric row such as `Curve` worth 3.6, or nothing but
//! a point adjustment on each submission. It was never printed, so it is recorded
//! as a bonus row with nothing marked, which is what [`Response::is_curve`] looks
//! for.
use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};
@@ -185,9 +192,26 @@ impl Question {
///
/// # Returns
///
/// `true` when the maximum is zero but a column still awards points.
/// `true` when the maximum is zero but a column still awards points, or when
/// a question with no option columns awarded points by adjustment alone.
pub fn looks_like_bonus(&self) -> bool {
self.max_points <= 0.0 && self.top_value() > 0.0
self.max_points <= 0.0
&& (self.top_value() > 0.0
|| (!self.has_options() && self.rows.iter().any(|r| r.score != 0.0)))
}
/// Whether this looks like a curve rather than a question on the paper.
///
/// # Returns
///
/// `true` for a bonus question whose rubric names no option.
pub fn looks_like_curve(&self) -> bool {
self.looks_like_bonus() && !self.has_options()
}
/// Whether any rubric column names an option letter.
fn has_options(&self) -> bool {
self.columns.iter().any(|c| c.letter.is_some())
}
/// Whether elimination scoring was in use.
@@ -307,6 +331,27 @@ pub fn classify(label: &str) -> (ColumnKind, Option<String>, Option<String>) {
(kind, Some(upper.to_string()), note)
}
/// Reads the question number from a file name.
///
/// # Arguments
///
/// * `path` - the file, named like `12.csv` or `12_Title.csv`.
///
/// # Returns
///
/// The number, or `None` when the file is not named like a question export.
pub fn question_number(path: &Path) -> Option<u32> {
if path.extension().and_then(|e| e.to_str()) != Some("csv") {
return None;
}
let stem = path.file_stem()?.to_str()?;
let digits = stem.split_once('_').map_or(stem, |(number, _)| number);
if !digits.chars().all(|c| c.is_ascii_digit()) {
return None;
}
digits.parse().ok()
}
/// Parses one question file.
///
/// # Arguments
@@ -322,16 +367,13 @@ pub fn classify(label: &str) -> (ColumnKind, Option<String>, Option<String>) {
/// Returns [`Error::Csv`] on a malformed file and [`Error::Invalid`] when the
/// header lacks the `Submission Time` column that delimits the rubric.
pub fn parse_question(path: &Path) -> Result<Question> {
let number = path
.file_stem()
.and_then(|s| s.to_str())
.and_then(|s| s.parse::<u32>().ok())
.ok_or_else(|| {
Error::Invalid(vec![format!(
"{} is not named like a Gradescope question export (expected `12.csv`)",
path.display()
)])
})?;
let number = question_number(path).ok_or_else(|| {
Error::Invalid(vec![format!(
"{} is not named like a Gradescope question export (expected `12.csv` or \
`12_Title.csv`)",
path.display()
)])
})?;
// Flexible mode is required: the trailing `Point Values` rows are shorter
// than the header.
@@ -503,53 +545,68 @@ pub fn parse_question(path: &Path) -> Result<Question> {
///
/// # Arguments
///
/// * `dir` - the directory of `N.csv` files.
/// * `dir` - the directory of `N.csv` and `N_Title.csv` files.
/// * `ctx` - identifying information the export does not carry.
///
/// # Returns
///
/// Normalized responses and the parsed questions.
/// Normalized responses and the parsed questions, with a warning for any CSV file
/// that was not read.
///
/// # Errors
///
/// Returns [`Error::Io`] when the directory cannot be read and [`Error::Invalid`]
/// when it holds no question files.
/// when it holds no question files or two files for one question.
pub fn ingest_dir(dir: &Path, ctx: &Context) -> Result<Import> {
let mut paths: Vec<PathBuf> = std::fs::read_dir(dir)
.map_err(|e| Error::io(dir, e))?
.filter_map(|e| e.ok())
.map(|e| e.path())
.filter(|p| {
p.extension().and_then(|e| e.to_str()) == Some("csv")
&& p.file_stem()
.and_then(|s| s.to_str())
.map(|s| s.chars().all(|c| c.is_ascii_digit()))
.unwrap_or(false)
})
.filter(|p| p.extension().and_then(|e| e.to_str()) == Some("csv"))
.collect();
// Numeric order, so `10.csv` does not sort before `2.csv`. Unnumbered files
// come out of the list here and are reported below, since a file left out
// quietly is points missing from every student's total.
paths.sort();
let (numbered, unread): (Vec<PathBuf>, Vec<PathBuf>) = paths
.into_iter()
.partition(|p| question_number(p).is_some());
let mut paths = numbered;
paths.sort_by_key(|p| question_number(p));
if paths.is_empty() {
return Err(Error::Invalid(vec![format!(
"{} holds no numbered CSV files; Gradescope exports one file per question, \
named `1.csv` through `N.csv`",
named `1.csv` through `N.csv` or `N_Title.csv`",
dir.display()
)]));
}
// Numeric order, so `10.csv` does not sort before `2.csv`.
paths.sort_by_key(|p| {
p.file_stem()
.and_then(|s| s.to_str())
.and_then(|s| s.parse::<u32>().ok())
.unwrap_or(u32::MAX)
});
for pair in paths.windows(2) {
if question_number(&pair[0]) == question_number(&pair[1]) {
return Err(Error::Invalid(vec![format!(
"{} and {} are both exports of the same question; remove the one that is out of \
date",
pair[0].display(),
pair[1].display()
)]));
}
}
let mut questions = Vec::new();
for p in &paths {
questions.push(parse_question(p)?);
}
Ok(to_responses(&questions, ctx))
let mut import = to_responses(&questions, ctx);
for path in &unread {
import.responses.warnings.push(format!(
"{} was not read: its name does not start with a question number",
path.display()
));
}
Ok(import)
}
/// Normalizes parsed questions into responses.
@@ -572,7 +629,14 @@ pub fn to_responses(questions: &[Question], ctx: &Context) -> Import {
let points = q.points_possible();
let bonus = q.looks_like_bonus();
if keyed.is_empty() {
if q.looks_like_curve() {
set.warnings.push(format!(
"question {} is worth zero points and has no option rubric, so it is recorded as \
a curve: its points go on each student's total and it is not treated as a \
question",
q.number
));
} else if keyed.is_empty() {
set.warnings.push(format!(
"question {}: no keyed option could be identified from the point values, so \
correctness is unknown; scores are still recorded",
@@ -779,6 +843,63 @@ mod tests {
assert_eq!(question.points_possible(), 1.5);
}
fn awarded(score: f64) -> StudentRow {
StudentRow {
sid: Some("1234567".to_string()),
name: None,
email: None,
section: None,
score,
submission_time: None,
marks: Vec::new(),
}
}
#[test]
fn a_zero_point_question_with_no_options_is_a_curve() {
let mut rubric = q(0.0, &[("Curve", 3.6)]);
rubric.rows = vec![awarded(3.6)];
assert!(rubric.looks_like_curve());
assert_eq!(rubric.points_possible(), 3.6);
// No rubric value at all: the points were a per-submission adjustment.
let mut adjusted = q(0.0, &[("Applied", 0.0)]);
adjusted.rows = vec![awarded(3.6)];
assert!(adjusted.looks_like_curve());
let ctx = Context {
course: "BIOSC1000".into(),
term: "2026f".into(),
assessment_id: "e3".into(),
date: None,
form: None,
};
let import = to_responses(&[adjusted], &ctx);
assert!(import.responses.rows[0].is_curve());
assert_eq!(import.responses.curve_total("1234567"), 3.6);
assert!(
import.responses.warnings[0].contains("curve"),
"{:?}",
import.responses.warnings
);
}
#[test]
fn a_bonus_question_with_options_is_not_a_curve() {
let question = q(0.0, &[("A", 0.0), ("B", 1.0)]);
assert!(question.looks_like_bonus());
assert!(!question.looks_like_curve());
}
#[test]
fn an_export_without_point_values_is_not_a_bonus() {
// The maximum defaults to zero when the row is absent; awarded points on
// lettered columns must not turn every question into a bonus.
let mut question = q(0.0, &[("A", 0.0), ("B", 0.0)]);
question.rows = vec![awarded(1.0)];
assert!(!question.looks_like_bonus());
}
#[test]
fn partial_credit_to_a_distractor_flags_ambiguity() {
// Real case: q14, where B earned 1.49 of 1.5.
@@ -854,6 +975,114 @@ mod tests {
std::fs::remove_dir_all(&dir).ok();
}
#[test]
fn reads_the_question_number_from_a_titled_file_name() {
assert_eq!(question_number(Path::new("7.csv")), Some(7));
assert_eq!(question_number(Path::new("39_Curve.csv")), Some(39));
assert_eq!(question_number(Path::new("39_Curve_v2.csv")), Some(39));
assert_eq!(question_number(Path::new("_Curve.csv")), None);
assert_eq!(question_number(Path::new("Curve.csv")), None);
assert_eq!(question_number(Path::new("39_Curve.txt")), None);
assert_eq!(question_number(Path::new("+39.csv")), None);
}
fn context() -> Context {
Context {
course: "BIOSC1000".into(),
term: "2026f".into(),
assessment_id: "e3".into(),
date: None,
form: Some("A".into()),
}
}
const CURVE_HEADER: &str = "Assignment Submission ID,Question Submission ID,First Name,\
Last Name,SID,Email,Sections,Score,Submission Time,Curve,Adjustment,Comments,Grader,Tags\n";
#[test]
fn a_titled_curve_file_reaches_the_totals() {
let dir = std::env::temp_dir().join(format!("cb-gs-curve-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join("1.csv"),
"Assignment Submission ID,Question Submission ID,First Name,Last Name,SID,Email,\
Sections,Score,Submission Time,A,B,Adjustment,Comments,Grader,Tags\n\
1,11,Ada,Lovelace,1234567,ada@x.edu,L01,10.0,2026-10-28 10:51:39 -0700,true,false,,,,\"\"\n\
2,12,Alan,Turing,7654321,alan@x.edu,L01,0.0,2026-10-28 10:51:39 -0700,false,true,,,,\"\"\n\
Point Values,,,,,10.0,10.0,0.0\n\
Rubric Numbers,,,,,,1.1,1.2\n\
Scoring Method,positive\n",
)
.unwrap();
// The second student's curve was taken away by an adjustment, which leaves
// a score of zero with the rubric row still marked.
std::fs::write(
dir.join("39_Curve.csv"),
format!(
"{CURVE_HEADER}\
1,21,Ada,Lovelace,1234567,ada@x.edu,L01,4.7,2026-10-28 10:51:39 -0700,true,,,,\"\"\n\
2,22,Alan,Turing,7654321,alan@x.edu,L01,0.0,2026-10-28 10:51:39 -0700,true,-5.0,removed,,\"\"\n\
Point Values,,,,,0.0,4.7\n\
Rubric Numbers,,,,,,39.1\n\
Scoring Method,positive\n"
),
)
.unwrap();
let import = ingest_dir(&dir, &context()).unwrap();
std::fs::remove_dir_all(&dir).ok();
let numbers: Vec<u32> = import.questions.iter().map(|q| q.number).collect();
assert_eq!(numbers, vec![1, 39]);
assert!(import.questions[1].looks_like_curve());
let set = import.responses;
assert_eq!(set.curve_total("1234567"), 4.7);
assert_eq!(set.curve_total("7654321"), 0.0);
assert_eq!(set.points_of_record("1234567"), 14.7);
assert_eq!(set.points_of_record("7654321"), 0.0);
}
#[test]
fn warns_about_a_csv_file_it_did_not_read() {
let dir = std::env::temp_dir().join(format!("cb-gs-unread-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join("1.csv"),
format!("{CURVE_HEADER}Point Values,,,,,0.0,4.7\n"),
)
.unwrap();
std::fs::write(dir.join("Curve.csv"), "not a question\n").unwrap();
let import = ingest_dir(&dir, &context()).unwrap();
std::fs::remove_dir_all(&dir).ok();
assert_eq!(import.questions.len(), 1);
assert!(
import
.responses
.warnings
.iter()
.any(|w| w.contains("Curve.csv") && w.contains("not read")),
"{:?}",
import.responses.warnings
);
}
#[test]
fn refuses_two_files_for_one_question() {
let dir = std::env::temp_dir().join(format!("cb-gs-twice-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let curve = format!("{CURVE_HEADER}Point Values,,,,,0.0,4.7\n");
std::fs::write(dir.join("39.csv"), &curve).unwrap();
std::fs::write(dir.join("39_Curve.csv"), &curve).unwrap();
let err = ingest_dir(&dir, &context()).unwrap_err();
std::fs::remove_dir_all(&dir).ok();
assert!(err.to_string().contains("same question"), "{err}");
}
#[test]
fn rejects_a_file_without_the_rubric_delimiter() {
let dir = std::env::temp_dir().join(format!("cb-gs-bad-{}", std::process::id()));
+4 -10
View File
@@ -511,20 +511,14 @@ pub fn describe(intake: &FormIntake) -> String {
///
/// # Returns
///
/// `true` when it holds at least one file named like `1.csv`.
/// `true` when it holds at least one file named like `1.csv` or `1_Title.csv`.
pub fn looks_like_export(dir: &Path) -> bool {
let Ok(entries) = std::fs::read_dir(dir) else {
return false;
};
entries.filter_map(|e| e.ok()).any(|entry| {
let path = entry.path();
path.extension().and_then(|e| e.to_str()) == Some("csv")
&& path
.file_stem()
.and_then(|s| s.to_str())
.map(|s| s.chars().all(|c| c.is_ascii_digit()))
.unwrap_or(false)
})
entries
.filter_map(|e| e.ok())
.any(|entry| gradescope::question_number(&entry.path()).is_some())
}
#[cfg(test)]
+137 -5
View File
@@ -161,6 +161,23 @@ impl Response {
!self.bonus && (!self.dropped || self.dropped_full_credit)
}
/// Whether this row is a curve rather than an answer to a question.
///
/// A curve is a zero-point entry on the grading platform that was never
/// printed: bonus, in no placement of the record, and with no option marked.
/// Its points belong on the student's total, but it has nothing to report as
/// a question.
///
/// # Returns
///
/// `true` for a curve row.
pub fn is_curve(&self) -> bool {
self.bonus
&& self.item_ref.is_none()
&& self.selected.is_empty()
&& self.eliminated.is_empty()
}
/// The response coded for a dichotomous model.
///
/// Partial credit is rounded toward the majority: a half-credit response is
@@ -302,15 +319,43 @@ impl ResponseSet {
.sum()
}
/// Bonus points a student earned.
/// Bonus points a student earned on bonus questions.
pub fn bonus_total(&self, key: &str) -> f64 {
self.rows
.iter()
.filter(|r| r.student_key == key && r.bonus && !r.dropped)
.filter(|r| r.student_key == key && r.bonus && !r.dropped && !r.is_curve())
.map(|r| r.score)
.sum()
}
/// Points a curve added to a student's total.
pub fn curve_total(&self, key: &str) -> f64 {
self.rows
.iter()
.filter(|r| r.student_key == key && r.is_curve() && !r.dropped)
.map(|r| r.score)
.sum()
}
/// The total on the grading platform: every point a student earned, bonus
/// and curve included.
///
/// Bonus and curve points sit in the numerator with nothing added to the
/// denominator, which is how a question worth zero points adds up on
/// Gradescope. Divide by [`ResponseSet::points_available`] for the percentage
/// the student can see there.
///
/// # Arguments
///
/// * `key` - the student key.
///
/// # Returns
///
/// The student's total points.
pub fn points_of_record(&self, key: &str) -> f64 {
self.scored_total(key) + self.bonus_total(key) + self.curve_total(key)
}
/// Points available on scored items, taken from the most generous row seen
/// for each item so a student who skipped an item still has a denominator.
pub fn points_available(&self) -> f64 {
@@ -383,7 +428,7 @@ impl ResponseSet {
let items: Vec<u32> = if include_bonus {
self.all_items()
.into_iter()
.filter(|n| !self.item_dropped(*n))
.filter(|n| !self.item_dropped(*n) && !self.item_is_curve(*n))
.collect()
} else {
self.scored_items()
@@ -439,6 +484,14 @@ impl ResponseSet {
any
}
/// Whether every row for a number is a curve, so it is no item at all.
fn item_is_curve(&self, number: u32) -> bool {
self.rows
.iter()
.filter(|r| r.item_number == number)
.all(Response::is_curve)
}
/// Attaches item metadata from an assessment record and the catalog.
///
/// Ingest knows question numbers; only the record knows which item a number
@@ -464,7 +517,10 @@ impl ResponseSet {
for r in &mut self.rows {
let Some(p) = record.placement(r.item_number) else {
unmatched.insert(r.item_number);
// A curve is never in the record, so its absence says nothing.
if !r.is_curve() {
unmatched.insert(r.item_number);
}
continue;
};
r.item_ref = Some(p.item.clone());
@@ -475,7 +531,9 @@ impl ResponseSet {
r.bonus = r.bonus || p.bonus;
r.dropped = r.dropped || p.dropped;
r.dropped_full_credit = r.dropped_full_credit || p.dropped_with_credit();
if let Some(points) = p.points {
// A record that says zero is describing a bonus question the way the
// platform does, and must not erase the points the platform awarded.
if let Some(points) = p.points.filter(|points| *points > 0.0) {
// The record is authoritative for points as administered; the
// export sometimes carries a stale maximum.
if (points - r.points_possible).abs() > 1e-9 && r.points_possible > 0.0 {
@@ -541,6 +599,29 @@ impl ResponseSet {
list.join(", ")
));
}
// A removed drop leaves the report's denominator. If the platform gave
// everyone the points, the question is still in the grade the student
// can see, and the two percentages will disagree.
for p in record
.items
.iter()
.filter(|p| p.dropped && !p.dropped_with_credit())
{
let mut rows = self
.rows
.iter()
.filter(|r| r.item_number == p.number)
.peekable();
if rows.peek().is_some() && rows.all(|r| r.score > 0.0) {
warnings.push(format!(
"question {} is dropped as removed, but the export gives every student points \
for it, so reports will disagree with the platform's percentage; set \
`dropped_as: full_credit` on the placement if it stays in the platform's total",
p.number
));
}
}
self.warnings.extend(warnings.clone());
warnings
}
@@ -977,6 +1058,57 @@ mod tests {
assert_eq!(set.bonus_total("s1"), 2.0);
}
/// A curve row as the Gradescope import writes one.
fn curve(student: &str, number: u32, score: f64) -> Response {
let mut r = row(student, number, 0.0);
r.selected = vec![];
r.correct = None;
r.bonus = true;
r.points_possible = score;
r.score = score;
r
}
#[test]
fn the_total_of_record_adds_bonus_and_curve_without_raising_the_maximum() {
let mut set = ResponseSet::new();
// 1 of 2 and 2 of 2 on the scored questions.
set.rows.push(row("s1", 1, 0.5));
set.rows.push(row("s1", 2, 1.0));
// A bonus question worth 2, answered right.
let mut bonus = row("s1", 3, 1.0);
bonus.bonus = true;
set.rows.push(bonus);
set.rows.push(curve("s1", 4, 3.6));
assert_eq!(set.scored_total("s1"), 3.0);
assert_eq!(set.bonus_total("s1"), 2.0);
assert_eq!(set.curve_total("s1"), 3.6);
assert!((set.points_of_record("s1") - 8.6).abs() < 1e-9);
assert_eq!(set.points_available(), 4.0, "only scored questions");
}
#[test]
fn a_curve_is_not_an_item() {
let mut set = ResponseSet::new();
set.rows.push(row("s1", 1, 1.0));
set.rows.push(curve("s1", 2, 3.6));
assert_eq!(set.matrix(false).items, vec![1]);
assert_eq!(set.matrix(true).items, vec![1]);
}
#[test]
fn an_answered_bonus_question_is_not_a_curve() {
let mut bonus = row("s1", 1, 1.0);
bonus.bonus = true;
assert!(!bonus.is_curve());
// Nor is a blank answer to a bonus question the record knows about.
bonus.selected = vec![];
bonus.item_ref = Some("q-x".into());
assert!(!bonus.is_curve());
}
#[test]
fn dropped_items_leave_the_matrix() {
let mut set = ResponseSet::new();