diff --git a/CHANGELOG.md b/CHANGELOG.md index 809e495..de9e8b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,3 +9,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Added - First public release. +- Student reports add bonus questions and curves to the score and show how the total adds up, so it matches Gradescope and Canvas. Class means, bands, and grade distributions use the same total. +- A zero-point Gradescope question with no option columns is recorded as a curve. +- `ingest` warns when a question dropped as removed still gives every student points on the platform. + +### Fixed + +- A record with `points: 0` on a bonus question no longer erases the points the platform awarded. +- A curve whose position matches a recorded question number is no longer discarded at ingest. +- Gradescope files named with the question's title, such as `39_Curve.csv`, are now read. They used to be skipped without a word, which left titled questions and curves out of the totals. Any other CSV file in the directory now draws a warning, and two files for one question are refused. Re-ingest to pick this up. +- The assessment JSON Schema now accepts `dropped_as`, `dropped_before_printing`, `stem_digest`, and `learning_objectives` on a placement, all of which the loader already read. Rerun `coursebank schema` to pick this up. diff --git a/README.md b/README.md index 6655207..a63e5dd 100644 --- a/README.md +++ b/README.md @@ -562,7 +562,7 @@ Two grading exports are supported, and the assessment id is required for both. | Command | Reads | |---------|-------| -| `ingest gradescope SOURCE...` | one directory of per-question CSVs per form, files named `1.csv` to `N.csv` | +| `ingest gradescope SOURCE...` | one directory of per-question CSVs per form, files named `1.csv` to `N.csv`, or `N_Title.csv` for a titled question | | `ingest canvas FILE` | the Canvas "Student Analysis" quiz CSV (not the gradebook, not the Item Analysis) | Both readers produce the same long-format row, one per student per item. diff --git a/docs/guide/recipes.md b/docs/guide/recipes.md index 6238715..32b4d76 100644 --- a/docs/guide/recipes.md +++ b/docs/guide/recipes.md @@ -56,7 +56,15 @@ See [`typst_export`](crate::guide::typst_export). **Gradescope.** `coursebank ingest gradescope grading/exam-2/ --assessment exam-2`. -Point it at the directory holding the per-question CSVs. +Point it at the directory holding the per-question CSVs, named as Gradescope names them: `7.csv`, or `39_Curve.csv` for a question with a title. +Give every form its own directory, including its own copy of a curve. + +**Bonus questions and curves.** +Leave them in the Gradescope export, worth zero points. +A zero-point question with option columns is a bonus question; give it `bonus: true` in the record. +A zero-point question with no option columns, such as a final `Curve` question worth 3.6/0, stays out of the record and is treated as a curve. +Reports add both to the total without raising the maximum, so their percentage matches Gradescope's and can pass 100%. +If you drop a question by giving everyone the points, set `dropped_as: full_credit` on its placement, or reports will take it out of the total that Gradescope still counts. **Canvas.** `coursebank ingest canvas export.csv --assessment exam-2`. diff --git a/src/analysis/diagnostic.rs b/src/analysis/diagnostic.rs index 1142c58..1453999 100644 --- a/src/analysis/diagnostic.rs +++ b/src/analysis/diagnostic.rs @@ -206,16 +206,33 @@ pub struct Score { pub points: f64, /// Points available on scored items. pub points_possible: f64, - /// Percentage on scored items. + /// Every point earned, bonus and curve included: the total on the platform. + pub total_points: f64, + /// `total_points` as a percentage of `points_possible`, the same percentage + /// the platform shows. It can pass 100. pub percent: f64, /// Bonus points earned. pub bonus_points: f64, + /// Points a curve added. + pub curve_points: f64, + /// The bonus questions on the exam, so the total can be added up by hand. + pub bonus_questions: Vec, /// Items answered correctly. pub correct: usize, /// Scored items administered. pub n_items: usize, } +/// One bonus question's contribution to a student's total. +#[derive(Debug, Clone, Serialize)] +#[serde(rename_all = "kebab-case")] +pub struct BonusQuestion { + /// The recorded question number. + pub number: u32, + /// Points the student earned on it. + pub points: f64, +} + /// Where a score sits in the class. #[derive(Debug, Clone, Serialize)] #[serde(rename_all = "kebab-case")] @@ -585,14 +602,26 @@ pub fn student( .map(|a| a.items.iter().map(|i| (i.number, i.p_value)).collect()) .unwrap_or_default(); + // A curve is on the total but was never a question on the paper, so a box for + // it would send the student looking for something that was not there. let questions = if opts.questions { rows.iter() + .filter(|row| !row.is_curve()) .map(|row| question_row(row, catalog, &class_rates, opts)) .collect() } else { Vec::new() }; + let bonus_questions = rows + .iter() + .filter(|r| r.bonus && !r.dropped && !r.is_curve()) + .map(|r| BonusQuestion { + number: r.item_number, + points: r.score, + }) + .collect(); + let mut dropped_questions: Vec = rows .iter() .filter(|r| r.dropped) @@ -630,8 +659,11 @@ pub fn student( score: Score { points: summary.points, points_possible: summary.points_possible, + total_points: summary.total_points, percent: summary.percent, bonus_points: summary.bonus_points, + curve_points: summary.curve_points, + bonus_questions, correct: summary.correct, n_items: summary.n_items, }, @@ -972,6 +1004,10 @@ fn readings_for(course: &CourseFile, objective: &str, limit: usize) -> Vec Vec { .collect() } +/// The class mean of one per-student number. +fn mean_of(cohort: &Cohort, value: impl Fn(&StudentSummary) -> f64) -> f64 { + if cohort.students.is_empty() { + 0.0 + } else { + cohort.students.iter().map(value).sum::() / cohort.students.len() as f64 + } +} + /// Bins a set of percentages into a distribution. fn distribution(percents: &[f64]) -> Distribution { let mut sorted: Vec = percents.to_vec(); @@ -2504,8 +2551,11 @@ mod tests { score: Score { points: 1.0, points_possible: 2.0, + total_points: 1.0, percent: 50.0, bonus_points: 0.0, + curve_points: 0.0, + bonus_questions: Vec::new(), correct: 1, n_items: 2, }, diff --git a/src/analysis/students.rs b/src/analysis/students.rs index f56a78d..9f96cb5 100644 --- a/src/analysis/students.rs +++ b/src/analysis/students.rs @@ -203,10 +203,15 @@ pub struct StudentSummary { pub points: f64, /// Points available on scored items. pub points_possible: f64, - /// Percentage on scored items. + /// Every point earned, bonus and curve included: the total on the platform. + pub total_points: f64, + /// `total_points` as a percentage of `points_possible`, the same percentage + /// the platform shows. It can pass 100. pub percent: f64, /// Bonus points earned. pub bonus_points: f64, + /// Points a curve added. + pub curve_points: f64, /// Items answered correctly. pub correct: usize, /// Items administered. @@ -355,7 +360,7 @@ pub fn summarize( let percents: Vec = students .iter() .map(|key| { - let earned = set.scored_total(key); + let earned = set.points_of_record(key); let possible = set.points_available(); if possible > 0.0 { 100.0 * earned / possible @@ -513,8 +518,10 @@ pub fn summarize( sid: rows.first().and_then(|r| r.sid.clone()), points, points_possible: possible, + total_points: set.points_of_record(key), percent, bonus_points: set.bonus_total(key), + curve_points: set.curve_total(key), correct, n_items, band: band_for(percent, &percents), @@ -1389,8 +1396,10 @@ learning_objectives: sid: None, points: 0.0, points_possible: 0.0, + total_points: 0.0, percent: 0.0, bonus_points: 0.0, + curve_points: 0.0, correct: 0, n_items: 0, band: String::new(), diff --git a/src/authoring/jsonschema.rs b/src/authoring/jsonschema.rs index d0bed57..56711d8 100644 --- a/src/authoring/jsonschema.rs +++ b/src/authoring/jsonschema.rs @@ -1472,6 +1472,11 @@ fn placement_schema() -> Value { }, "item": text("Item reference, `bank::item-id` or a bare item id."), "version": { "type": "integer", "minimum": 1 }, + "stem_digest": { + "type": "string", + "description": "The stem as given. Validation treats a change as an error, since \ + it is no longer the same question." + }, "fingerprint": { "type": "string", "description": "What the item looked like when given. Validation warns if the item \ @@ -1496,6 +1501,7 @@ fn placement_schema() -> Value { }, "level": level(), "learning_targets": string_array("Targets as administered."), + "learning_objectives": string_array("The older name for learning_targets."), "credit_overrides": { "type": "object", "description": "Partial credit decided after the fact, by option letter. Recording \ @@ -1505,7 +1511,23 @@ fn placement_schema() -> Value { }, "dropped": { "type": "boolean", - "description": "Excluded from scoring and from statistics." + "description": "Thrown out after the exam. Always excluded from statistics; \ + dropped_as says whether it stays in the score." + }, + "dropped_as": { + "type": "string", + "enum": ["removed", "full_credit"], + "description": "How a dropped question was handled on the grading platform. \ + removed, the default, takes it out of the numerator and the \ + denominator. full_credit keeps it in both: use it when everyone \ + was given the points, so reports agree with the platform's grade." + }, + "dropped_before_printing": { + "type": "boolean", + "description": "Pulled before the paper was printed, so it never held a position \ + and later questions moved up. Leave unset for a question thrown \ + out after the exam: setting it wrongly attributes responses to \ + the wrong items." } } }) @@ -1601,6 +1623,49 @@ mod tests { ); } + #[test] + fn the_placement_schema_lists_every_field_a_record_can_carry() { + use crate::assessment::{DropStyle, Placement}; + + // Written out in full so that a new field does not compile until it is + // added here, which is the prompt to add it to the schema as well. + let placement = Placement { + number: 1, + item: "q-x".to_string(), + version: Some(1), + stem_digest: Some("s".to_string()), + fingerprint: Some("f".to_string()), + points: Some(1.0), + bonus: true, + key: vec!["A".to_string()], + distractors: vec!["B".to_string()], + variant: Some("v".to_string()), + level: Some(Level::ALL[0]), + learning_targets: vec!["t-x".to_string()], + credit_overrides: [("B".to_string(), 0.5)].into_iter().collect(), + dropped: true, + dropped_as: Some(DropStyle::FullCredit), + dropped_before_printing: true, + }; + + let schema = placement_schema(); + let value = serde_json::to_value(&placement).unwrap(); + for key in value.as_object().unwrap().keys() { + assert!( + schema["properties"].get(key).is_some(), + "`{key}` loads from a record but the schema would flag it as unknown" + ); + } + + for style in [DropStyle::Removed, DropStyle::FullCredit] { + let token = serde_json::to_value(style).unwrap(); + let allowed = schema["properties"]["dropped_as"]["enum"] + .as_array() + .unwrap(); + assert!(allowed.contains(&token), "{token} is not in the enum"); + } + } + #[test] fn modelines_point_at_the_right_file() { assert_eq!( diff --git a/src/commands/analysis.rs b/src/commands/analysis.rs index 61366ba..dd5cd59 100644 --- a/src/commands/analysis.rs +++ b/src/commands/analysis.rs @@ -195,8 +195,9 @@ pub(crate) fn ingest(cli: &Cli, sub: &IngestCommand) -> Result { for source in &parsed { if !intake::looks_like_export(&source.dir) { return Err(Error::usage(format!( - "{} holds no files named `1.csv` … `N.csv`. Gradescope writes one file \ - per question; point at the directory those were unzipped into", + "{} holds no files named `1.csv` … `N.csv` or `N_Title.csv`. Gradescope \ + writes one file per question; point at the directory those were \ + unzipped into", source.dir.display() ))); } diff --git a/src/commands/handlers.rs b/src/commands/handlers.rs index 800b242..af2be5b 100644 --- a/src/commands/handlers.rs +++ b/src/commands/handlers.rs @@ -207,8 +207,9 @@ pub(crate) fn ingest(cli: &Cli, sub: &IngestCommand) -> Result { for source in &parsed { if !intake::looks_like_export(&source.dir) { return Err(Error::usage(format!( - "{} holds no files named `1.csv` … `N.csv`. Gradescope writes one file \ - per question; point at the directory those were unzipped into", + "{} holds no files named `1.csv` … `N.csv` or `N_Title.csv`. Gradescope \ + writes one file per question; point at the directory those were \ + unzipped into", source.dir.display() ))); } diff --git a/src/data/decode.rs b/src/data/decode.rs index c55e49f..ffe822f 100644 --- a/src/data/decode.rs +++ b/src/data/decode.rs @@ -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 = 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 { diff --git a/src/data/gradescope.rs b/src/data/gradescope.rs index 9de2838..e2bf14d 100644 --- a/src/data/gradescope.rs +++ b/src/data/gradescope.rs @@ -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, Option) { (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 { + 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, Option) { /// 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 { - let number = path - .file_stem() - .and_then(|s| s.to_str()) - .and_then(|s| s.parse::().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 { /// /// # 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 { let mut paths: Vec = 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, Vec) = 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::().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 = 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())); diff --git a/src/data/intake.rs b/src/data/intake.rs index 331bd43..301f808 100644 --- a/src/data/intake.rs +++ b/src/data/intake.rs @@ -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)] diff --git a/src/data/responses.rs b/src/data/responses.rs index 369ba79..32185bc 100644 --- a/src/data/responses.rs +++ b/src/data/responses.rs @@ -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 = 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(); diff --git a/src/export/report.rs b/src/export/report.rs index ef2b723..674a1c9 100644 --- a/src/export/report.rs +++ b/src/export/report.rs @@ -100,13 +100,16 @@ pub fn student( // --- score out.push_str(&format!( - "You scored **{:.1} of {:.1} points ({:.0}%)**", - summary.points, summary.points_possible, summary.percent + "You scored **{} of {} points ({:.1}%)**", + points(summary.total_points), + points(summary.points_possible), + summary.percent )); + let mut extras = Vec::new(); if summary.bonus_points > 0.0 { - out.push_str(&format!( - ", plus {:.1} bonus point{}", - summary.bonus_points, + extras.push(format!( + "{} bonus point{}", + points(summary.bonus_points), if (summary.bonus_points - 1.0).abs() < 1e-9 { "" } else { @@ -114,6 +117,20 @@ pub fn student( } )); } + if summary.curve_points != 0.0 { + extras.push(format!( + "{} curve point{}", + points(summary.curve_points), + if (summary.curve_points - 1.0).abs() < 1e-9 { + "" + } else { + "s" + } + )); + } + if !extras.is_empty() { + out.push_str(&format!(" including {}", extras.join(" and "))); + } out.push_str(&format!( ", answering {} of {} questions correctly.\n\n", summary.correct, summary.n_items @@ -121,7 +138,7 @@ pub fn student( if opts.comparison { out.push_str(&format!( - "The class averaged {:.0}%. Your score is in the {}.\n\n", + "The class averaged {:.1}%. Your score is in the {}.\n\n", cohort.mean_percent, summary.band )); } @@ -684,6 +701,20 @@ pub fn roster(cohort: &Cohort) -> String { out } +/// Formats points the way a gradebook shows them, with no trailing zeros. +/// +/// # Arguments +/// +/// * `value` - the points. +/// +/// # Returns +/// +/// The points to at most two decimal places. +fn points(value: f64) -> String { + let text = format!("{value:.2}"); + text.trim_end_matches('0').trim_end_matches('.').to_string() +} + /// A small unicode bar for a rate in `0.0..=1.0`. /// /// # Arguments diff --git a/src/export/typst/diagnostic.rs b/src/export/typst/diagnostic.rs index 5d7bc88..412bdf7 100644 --- a/src/export/typst/diagnostic.rs +++ b/src/export/typst/diagnostic.rs @@ -196,8 +196,26 @@ pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> V let mut score = Value::dict(); score.insert("points", Value::Float(diagnostic.score.points)); score.insert("possible", Value::Float(diagnostic.score.points_possible)); + score.insert("total", Value::Float(diagnostic.score.total_points)); score.insert("percent", Value::Float(diagnostic.score.percent)); score.insert("bonus", Value::Float(diagnostic.score.bonus_points)); + score.insert("curve", Value::Float(diagnostic.score.curve_points)); + score.insert( + "bonus-questions", + Value::Array( + diagnostic + .score + .bonus_questions + .iter() + .map(|question| { + let mut value = Value::dict(); + value.insert("number", Value::Int(question.number as i64)); + value.insert("points", Value::Float(question.points)); + value + }) + .collect(), + ), + ); score.insert("correct", Value::Int(diagnostic.score.correct as i64)); score.insert("items", Value::Int(diagnostic.score.n_items as i64)); out.insert("score", score); @@ -546,6 +564,8 @@ pub fn cohort_value(diagnostic: &CohortDiagnostic, config: &RenderConfig) -> Val Value::Array(diagnostic.distribution.bins.iter().map(bin_value).collect()), ); out.insert("distribution", distribution); + out.insert("mean-bonus", Value::Float(diagnostic.mean_bonus)); + out.insert("mean-curve", Value::Float(diagnostic.mean_curve)); let mut reliability = Value::dict(); reliability.insert_some("alpha", diagnostic.reliability.alpha.map(Value::Float)); @@ -1246,6 +1266,8 @@ mod tests { fn empty_cohort() -> CohortDiagnostic { CohortDiagnostic { + mean_bonus: 0.0, + mean_curve: 0.0, n_students: 24, n_items: 36, distribution: Distribution { diff --git a/src/export/typst/templates/cohort-report.typ b/src/export/typst/templates/cohort-report.typ index 43536c5..7ef6d3f 100644 --- a/src/export/typst/templates/cohort-report.typ +++ b/src/export/typst/templates/cohort-report.typ @@ -467,6 +467,19 @@ #pad(right: prose-pad)[#text(size: size-lead, fill: luma(90))[#rel.interpretation]] ] +#let mean-bonus = cb-data.at("mean-bonus", default: 0.0) +#let mean-curve = cb-data.at("mean-curve", default: 0.0) + +#if mean-bonus != 0.0 or mean-curve != 0.0 [ + #block(above: entry-gap)[ + #pad(right: prose-pad)[#text(size: size-lead, fill: luma(90))[ + These percentages match the gradebook, so they include an average of + #num(mean-bonus, digits: 2) bonus and #num(mean-curve, digits: 2) curve + points per student. Reliability and the item statistics do not. + ]] + ] +] + // ───────────────────────────────────────────────────────────────────────────── // Where the class landed // ───────────────────────────────────────────────────────────────────────────── diff --git a/src/export/typst/templates/student-report.typ b/src/export/typst/templates/student-report.typ index da43647..27f3758 100644 --- a/src/export/typst/templates/student-report.typ +++ b/src/export/typst/templates/student-report.typ @@ -57,7 +57,17 @@ name: "Sample Student", email: "sample@example.edu", form: "A", - score: (points: 27.0, possible: 36.0, percent: 75.0, bonus: 1.0, correct: 27, items: 36), + score: ( + points: 27.0, + possible: 36.0, + total: 31.6, + percent: 87.8, + bonus: 1.0, + curve: 3.6, + bonus-questions: ((number: 37, points: 1.0), (number: 38, points: 0.0)), + correct: 27, + items: 36, + ), standing: (class-mean: 71.2, class-sd: 11.4, band: "upper half"), levels: ( ( @@ -132,10 +142,12 @@ number: 2, level: 3, targets: ("t-sample-gap",), - measured: (( - objective: [A sample objective to work on.], - target: [A sample learning target under it.], - ),), + measured: ( + ( + objective: [A sample objective to work on.], + target: [A sample learning target under it.], + ), + ), correct: false, credit: 0.0, bonus: false, @@ -146,6 +158,30 @@ taught-in: ("Enthalpy (L1.1), slides 12, 13",), review: ((citation: "KKW §6.2", title: "Molecules and Medicine", url: "https://example.edu/6/2"),), ), + ( + number: 37, + level: 1, + targets: (), + measured: (), + correct: true, + credit: 1.0, + bonus: true, + blank: false, + taught-in: (), + review: (), + ), + ( + number: 38, + level: 1, + targets: (), + measured: (), + correct: false, + credit: 0.0, + bonus: true, + blank: false, + taught-in: (), + review: (), + ), ), dropped-questions: ((number: 35, full-credit: true),), review-lectures: ( @@ -275,7 +311,8 @@ // A rate is a fraction in 0..1; a percent is already out of 100. Keeping the two // straight is the only arithmetic this template does. #let pct(rate) = str(calc.round(rate * 100)) + "%" -#let pct1(value) = str(calc.round(value, digits: 0)) + "%" +#let pct1(value) = str(calc.round(value, digits: 1)) + "%" +#let pts(value) = str(calc.round(value, digits: 2)) #let plural(n, one, many) = if n == 1 { one } else { many } @@ -410,9 +447,12 @@ )[ #pad(right: prose-pad - 1.1cm)[ #text(size: size-lead)[ - This map explains what the exam covered and what your results mean, so you can use the information. Your score appears first because that's what you probably want to see. After that, you'll find more helpful details: which types of questions you did well on, which topics you might want to review, and what to read for each area. The last two sections are the most practical, so if you only read part of this, focus on those. + This map explains what the exam covered and what your results mean, so you can use the information. + Your score appears first because you probably want to see it. + After that, you'll find helpful details: which question types you did well on, which topics to review, and what to read for each area. + The last two sections are the most practical, so if you read only part of this, focus on those. - This report does not judge your abilities, and one question alone does not say much. If a score is based on just one or two questions, the report will point that out so you don't read too much into it. + This report doesn't judge your abilities, and one question alone doesn't say much. ] ] ] @@ -431,11 +471,7 @@ stat-card( "your score", pct1(score.percent), - note: str(score.points) - + " of " - + str(score.possible) - + " points" - + (if score.at("bonus", default: 0.0) > 0.0 { " (+" + str(score.bonus) + " bonus)" } else { "" }), + note: pts(score.at("total", default: score.points)) + " of " + pts(score.possible) + " points", ), stat-card( "questions right", @@ -457,6 +493,37 @@ }, ) +// The arithmetic behind the score, so it can be checked against the gradebook. +// Bonus and curve points are worth zero on the platform: they raise the total and +// leave the denominator alone, which is why a score can pass 100%. +#let bonus-questions = score.at("bonus-questions", default: ()) +#let curve-points = score.at("curve", default: 0.0) + +#if bonus-questions.len() > 0 or curve-points != 0.0 [ + #block(above: entry-gap)[ + #table( + columns: (1fr, auto), + stroke: none, + inset: (x: 0pt, y: 3pt), + align: (left, right), + [Questions], [#pts(score.points) of #pts(score.possible)], + ..if bonus-questions.len() > 0 { + ( + [Bonus #plural(bonus-questions.len(), "question", "questions") + #bonus-questions.map(q => str(q.number)).join(", ")], + [+#pts(score.at("bonus", default: 0.0))], + ) + } else { () }, + ..if curve-points != 0.0 { + ([Curve], [#if curve-points > 0.0 [+]#pts(curve-points)]) + } else { () }, + table.hline(stroke: 0.5pt + luma(180)), + [*Final score*], + [*#pts(score.at("total", default: score.points)) of #pts(score.possible) (#pct1(score.percent))*], + ) + ] +] + #let dropped-questions = cb-data.at("dropped-questions", default: ()) #if dropped-questions.len() > 0 [ @@ -473,7 +540,7 @@ if credited.len() > 0 [ #plural(credited.len(), "Question", "Questions") #numbers(credited) - #plural(credited.len(), "was", "were") thrown out after the exam. + #plural(credited.len(), "was", "were") dropped after the exam. Everyone received full credit for #plural(credited.len(), "it", "them"), so #plural(credited.len(), "it is", "they are") still counted in the @@ -796,11 +863,19 @@ #let question-box(q) = { let dropped = q.at("dropped", default: false) - let color = if dropped { luma(130) } else if q.at("blank", default: false) { + let bonus = q.at("bonus", default: false) + let credit = q.at("credit", default: 0.0) + // A bonus question can only add points, so one that earned nothing is not + // marked as an error, and its color follows the points it actually earned. + let color = if dropped { luma(130) } else if bonus and credit <= 0.0 { luma(160) - } else if q.at("correct", default: false) == true { + } else if q.at("blank", default: false) { + luma(160) + } else if bonus and credit >= 0.999 { ok-color - } else if q.at("credit", default: 0.0) > 0.0 { mid-color } else { bad-color } + } else if not bonus and q.at("correct", default: false) == true { + ok-color + } else if credit > 0.0 { mid-color } else { bad-color } box( width: 100%, fill: color.lighten(85%), @@ -814,6 +889,9 @@ if dropped { linebreak() text(size: size-tag, fill: luma(110))[out] + } else if bonus { + linebreak() + text(size: size-tag, fill: luma(110))[bonus] } else { let level = q.at("level", default: none) if level != none { @@ -848,6 +926,9 @@ #box(width: 0.7em, height: 0.7em, fill: bad-color.lighten(70%), radius: 2pt) not right · #box(width: 0.7em, height: 0.7em, fill: luma(210), radius: 2pt) left blank · #box(width: 0.7em, height: 0.7em, fill: luma(150), radius: 2pt) dropped, not scored + #if questions.any(q => q.at("bonus", default: false)) [ + · a box marked *bonus* can only add points, so a gray one cost you nothing + ] ] ] ]