refactor: improve cohort report

This commit is contained in:
alexm committed 2026-09-19 22:19:25 -04:00
1 parent c06d5caa8c
commit 92c8a8fc75
6 files changed
+2194 -311

No files matched your search

+129
View File
@@ -137,6 +137,58 @@ pub struct Policy {
/// The fewest items on an objective before a report will call it mastered.
#[serde(default = "two_usize")]
pub min_items_for_mastery: usize,
/// The letter-grade bands, highest first or in any order.
///
/// Empty by default, because a grading scale belongs to a course rather than
/// to a tool. When it is set, a class report bins the score distribution by
/// letter instead of by ten-point interval, which is the only binning a
/// student or an instructor actually acts on.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub grade_scale: Vec<GradeBand>,
}
/// One letter-grade band.
///
/// Only the lower bound is recorded. An upper bound would be a second copy of
/// the next band's lower bound, and the two would eventually disagree: a scale
/// written as `93.0 - 96.9` leaves 96.95 in no band at all. Bands are read as
/// "this letter or better from here up", so the top band needs no ceiling.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GradeBand {
/// The letter as it appears on a transcript.
pub letter: String,
/// The lowest percentage that earns it, inclusive.
pub min: f64,
/// The grade points it carries, when the course records them.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub gpa: Option<f64>,
/// The attainment word attached to the band, such as `Meritorious`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub attainment: Option<String>,
/// A colour group, so a report can tint A bands alike without parsing
/// letters. Defaults to the letter's first character.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub group: Option<String>,
}
impl GradeBand {
/// The group a band belongs to: its own `group`, else its first character.
///
/// # Returns
///
/// An uppercase group key such as `A`.
pub fn group_key(&self) -> String {
match &self.group {
Some(group) => group.to_ascii_uppercase(),
None => self
.letter
.chars()
.next()
.map(|c| c.to_ascii_uppercase().to_string())
.unwrap_or_default(),
}
}
}
impl Default for Policy {
@@ -149,10 +201,44 @@ impl Default for Policy {
partial_credit_floor_level: None,
mastery_threshold: mastery_default(),
min_items_for_mastery: 2,
grade_scale: Vec::new(),
}
}
}
impl Policy {
/// The grade bands, highest lower bound first.
///
/// # Returns
///
/// The bands in descending order, empty when the course sets no scale.
pub fn bands(&self) -> Vec<&GradeBand> {
let mut out: Vec<&GradeBand> = self.grade_scale.iter().collect();
out.sort_by(|a, b| {
b.min
.partial_cmp(&a.min)
.unwrap_or(std::cmp::Ordering::Equal)
});
out
}
/// The band a percentage falls in.
///
/// # Arguments
///
/// * `percent` - a score out of 100.
///
/// # Returns
///
/// The band, or `None` when the course sets no scale or the score sits below
/// every band in it.
pub fn band_for(&self, percent: f64) -> Option<&GradeBand> {
self.bands()
.into_iter()
.find(|band| percent + 1e-9 >= band.min)
}
}
/// A unit or module of the course.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
@@ -622,6 +708,49 @@ impl CourseFile {
));
}
// A scale with a hole in it silently drops students into no band at all,
// and the report would show a distribution that does not sum to the
// class. Cheaper to say so here.
let mut seen_letters: BTreeMap<&str, usize> = BTreeMap::new();
let mut seen_mins: Vec<f64> = Vec::new();
for band in &self.policy.grade_scale {
*seen_letters.entry(band.letter.as_str()).or_insert(0) += 1;
if !(0.0..=100.0).contains(&band.min) {
issues.push(format!(
"policy.grade_scale: band `{}` has min {}, which is not a percentage",
band.letter, band.min
));
}
if seen_mins.iter().any(|m| (m - band.min).abs() < 1e-9) {
issues.push(format!(
"policy.grade_scale: two bands start at {}%, so the lower one is unreachable",
band.min
));
}
seen_mins.push(band.min);
}
for (letter, n) in &seen_letters {
if *n > 1 {
issues.push(format!(
"policy.grade_scale: duplicate letter `{letter}` declared {n} times"
));
}
}
if !self.policy.grade_scale.is_empty() {
let lowest = self
.policy
.bands()
.last()
.map(|b| b.min)
.unwrap_or(f64::INFINITY);
if lowest > 0.0 {
issues.push(format!(
"policy.grade_scale: the lowest band starts at {lowest}%, so a score below \
that falls in no band. Give the failing grade a min of 0."
));
}
}
let unit_ids: Vec<&String> = self.units.iter().map(|u| &u.id).collect();
let mut unit_counts: BTreeMap<&str, usize> = BTreeMap::new();
for u in &self.units {