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
+766 -76

No files matched your search

+10
View File
@@ -9,3 +9,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
### Added ### Added
- First public release. - 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.
+1 -1
View File
@@ -562,7 +562,7 @@ Two grading exports are supported, and the assessment id is required for both.
| Command | Reads | | 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) | | `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. Both readers produce the same long-format row, one per student per item.
+9 -1
View File
@@ -56,7 +56,15 @@ See [`typst_export`](crate::guide::typst_export).
**Gradescope.** **Gradescope.**
`coursebank ingest gradescope grading/exam-2/ --assessment exam-2`. `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.** **Canvas.**
`coursebank ingest canvas export.csv --assessment exam-2`. `coursebank ingest canvas export.csv --assessment exam-2`.
+51 -1
View File
@@ -206,16 +206,33 @@ pub struct Score {
pub points: f64, pub points: f64,
/// Points available on scored items. /// Points available on scored items.
pub points_possible: f64, 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, pub percent: f64,
/// Bonus points earned. /// Bonus points earned.
pub bonus_points: f64, 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<BonusQuestion>,
/// Items answered correctly. /// Items answered correctly.
pub correct: usize, pub correct: usize,
/// Scored items administered. /// Scored items administered.
pub n_items: usize, 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. /// Where a score sits in the class.
#[derive(Debug, Clone, Serialize)] #[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")] #[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()) .map(|a| a.items.iter().map(|i| (i.number, i.p_value)).collect())
.unwrap_or_default(); .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 { let questions = if opts.questions {
rows.iter() rows.iter()
.filter(|row| !row.is_curve())
.map(|row| question_row(row, catalog, &class_rates, opts)) .map(|row| question_row(row, catalog, &class_rates, opts))
.collect() .collect()
} else { } else {
Vec::new() 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<DroppedQuestion> = rows let mut dropped_questions: Vec<DroppedQuestion> = rows
.iter() .iter()
.filter(|r| r.dropped) .filter(|r| r.dropped)
@@ -630,8 +659,11 @@ pub fn student(
score: Score { score: Score {
points: summary.points, points: summary.points,
points_possible: summary.points_possible, points_possible: summary.points_possible,
total_points: summary.total_points,
percent: summary.percent, percent: summary.percent,
bonus_points: summary.bonus_points, bonus_points: summary.bonus_points,
curve_points: summary.curve_points,
bonus_questions,
correct: summary.correct, correct: summary.correct,
n_items: summary.n_items, n_items: summary.n_items,
}, },
@@ -972,6 +1004,10 @@ fn readings_for(course: &CourseFile, objective: &str, limit: usize) -> Vec<Study
#[derive(Debug, Clone, Serialize)] #[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "kebab-case")] #[serde(rename_all = "kebab-case")]
pub struct CohortDiagnostic { pub struct CohortDiagnostic {
/// Mean bonus points per student, which the distribution includes.
pub mean_bonus: f64,
/// Mean curve points per student, which the distribution includes.
pub mean_curve: f64,
/// How many students sat it. /// How many students sat it.
pub n_students: usize, pub n_students: usize,
/// How many scored items. /// How many scored items.
@@ -1758,6 +1794,8 @@ pub fn cohort(
n_students: cohort.students.len(), n_students: cohort.students.len(),
n_items: analysis.reliability.n_items, n_items: analysis.reliability.n_items,
distribution: distribution(&percents), distribution: distribution(&percents),
mean_bonus: mean_of(cohort, |s| s.bonus_points),
mean_curve: mean_of(cohort, |s| s.curve_points),
grades, grades,
lectures, lectures,
dropped_questions, dropped_questions,
@@ -2419,6 +2457,15 @@ fn form_rows(set: &ResponseSet, cohort: &Cohort) -> Vec<FormRow> {
.collect() .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::<f64>() / cohort.students.len() as f64
}
}
/// Bins a set of percentages into a distribution. /// Bins a set of percentages into a distribution.
fn distribution(percents: &[f64]) -> Distribution { fn distribution(percents: &[f64]) -> Distribution {
let mut sorted: Vec<f64> = percents.to_vec(); let mut sorted: Vec<f64> = percents.to_vec();
@@ -2504,8 +2551,11 @@ mod tests {
score: Score { score: Score {
points: 1.0, points: 1.0,
points_possible: 2.0, points_possible: 2.0,
total_points: 1.0,
percent: 50.0, percent: 50.0,
bonus_points: 0.0, bonus_points: 0.0,
curve_points: 0.0,
bonus_questions: Vec::new(),
correct: 1, correct: 1,
n_items: 2, n_items: 2,
}, },
+11 -2
View File
@@ -203,10 +203,15 @@ pub struct StudentSummary {
pub points: f64, pub points: f64,
/// Points available on scored items. /// Points available on scored items.
pub points_possible: f64, 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, pub percent: f64,
/// Bonus points earned. /// Bonus points earned.
pub bonus_points: f64, pub bonus_points: f64,
/// Points a curve added.
pub curve_points: f64,
/// Items answered correctly. /// Items answered correctly.
pub correct: usize, pub correct: usize,
/// Items administered. /// Items administered.
@@ -355,7 +360,7 @@ pub fn summarize(
let percents: Vec<f64> = students let percents: Vec<f64> = students
.iter() .iter()
.map(|key| { .map(|key| {
let earned = set.scored_total(key); let earned = set.points_of_record(key);
let possible = set.points_available(); let possible = set.points_available();
if possible > 0.0 { if possible > 0.0 {
100.0 * earned / possible 100.0 * earned / possible
@@ -513,8 +518,10 @@ pub fn summarize(
sid: rows.first().and_then(|r| r.sid.clone()), sid: rows.first().and_then(|r| r.sid.clone()),
points, points,
points_possible: possible, points_possible: possible,
total_points: set.points_of_record(key),
percent, percent,
bonus_points: set.bonus_total(key), bonus_points: set.bonus_total(key),
curve_points: set.curve_total(key),
correct, correct,
n_items, n_items,
band: band_for(percent, &percents), band: band_for(percent, &percents),
@@ -1389,8 +1396,10 @@ learning_objectives:
sid: None, sid: None,
points: 0.0, points: 0.0,
points_possible: 0.0, points_possible: 0.0,
total_points: 0.0,
percent: 0.0, percent: 0.0,
bonus_points: 0.0, bonus_points: 0.0,
curve_points: 0.0,
correct: 0, correct: 0,
n_items: 0, n_items: 0,
band: String::new(), band: String::new(),
+66 -1
View File
@@ -1472,6 +1472,11 @@ fn placement_schema() -> Value {
}, },
"item": text("Item reference, `bank::item-id` or a bare item id."), "item": text("Item reference, `bank::item-id` or a bare item id."),
"version": { "type": "integer", "minimum": 1 }, "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": { "fingerprint": {
"type": "string", "type": "string",
"description": "What the item looked like when given. Validation warns if the item \ "description": "What the item looked like when given. Validation warns if the item \
@@ -1496,6 +1501,7 @@ fn placement_schema() -> Value {
}, },
"level": level(), "level": level(),
"learning_targets": string_array("Targets as administered."), "learning_targets": string_array("Targets as administered."),
"learning_objectives": string_array("The older name for learning_targets."),
"credit_overrides": { "credit_overrides": {
"type": "object", "type": "object",
"description": "Partial credit decided after the fact, by option letter. Recording \ "description": "Partial credit decided after the fact, by option letter. Recording \
@@ -1505,7 +1511,23 @@ fn placement_schema() -> Value {
}, },
"dropped": { "dropped": {
"type": "boolean", "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] #[test]
fn modelines_point_at_the_right_file() { fn modelines_point_at_the_right_file() {
assert_eq!( assert_eq!(
+3 -2
View File
@@ -195,8 +195,9 @@ pub(crate) fn ingest(cli: &Cli, sub: &IngestCommand) -> Result<Outcome> {
for source in &parsed { for source in &parsed {
if !intake::looks_like_export(&source.dir) { if !intake::looks_like_export(&source.dir) {
return Err(Error::usage(format!( return Err(Error::usage(format!(
"{} holds no files named `1.csv` … `N.csv`. Gradescope writes one file \ "{} holds no files named `1.csv` … `N.csv` or `N_Title.csv`. Gradescope \
per question; point at the directory those were unzipped into", writes one file per question; point at the directory those were \
unzipped into",
source.dir.display() source.dir.display()
))); )));
} }
+3 -2
View File
@@ -207,8 +207,9 @@ pub(crate) fn ingest(cli: &Cli, sub: &IngestCommand) -> Result<Outcome> {
for source in &parsed { for source in &parsed {
if !intake::looks_like_export(&source.dir) { if !intake::looks_like_export(&source.dir) {
return Err(Error::usage(format!( return Err(Error::usage(format!(
"{} holds no files named `1.csv` … `N.csv`. Gradescope writes one file \ "{} holds no files named `1.csv` … `N.csv` or `N_Title.csv`. Gradescope \
per question; point at the directory those were unzipped into", writes one file per question; point at the directory those were \
unzipped into",
source.dir.display() source.dir.display()
))); )));
} }
+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 // something else entirely. Nothing downstream can tell them apart, so the
// collision has to be caught here. // collision has to be caught here.
let recorded: BTreeSet<u32> = decoder.numbers().collect(); let recorded: BTreeSet<u32> = decoder.numbers().collect();
let last_recorded = recorded.iter().next_back().copied().unwrap_or(0);
for row in &mut set.rows { for row in &mut set.rows {
let belongs = row 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 { 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); unmapped_positions.insert(row.item_number);
if recorded.contains(&row.item_number) { if recorded.contains(&row.item_number) {
colliding_positions.insert(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"); 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] #[test]
fn a_perfect_fit_says_nothing() { fn a_perfect_fit_says_nothing() {
let fits = vec![FormFit { let fits = vec![FormFit {
+260 -31
View File
@@ -5,9 +5,10 @@
//! Reading Gradescope's per-question CSV exports. //! Reading Gradescope's per-question CSV exports.
//! //!
//! Gradescope exports one file per question, named `1.csv` through `N.csv`, in //! 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, //! wide form, with the title appended when the question has one: `39_Curve.csv`.
//! 24-student export rather than inferred from documentation, because several of //! Every assumption encoded here was checked against a real 32-question, 24-student
//! them are not what the format suggests. //! export rather than inferred from documentation, because several of them are not
//! what the format suggests.
//! //!
//! The layout is: //! The layout is:
//! //!
@@ -43,6 +44,12 @@
//! *Bonus questions have `max_points` of zero* while a rubric column still //! *Bonus questions have `max_points` of zero* while a rubric column still
//! carries points. Key detection therefore uses the largest value across the //! carries points. Key detection therefore uses the largest value across the
//! maximum *and* every column, not the maximum alone. //! 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::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
@@ -185,9 +192,26 @@ impl Question {
/// ///
/// # Returns /// # 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 { 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. /// 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) (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. /// Parses one question file.
/// ///
/// # Arguments /// # Arguments
@@ -322,13 +367,10 @@ pub fn classify(label: &str) -> (ColumnKind, Option<String>, Option<String>) {
/// Returns [`Error::Csv`] on a malformed file and [`Error::Invalid`] when the /// Returns [`Error::Csv`] on a malformed file and [`Error::Invalid`] when the
/// header lacks the `Submission Time` column that delimits the rubric. /// header lacks the `Submission Time` column that delimits the rubric.
pub fn parse_question(path: &Path) -> Result<Question> { pub fn parse_question(path: &Path) -> Result<Question> {
let number = path let number = question_number(path).ok_or_else(|| {
.file_stem()
.and_then(|s| s.to_str())
.and_then(|s| s.parse::<u32>().ok())
.ok_or_else(|| {
Error::Invalid(vec![format!( Error::Invalid(vec![format!(
"{} is not named like a Gradescope question export (expected `12.csv`)", "{} is not named like a Gradescope question export (expected `12.csv` or \
`12_Title.csv`)",
path.display() path.display()
)]) )])
})?; })?;
@@ -503,53 +545,68 @@ pub fn parse_question(path: &Path) -> Result<Question> {
/// ///
/// # Arguments /// # 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. /// * `ctx` - identifying information the export does not carry.
/// ///
/// # Returns /// # 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 /// # Errors
/// ///
/// Returns [`Error::Io`] when the directory cannot be read and [`Error::Invalid`] /// 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> { pub fn ingest_dir(dir: &Path, ctx: &Context) -> Result<Import> {
let mut paths: Vec<PathBuf> = std::fs::read_dir(dir) let mut paths: Vec<PathBuf> = std::fs::read_dir(dir)
.map_err(|e| Error::io(dir, e))? .map_err(|e| Error::io(dir, e))?
.filter_map(|e| e.ok()) .filter_map(|e| e.ok())
.map(|e| e.path()) .map(|e| e.path())
.filter(|p| { .filter(|p| p.extension().and_then(|e| e.to_str()) == Some("csv"))
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)
})
.collect(); .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() { if paths.is_empty() {
return Err(Error::Invalid(vec![format!( return Err(Error::Invalid(vec![format!(
"{} holds no numbered CSV files; Gradescope exports one file per question, \ "{} 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() dir.display()
)])); )]));
} }
// Numeric order, so `10.csv` does not sort before `2.csv`. for pair in paths.windows(2) {
paths.sort_by_key(|p| { if question_number(&pair[0]) == question_number(&pair[1]) {
p.file_stem() return Err(Error::Invalid(vec![format!(
.and_then(|s| s.to_str()) "{} and {} are both exports of the same question; remove the one that is out of \
.and_then(|s| s.parse::<u32>().ok()) date",
.unwrap_or(u32::MAX) pair[0].display(),
}); pair[1].display()
)]));
}
}
let mut questions = Vec::new(); let mut questions = Vec::new();
for p in &paths { for p in &paths {
questions.push(parse_question(p)?); 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. /// Normalizes parsed questions into responses.
@@ -572,7 +629,14 @@ pub fn to_responses(questions: &[Question], ctx: &Context) -> Import {
let points = q.points_possible(); let points = q.points_possible();
let bonus = q.looks_like_bonus(); 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!( set.warnings.push(format!(
"question {}: no keyed option could be identified from the point values, so \ "question {}: no keyed option could be identified from the point values, so \
correctness is unknown; scores are still recorded", correctness is unknown; scores are still recorded",
@@ -779,6 +843,63 @@ mod tests {
assert_eq!(question.points_possible(), 1.5); 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] #[test]
fn partial_credit_to_a_distractor_flags_ambiguity() { fn partial_credit_to_a_distractor_flags_ambiguity() {
// Real case: q14, where B earned 1.49 of 1.5. // Real case: q14, where B earned 1.49 of 1.5.
@@ -854,6 +975,114 @@ mod tests {
std::fs::remove_dir_all(&dir).ok(); 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] #[test]
fn rejects_a_file_without_the_rubric_delimiter() { fn rejects_a_file_without_the_rubric_delimiter() {
let dir = std::env::temp_dir().join(format!("cb-gs-bad-{}", std::process::id())); 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 /// # 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 { pub fn looks_like_export(dir: &Path) -> bool {
let Ok(entries) = std::fs::read_dir(dir) else { let Ok(entries) = std::fs::read_dir(dir) else {
return false; return false;
}; };
entries.filter_map(|e| e.ok()).any(|entry| { entries
let path = entry.path(); .filter_map(|e| e.ok())
path.extension().and_then(|e| e.to_str()) == Some("csv") .any(|entry| gradescope::question_number(&entry.path()).is_some())
&& path
.file_stem()
.and_then(|s| s.to_str())
.map(|s| s.chars().all(|c| c.is_ascii_digit()))
.unwrap_or(false)
})
} }
#[cfg(test)] #[cfg(test)]
+136 -4
View File
@@ -161,6 +161,23 @@ impl Response {
!self.bonus && (!self.dropped || self.dropped_full_credit) !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. /// The response coded for a dichotomous model.
/// ///
/// Partial credit is rounded toward the majority: a half-credit response is /// Partial credit is rounded toward the majority: a half-credit response is
@@ -302,15 +319,43 @@ impl ResponseSet {
.sum() .sum()
} }
/// Bonus points a student earned. /// Bonus points a student earned on bonus questions.
pub fn bonus_total(&self, key: &str) -> f64 { pub fn bonus_total(&self, key: &str) -> f64 {
self.rows self.rows
.iter() .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) .map(|r| r.score)
.sum() .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 /// 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. /// for each item so a student who skipped an item still has a denominator.
pub fn points_available(&self) -> f64 { pub fn points_available(&self) -> f64 {
@@ -383,7 +428,7 @@ impl ResponseSet {
let items: Vec<u32> = if include_bonus { let items: Vec<u32> = if include_bonus {
self.all_items() self.all_items()
.into_iter() .into_iter()
.filter(|n| !self.item_dropped(*n)) .filter(|n| !self.item_dropped(*n) && !self.item_is_curve(*n))
.collect() .collect()
} else { } else {
self.scored_items() self.scored_items()
@@ -439,6 +484,14 @@ impl ResponseSet {
any 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. /// Attaches item metadata from an assessment record and the catalog.
/// ///
/// Ingest knows question numbers; only the record knows which item a number /// Ingest knows question numbers; only the record knows which item a number
@@ -464,7 +517,10 @@ impl ResponseSet {
for r in &mut self.rows { for r in &mut self.rows {
let Some(p) = record.placement(r.item_number) else { let Some(p) = record.placement(r.item_number) else {
// A curve is never in the record, so its absence says nothing.
if !r.is_curve() {
unmatched.insert(r.item_number); unmatched.insert(r.item_number);
}
continue; continue;
}; };
r.item_ref = Some(p.item.clone()); r.item_ref = Some(p.item.clone());
@@ -475,7 +531,9 @@ impl ResponseSet {
r.bonus = r.bonus || p.bonus; r.bonus = r.bonus || p.bonus;
r.dropped = r.dropped || p.dropped; r.dropped = r.dropped || p.dropped;
r.dropped_full_credit = r.dropped_full_credit || p.dropped_with_credit(); 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 // The record is authoritative for points as administered; the
// export sometimes carries a stale maximum. // export sometimes carries a stale maximum.
if (points - r.points_possible).abs() > 1e-9 && r.points_possible > 0.0 { if (points - r.points_possible).abs() > 1e-9 && r.points_possible > 0.0 {
@@ -541,6 +599,29 @@ impl ResponseSet {
list.join(", ") 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()); self.warnings.extend(warnings.clone());
warnings warnings
} }
@@ -977,6 +1058,57 @@ mod tests {
assert_eq!(set.bonus_total("s1"), 2.0); 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] #[test]
fn dropped_items_leave_the_matrix() { fn dropped_items_leave_the_matrix() {
let mut set = ResponseSet::new(); let mut set = ResponseSet::new();
+37 -6
View File
@@ -100,13 +100,16 @@ pub fn student(
// --- score // --- score
out.push_str(&format!( out.push_str(&format!(
"You scored **{:.1} of {:.1} points ({:.0}%)**", "You scored **{} of {} points ({:.1}%)**",
summary.points, summary.points_possible, summary.percent points(summary.total_points),
points(summary.points_possible),
summary.percent
)); ));
let mut extras = Vec::new();
if summary.bonus_points > 0.0 { if summary.bonus_points > 0.0 {
out.push_str(&format!( extras.push(format!(
", plus {:.1} bonus point{}", "{} bonus point{}",
summary.bonus_points, points(summary.bonus_points),
if (summary.bonus_points - 1.0).abs() < 1e-9 { if (summary.bonus_points - 1.0).abs() < 1e-9 {
"" ""
} else { } 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!( out.push_str(&format!(
", answering {} of {} questions correctly.\n\n", ", answering {} of {} questions correctly.\n\n",
summary.correct, summary.n_items summary.correct, summary.n_items
@@ -121,7 +138,7 @@ pub fn student(
if opts.comparison { if opts.comparison {
out.push_str(&format!( 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 cohort.mean_percent, summary.band
)); ));
} }
@@ -684,6 +701,20 @@ pub fn roster(cohort: &Cohort) -> String {
out 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`. /// A small unicode bar for a rate in `0.0..=1.0`.
/// ///
/// # Arguments /// # Arguments
+22
View File
@@ -196,8 +196,26 @@ pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> V
let mut score = Value::dict(); let mut score = Value::dict();
score.insert("points", Value::Float(diagnostic.score.points)); score.insert("points", Value::Float(diagnostic.score.points));
score.insert("possible", Value::Float(diagnostic.score.points_possible)); 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("percent", Value::Float(diagnostic.score.percent));
score.insert("bonus", Value::Float(diagnostic.score.bonus_points)); 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("correct", Value::Int(diagnostic.score.correct as i64));
score.insert("items", Value::Int(diagnostic.score.n_items as i64)); score.insert("items", Value::Int(diagnostic.score.n_items as i64));
out.insert("score", score); 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()), Value::Array(diagnostic.distribution.bins.iter().map(bin_value).collect()),
); );
out.insert("distribution", distribution); 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(); let mut reliability = Value::dict();
reliability.insert_some("alpha", diagnostic.reliability.alpha.map(Value::Float)); reliability.insert_some("alpha", diagnostic.reliability.alpha.map(Value::Float));
@@ -1246,6 +1266,8 @@ mod tests {
fn empty_cohort() -> CohortDiagnostic { fn empty_cohort() -> CohortDiagnostic {
CohortDiagnostic { CohortDiagnostic {
mean_bonus: 0.0,
mean_curve: 0.0,
n_students: 24, n_students: 24,
n_items: 36, n_items: 36,
distribution: Distribution { distribution: Distribution {
@@ -467,6 +467,19 @@
#pad(right: prose-pad)[#text(size: size-lead, fill: luma(90))[#rel.interpretation]] #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 // Where the class landed
// ───────────────────────────────────────────────────────────────────────────── // ─────────────────────────────────────────────────────────────────────────────
+96 -15
View File
@@ -57,7 +57,17 @@
name: "Sample Student", name: "Sample Student",
email: "sample@example.edu", email: "sample@example.edu",
form: "A", 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"), standing: (class-mean: 71.2, class-sd: 11.4, band: "upper half"),
levels: ( levels: (
( (
@@ -132,10 +142,12 @@
number: 2, number: 2,
level: 3, level: 3,
targets: ("t-sample-gap",), targets: ("t-sample-gap",),
measured: (( measured: (
(
objective: [A sample objective to work on.], objective: [A sample objective to work on.],
target: [A sample learning target under it.], target: [A sample learning target under it.],
),), ),
),
correct: false, correct: false,
credit: 0.0, credit: 0.0,
bonus: false, bonus: false,
@@ -146,6 +158,30 @@
taught-in: ("Enthalpy (L1.1), slides 12, 13",), taught-in: ("Enthalpy (L1.1), slides 12, 13",),
review: ((citation: "KKW §6.2", title: "Molecules and Medicine", url: "https://example.edu/6/2"),), 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),), dropped-questions: ((number: 35, full-credit: true),),
review-lectures: ( review-lectures: (
@@ -275,7 +311,8 @@
// A rate is a fraction in 0..1; a percent is already out of 100. Keeping the two // 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. // straight is the only arithmetic this template does.
#let pct(rate) = str(calc.round(rate * 100)) + "%" #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 } #let plural(n, one, many) = if n == 1 { one } else { many }
@@ -410,9 +447,12 @@
)[ )[
#pad(right: prose-pad - 1.1cm)[ #pad(right: prose-pad - 1.1cm)[
#text(size: size-lead)[ #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( stat-card(
"your score", "your score",
pct1(score.percent), pct1(score.percent),
note: str(score.points) note: pts(score.at("total", default: score.points)) + " of " + pts(score.possible) + " points",
+ " of "
+ str(score.possible)
+ " points"
+ (if score.at("bonus", default: 0.0) > 0.0 { " (+" + str(score.bonus) + " bonus)" } else { "" }),
), ),
stat-card( stat-card(
"questions right", "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: ()) #let dropped-questions = cb-data.at("dropped-questions", default: ())
#if dropped-questions.len() > 0 [ #if dropped-questions.len() > 0 [
@@ -473,7 +540,7 @@
if credited.len() > 0 [ if credited.len() > 0 [
#plural(credited.len(), "Question", "Questions") #numbers(credited) #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 Everyone received full credit for
#plural(credited.len(), "it", "them"), so #plural(credited.len(), "it", "them"), so
#plural(credited.len(), "it is", "they are") still counted in the #plural(credited.len(), "it is", "they are") still counted in the
@@ -796,11 +863,19 @@
#let question-box(q) = { #let question-box(q) = {
let dropped = q.at("dropped", default: false) 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) 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 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( box(
width: 100%, width: 100%,
fill: color.lighten(85%), fill: color.lighten(85%),
@@ -814,6 +889,9 @@
if dropped { if dropped {
linebreak() linebreak()
text(size: size-tag, fill: luma(110))[out] text(size: size-tag, fill: luma(110))[out]
} else if bonus {
linebreak()
text(size: size-tag, fill: luma(110))[bonus]
} else { } else {
let level = q.at("level", default: none) let level = q.at("level", default: none)
if level != 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: 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(210), radius: 2pt) left blank ·
#box(width: 0.7em, height: 0.7em, fill: luma(150), radius: 2pt) dropped, not scored #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
]
] ]
] ]
] ]