feat: implement reports
This commit is contained in:
@@ -0,0 +1,904 @@
|
||||
// SPDX-License-Identifier: Prosperity-3.0.0
|
||||
// Copyright Scientific Computing Studio
|
||||
// Source: https://git.scient.ing/education/coursebank
|
||||
|
||||
//! Handing a diagnostic to a Typst template.
|
||||
//!
|
||||
//! The same arrangement the exam export uses: this module decides what the
|
||||
//! template is told, the template decides what it looks like, and the two meet at
|
||||
//! a marker comment. Nothing here knows about page size or colour.
|
||||
//!
|
||||
//! Two slots are filled, both already defined for the exam path:
|
||||
//!
|
||||
//! | Slot | Injected |
|
||||
//! |:--|:--|
|
||||
//! | `meta` | `#let cb-meta = (...)` — course, assessment, generator, class size |
|
||||
//! | `data` | `#let cb-data = (...)` — one student's diagnostic, or the class's |
|
||||
//!
|
||||
//! The `questions` slot is deliberately unused. It exists to emit question stems,
|
||||
//! and a diagnostic has none to emit: see
|
||||
//! [`crate::diagnostic::StudentDiagnostic`], which has no field for one. A student
|
||||
//! report template that wanted to print a stem would have nothing to print it
|
||||
//! from, which is the property worth preserving.
|
||||
//!
|
||||
//! Prose fields — objective text, the feedback written for a chosen option, a
|
||||
//! reading's focus sentence — go through the same markup path as an exam stem, so
|
||||
//! `$\Delta G$` in `course.yaml` renders the same way in a report as it does on
|
||||
//! the paper.
|
||||
|
||||
use crate::assessment::AssessmentFile;
|
||||
use crate::catalog::Catalog;
|
||||
use crate::diagnostic::{
|
||||
Bin, CohortDiagnostic, CohortObjectiveRow, CohortQuestionRow, StudentDiagnostic, StudyGroup,
|
||||
};
|
||||
use crate::error::{Error, Result};
|
||||
use crate::layout::Layout;
|
||||
use crate::typst::config::{RenderConfig, Variant};
|
||||
use crate::typst::payload::markup_value;
|
||||
use crate::typst::template::{self, Origin, Slot};
|
||||
use crate::typst::value::Value;
|
||||
|
||||
/// A rendered diagnostic document.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Document {
|
||||
/// Which document this is.
|
||||
pub variant: Variant,
|
||||
/// Where the template came from.
|
||||
pub origin: Origin,
|
||||
/// Which slots it declared.
|
||||
pub slots: Vec<Slot>,
|
||||
/// The Typst source.
|
||||
pub text: String,
|
||||
/// Advisory problems.
|
||||
pub warnings: Vec<String>,
|
||||
}
|
||||
|
||||
/// The identity block every diagnostic carries.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Meta {
|
||||
/// Course code.
|
||||
pub course_code: String,
|
||||
/// Course title.
|
||||
pub course_title: String,
|
||||
/// The term.
|
||||
pub term: String,
|
||||
/// Institution, when the course names one.
|
||||
pub institution: Option<String>,
|
||||
/// Assessment id.
|
||||
pub assessment_id: String,
|
||||
/// Assessment title.
|
||||
pub assessment_title: String,
|
||||
/// The administration date, as `YYYY-MM-DD`.
|
||||
pub date: Option<String>,
|
||||
/// The day the report was generated.
|
||||
pub generated_on: String,
|
||||
/// The tool version, so a report found later can be traced.
|
||||
pub version: String,
|
||||
/// How many students sat the assessment.
|
||||
pub n_students: usize,
|
||||
/// The course's mastery threshold, so a template can draw the line in the
|
||||
/// same place the classification used.
|
||||
pub mastery_threshold: f64,
|
||||
/// How many items an objective needs before it is classified at all.
|
||||
pub min_items_for_mastery: usize,
|
||||
}
|
||||
|
||||
impl Meta {
|
||||
/// Builds the identity block.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `catalog` - the loaded course.
|
||||
/// * `record` - the assessment record.
|
||||
/// * `n_students` - the cohort size.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The block.
|
||||
pub fn new(catalog: &Catalog, record: &AssessmentFile, n_students: usize) -> Meta {
|
||||
Meta {
|
||||
course_code: catalog.course.course.code.clone(),
|
||||
course_title: catalog.course.course.title.clone(),
|
||||
term: record
|
||||
.assessment
|
||||
.term
|
||||
.clone()
|
||||
.unwrap_or_else(|| catalog.course.course.term.clone()),
|
||||
institution: catalog.course.course.institution.clone(),
|
||||
assessment_id: record.assessment.id.clone(),
|
||||
assessment_title: record.assessment.title.clone(),
|
||||
date: record.assessment.date.map(|d| d.to_string()),
|
||||
generated_on: crate::date::Date::today().to_string(),
|
||||
version: crate::VERSION.to_string(),
|
||||
n_students,
|
||||
mastery_threshold: catalog.course.policy.mastery_threshold,
|
||||
min_items_for_mastery: catalog.course.policy.min_items_for_mastery,
|
||||
}
|
||||
}
|
||||
|
||||
/// The metadata as a Typst value.
|
||||
fn value(&self, config: &RenderConfig) -> Value {
|
||||
let mut course = Value::dict();
|
||||
course.insert("code", Value::str(&self.course_code));
|
||||
course.insert("title", Value::str(&self.course_title));
|
||||
course.insert("term", Value::str(&self.term));
|
||||
if let Some(institution) = &self.institution {
|
||||
course.insert("institution", Value::str(institution));
|
||||
}
|
||||
|
||||
let mut assessment = Value::dict();
|
||||
assessment.insert("id", Value::str(&self.assessment_id));
|
||||
assessment.insert("title", Value::str(&self.assessment_title));
|
||||
assessment.insert_some("date", self.date.as_ref().map(Value::str));
|
||||
|
||||
let mut generator = Value::dict();
|
||||
generator.insert("tool", Value::str("coursebank"));
|
||||
generator.insert("version", Value::str(&self.version));
|
||||
generator.insert("on", Value::str(&self.generated_on));
|
||||
|
||||
let mut policy = Value::dict();
|
||||
policy.insert("mastery-threshold", Value::Float(self.mastery_threshold));
|
||||
policy.insert(
|
||||
"min-items-for-mastery",
|
||||
Value::Int(self.min_items_for_mastery as i64),
|
||||
);
|
||||
|
||||
let mut out = Value::dict();
|
||||
out.insert("course", course);
|
||||
out.insert("assessment", assessment);
|
||||
out.insert("generator", generator);
|
||||
out.insert("policy", policy);
|
||||
out.insert("class-size", Value::Int(self.n_students as i64));
|
||||
out.insert("extra", extra_value(config));
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
/// The render config's `extra` block, carried through untouched.
|
||||
fn extra_value(config: &RenderConfig) -> Value {
|
||||
let mut out = Value::dict();
|
||||
for (key, value) in &config.extra {
|
||||
out.insert(key.clone(), crate::typst::value::from_yaml(value, false));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// One student's diagnostic as a Typst value.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `diagnostic` - the assembled diagnostic.
|
||||
/// * `config` - the render config, for markup handling.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A dictionary the template binds as `cb-data`.
|
||||
pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> Value {
|
||||
let content = config.content.is_content();
|
||||
let mut out = Value::dict();
|
||||
|
||||
out.insert("student-key", Value::str(&diagnostic.student_key));
|
||||
out.insert_some("name", diagnostic.name.as_ref().map(Value::str));
|
||||
out.insert_some("sid", diagnostic.sid.as_ref().map(Value::str));
|
||||
out.insert_some("form", diagnostic.form.as_ref().map(Value::str));
|
||||
|
||||
let mut score = Value::dict();
|
||||
score.insert("points", Value::Float(diagnostic.score.points));
|
||||
score.insert("possible", Value::Float(diagnostic.score.points_possible));
|
||||
score.insert("percent", Value::Float(diagnostic.score.percent));
|
||||
score.insert("bonus", Value::Float(diagnostic.score.bonus_points));
|
||||
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);
|
||||
|
||||
if let Some(standing) = &diagnostic.standing {
|
||||
let mut value = Value::dict();
|
||||
value.insert("class-mean", Value::Float(standing.class_mean));
|
||||
value.insert("class-sd", Value::Float(standing.class_sd));
|
||||
value.insert("band", Value::str(&standing.band));
|
||||
value.insert_some("theta", standing.theta.map(Value::Float));
|
||||
value.insert_some("theta-se", standing.theta_se.map(Value::Float));
|
||||
out.insert("standing", value);
|
||||
}
|
||||
|
||||
out.insert(
|
||||
"levels",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.levels
|
||||
.iter()
|
||||
.map(|level| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("level", Value::Int(level.level as i64));
|
||||
value.insert("name", Value::str(&level.name));
|
||||
value.insert("blurb", Value::str(&level.blurb));
|
||||
value.insert("items", Value::Int(level.n_items as i64));
|
||||
value.insert("rate", Value::Float(level.rate));
|
||||
value.insert_some("class-rate", level.class_rate.map(Value::Float));
|
||||
value.insert_some("comparison", level.comparison.as_ref().map(Value::str));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"objectives",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.objectives
|
||||
.iter()
|
||||
.map(|objective| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("id", Value::str(&objective.id));
|
||||
value.insert("text", markup_value(&objective.text, content));
|
||||
value.insert_some("unit", objective.unit.as_ref().map(Value::str));
|
||||
value.insert("items", Value::Int(objective.n_items as i64));
|
||||
value.insert("credit", Value::Float(objective.credit));
|
||||
value.insert("rate", Value::Float(objective.rate));
|
||||
value.insert("lower", Value::Float(objective.lower));
|
||||
value.insert("upper", Value::Float(objective.upper));
|
||||
value.insert_some("class-rate", objective.class_rate.map(Value::Float));
|
||||
value.insert("status", Value::str(&objective.status));
|
||||
value.insert("symbol", Value::str(&objective.symbol));
|
||||
value.insert("confident", Value::Bool(objective.confident));
|
||||
value.insert("thin-evidence", Value::Bool(objective.thin_evidence));
|
||||
value.insert(
|
||||
"levels",
|
||||
Value::Array(
|
||||
objective
|
||||
.levels
|
||||
.iter()
|
||||
.map(|l| Value::Int(*l as i64))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
let objective_refs = |rows: &[crate::diagnostic::ObjectiveRef]| -> Value {
|
||||
Value::Array(
|
||||
rows.iter()
|
||||
.map(|row| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("id", Value::str(&row.id));
|
||||
value.insert("text", markup_value(&row.text, content));
|
||||
value.insert("rate", Value::Float(row.rate));
|
||||
value.insert("items", Value::Int(row.n_items as i64));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
)
|
||||
};
|
||||
out.insert("strengths", objective_refs(&diagnostic.strengths));
|
||||
out.insert("focus", objective_refs(&diagnostic.focus));
|
||||
|
||||
out.insert(
|
||||
"questions",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.questions
|
||||
.iter()
|
||||
.map(|question| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("number", Value::Int(question.number as i64));
|
||||
value.insert_some("position", question.position.map(|p| Value::Int(p as i64)));
|
||||
value.insert_some("level", question.level.map(|l| Value::Int(l as i64)));
|
||||
value.insert(
|
||||
"objectives",
|
||||
Value::Array(question.objectives.iter().map(|o| Value::str(o)).collect()),
|
||||
);
|
||||
value.insert_some("correct", question.correct.map(Value::Bool));
|
||||
value.insert("credit", Value::Float(question.credit));
|
||||
value.insert("bonus", Value::Bool(question.bonus));
|
||||
value.insert("blank", Value::Bool(question.blank));
|
||||
value.insert_some("class-rate", question.class_rate.map(Value::Float));
|
||||
value.insert_some(
|
||||
"feedback",
|
||||
question
|
||||
.feedback
|
||||
.as_ref()
|
||||
.map(|text| markup_value(text, content)),
|
||||
);
|
||||
value.insert(
|
||||
"taught-in",
|
||||
Value::Array(question.taught_in.iter().map(|s| Value::str(s)).collect()),
|
||||
);
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"study",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.study
|
||||
.iter()
|
||||
.map(|group| study_value(group, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out
|
||||
}
|
||||
|
||||
/// One study group as a Typst value.
|
||||
fn study_value(group: &StudyGroup, content: bool) -> Value {
|
||||
let mut out = Value::dict();
|
||||
out.insert("objective", Value::str(&group.objective));
|
||||
out.insert("text", markup_value(&group.text, content));
|
||||
out.insert("rate", Value::Float(group.rate));
|
||||
out.insert(
|
||||
"readings",
|
||||
Value::Array(
|
||||
group
|
||||
.readings
|
||||
.iter()
|
||||
.map(|reading| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("citation", Value::str(&reading.citation));
|
||||
value.insert("lecture", Value::str(&reading.lecture));
|
||||
value.insert("lecture-title", Value::str(&reading.lecture_title));
|
||||
value.insert_some("url", reading.url.as_ref().map(Value::str));
|
||||
value.insert_some(
|
||||
"focus",
|
||||
reading.focus.as_ref().map(|t| markup_value(t, content)),
|
||||
);
|
||||
value.insert_some(
|
||||
"summary",
|
||||
reading.summary.as_ref().map(|t| markup_value(t, content)),
|
||||
);
|
||||
value.insert("supplemental", Value::Bool(reading.supplemental));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
out
|
||||
}
|
||||
|
||||
/// The class diagnostic as a Typst value.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `diagnostic` - the assembled diagnostic.
|
||||
/// * `config` - the render config, for markup handling.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A dictionary the template binds as `cb-data`.
|
||||
pub fn cohort_value(diagnostic: &CohortDiagnostic, config: &RenderConfig) -> Value {
|
||||
let content = config.content.is_content();
|
||||
let mut out = Value::dict();
|
||||
|
||||
out.insert("students", Value::Int(diagnostic.n_students as i64));
|
||||
out.insert("items", Value::Int(diagnostic.n_items as i64));
|
||||
|
||||
let mut distribution = Value::dict();
|
||||
distribution.insert("mean", Value::Float(diagnostic.distribution.mean));
|
||||
distribution.insert("median", Value::Float(diagnostic.distribution.median));
|
||||
distribution.insert("sd", Value::Float(diagnostic.distribution.sd));
|
||||
distribution.insert("min", Value::Float(diagnostic.distribution.min));
|
||||
distribution.insert("max", Value::Float(diagnostic.distribution.max));
|
||||
distribution.insert(
|
||||
"bins",
|
||||
Value::Array(diagnostic.distribution.bins.iter().map(bin_value).collect()),
|
||||
);
|
||||
out.insert("distribution", distribution);
|
||||
|
||||
let mut reliability = Value::dict();
|
||||
reliability.insert_some("alpha", diagnostic.reliability.alpha.map(Value::Float));
|
||||
reliability.insert_some("sem", diagnostic.reliability.sem.map(Value::Float));
|
||||
reliability.insert("mean-p", Value::Float(diagnostic.reliability.mean_p));
|
||||
reliability.insert_some(
|
||||
"mean-point-biserial",
|
||||
diagnostic.reliability.mean_point_biserial.map(Value::Float),
|
||||
);
|
||||
reliability.insert(
|
||||
"interpretation",
|
||||
Value::str(&diagnostic.reliability.interpretation),
|
||||
);
|
||||
out.insert("reliability", reliability);
|
||||
|
||||
out.insert(
|
||||
"levels",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.levels
|
||||
.iter()
|
||||
.map(|level| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("level", Value::Int(level.level as i64));
|
||||
value.insert("name", Value::str(&level.name));
|
||||
value.insert("items", Value::Int(level.n_items as i64));
|
||||
value.insert("rate", Value::Float(level.rate));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"objectives",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.objectives
|
||||
.iter()
|
||||
.map(|o| cohort_objective_value(o, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
out.insert(
|
||||
"gaps",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.gaps
|
||||
.iter()
|
||||
.map(|o| cohort_objective_value(o, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"questions",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.questions
|
||||
.iter()
|
||||
.map(|q| cohort_question_value(q, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
out.insert(
|
||||
"revise",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.revise
|
||||
.iter()
|
||||
.map(|q| cohort_question_value(q, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"forms",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.forms
|
||||
.iter()
|
||||
.map(|form| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("id", Value::str(&form.id));
|
||||
value.insert("students", Value::Int(form.n_students as i64));
|
||||
value.insert("mean", Value::Float(form.mean));
|
||||
value.insert("sd", Value::Float(form.sd));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"blueprint",
|
||||
Value::Array(diagnostic.blueprint.iter().map(|s| Value::str(s)).collect()),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"patterns",
|
||||
Value::Array(
|
||||
diagnostic
|
||||
.patterns
|
||||
.iter()
|
||||
.map(|pattern| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("label", Value::str(&pattern.label));
|
||||
value.insert("students", Value::Int(pattern.n_students as i64));
|
||||
let mut means = Value::dict();
|
||||
for (level, mean) in &pattern.level_means {
|
||||
means.insert(format!("l{level}"), Value::Float(*mean));
|
||||
}
|
||||
value.insert("level-means", means);
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
|
||||
out.insert(
|
||||
"warnings",
|
||||
Value::Array(diagnostic.warnings.iter().map(|s| Value::str(s)).collect()),
|
||||
);
|
||||
|
||||
out
|
||||
}
|
||||
|
||||
/// One histogram bin as a Typst value.
|
||||
fn bin_value(bin: &Bin) -> Value {
|
||||
let mut value = Value::dict();
|
||||
value.insert("low", Value::Int(bin.low as i64));
|
||||
value.insert("high", Value::Int(bin.high as i64));
|
||||
value.insert("count", Value::Int(bin.count as i64));
|
||||
value
|
||||
}
|
||||
|
||||
/// One class objective row as a Typst value.
|
||||
fn cohort_objective_value(objective: &CohortObjectiveRow, content: bool) -> Value {
|
||||
let mut value = Value::dict();
|
||||
value.insert("id", Value::str(&objective.id));
|
||||
value.insert("text", markup_value(&objective.text, content));
|
||||
value.insert("items", Value::Int(objective.n_items as i64));
|
||||
value.insert("rate", Value::Float(objective.rate));
|
||||
value.insert("meeting", Value::Int(objective.meeting as i64));
|
||||
value.insert("developing", Value::Int(objective.developing as i64));
|
||||
value.insert("not-yet", Value::Int(objective.not_yet as i64));
|
||||
value.insert("thin", Value::Int(objective.thin as i64));
|
||||
value.insert("below-threshold", Value::Bool(objective.below_threshold));
|
||||
value
|
||||
}
|
||||
|
||||
/// One class question row as a Typst value.
|
||||
fn cohort_question_value(question: &CohortQuestionRow, content: bool) -> Value {
|
||||
let mut value = Value::dict();
|
||||
value.insert("number", Value::Int(question.number as i64));
|
||||
value.insert_some("item", question.item.as_ref().map(Value::str));
|
||||
value.insert_some("level", question.level.map(|l| Value::Int(l as i64)));
|
||||
value.insert(
|
||||
"objectives",
|
||||
Value::Array(question.objectives.iter().map(|o| Value::str(o)).collect()),
|
||||
);
|
||||
value.insert("p", Value::Float(question.p_value));
|
||||
value.insert_some("point-biserial", question.point_biserial.map(Value::Float));
|
||||
value.insert_some("discrimination", question.discrimination.map(Value::Float));
|
||||
value.insert("blank-rate", Value::Float(question.blank_rate));
|
||||
value.insert(
|
||||
"key",
|
||||
Value::Array(question.key.iter().map(|k| Value::str(k)).collect()),
|
||||
);
|
||||
value.insert(
|
||||
"options",
|
||||
Value::Array(
|
||||
question
|
||||
.options
|
||||
.iter()
|
||||
.map(|option| {
|
||||
let mut value = Value::dict();
|
||||
value.insert("letter", Value::str(&option.letter));
|
||||
value.insert("count", Value::Int(option.count as i64));
|
||||
value.insert("rate", Value::Float(option.rate));
|
||||
value.insert("is-key", Value::Bool(option.is_key));
|
||||
value.insert_some("point-biserial", option.point_biserial.map(Value::Float));
|
||||
value.insert("nonfunctioning", Value::Bool(option.nonfunctioning));
|
||||
value
|
||||
})
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
value.insert(
|
||||
"flags",
|
||||
Value::Array(question.flags.iter().map(|f| Value::str(f)).collect()),
|
||||
);
|
||||
value.insert(
|
||||
"notes",
|
||||
Value::Array(
|
||||
question
|
||||
.notes
|
||||
.iter()
|
||||
.map(|n| markup_value(n, content))
|
||||
.collect(),
|
||||
),
|
||||
);
|
||||
let mut by_form = Value::dict();
|
||||
for (form, p) in &question.by_form {
|
||||
by_form.insert(form.clone(), Value::Float(*p));
|
||||
}
|
||||
value.insert("by-form", by_form);
|
||||
value
|
||||
}
|
||||
|
||||
/// Emits a `#let` binding for a slot.
|
||||
fn binding(name: &str, value: &Value) -> String {
|
||||
format!("#let {name} = {}\n", value.to_typst(0))
|
||||
}
|
||||
|
||||
/// Renders one student's report.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `layout` - the course layout, for the template lookup.
|
||||
/// * `meta` - the identity block.
|
||||
/// * `diagnostic` - the student's diagnostic.
|
||||
/// * `config` - the render config for this variant.
|
||||
/// * `explicit` - a template path overriding the lookup.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The rendered document.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::Io`] when an explicit template cannot be read and
|
||||
/// [`Error::Invalid`] when a template's markers are malformed.
|
||||
pub fn render_student(
|
||||
layout: &Layout,
|
||||
meta: &Meta,
|
||||
diagnostic: &StudentDiagnostic,
|
||||
config: &RenderConfig,
|
||||
explicit: Option<&std::path::Path>,
|
||||
) -> Result<Document> {
|
||||
render(
|
||||
layout,
|
||||
Variant::StudentReport,
|
||||
&meta.assessment_id,
|
||||
meta,
|
||||
student_value(diagnostic, config),
|
||||
config,
|
||||
explicit,
|
||||
)
|
||||
}
|
||||
|
||||
/// Renders the class report.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `layout` - the course layout, for the template lookup.
|
||||
/// * `meta` - the identity block.
|
||||
/// * `diagnostic` - the class diagnostic.
|
||||
/// * `config` - the render config for this variant.
|
||||
/// * `explicit` - a template path overriding the lookup.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The rendered document.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// As [`render_student`].
|
||||
pub fn render_cohort(
|
||||
layout: &Layout,
|
||||
meta: &Meta,
|
||||
diagnostic: &CohortDiagnostic,
|
||||
config: &RenderConfig,
|
||||
explicit: Option<&std::path::Path>,
|
||||
) -> Result<Document> {
|
||||
render(
|
||||
layout,
|
||||
Variant::CohortReport,
|
||||
&meta.assessment_id,
|
||||
meta,
|
||||
cohort_value(diagnostic, config),
|
||||
config,
|
||||
explicit,
|
||||
)
|
||||
}
|
||||
|
||||
/// The shared rendering path.
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
fn render(
|
||||
layout: &Layout,
|
||||
variant: Variant,
|
||||
assessment_id: &str,
|
||||
meta: &Meta,
|
||||
data: Value,
|
||||
config: &RenderConfig,
|
||||
explicit: Option<&std::path::Path>,
|
||||
) -> Result<Document> {
|
||||
let template = template::load(layout, variant, Some(assessment_id), explicit)?;
|
||||
|
||||
let mut bodies = Vec::new();
|
||||
if template.wants(Slot::Meta) {
|
||||
bodies.push((
|
||||
Slot::Meta,
|
||||
binding(&config.meta_binding, &meta.value(config)),
|
||||
));
|
||||
}
|
||||
if template.wants(Slot::Data) {
|
||||
bodies.push((Slot::Data, binding(&config.data_binding, &data)));
|
||||
}
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
if template.is_inert() {
|
||||
warnings.push(format!(
|
||||
"the template {} declares no coursebank markers, so the report is empty; add `// \
|
||||
coursebank:data` where the body belongs",
|
||||
template.origin
|
||||
));
|
||||
} else if !template.wants(Slot::Data) {
|
||||
warnings.push(format!(
|
||||
"the template {} declares no `data` slot, so it received the metadata but not the \
|
||||
report itself",
|
||||
template.origin
|
||||
));
|
||||
}
|
||||
if template.wants(Slot::Questions) {
|
||||
return Err(Error::Invalid(vec![format!(
|
||||
"the template {} declares a `questions` slot, but a diagnostic report carries no \
|
||||
questions to fill it with. Remove the marker: a report that reproduces the exam \
|
||||
cannot be returned before a makeup is given",
|
||||
template.origin
|
||||
)]));
|
||||
}
|
||||
|
||||
Ok(Document {
|
||||
variant,
|
||||
origin: template.origin.clone(),
|
||||
slots: template.slots(),
|
||||
text: template.render(&bodies),
|
||||
warnings,
|
||||
})
|
||||
}
|
||||
|
||||
/// The file stem a student's report is written under.
|
||||
///
|
||||
/// Uses the student key rather than the name: a key is unique, filesystem-safe,
|
||||
/// and already a pseudonym when the store is pseudonymized.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `assessment_id` - the assessment id.
|
||||
/// * `student_key` - the student key.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// The stem, with no extension.
|
||||
pub fn student_stem(assessment_id: &str, student_key: &str) -> String {
|
||||
let safe: String = student_key
|
||||
.chars()
|
||||
.map(|c| {
|
||||
if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
|
||||
c
|
||||
} else {
|
||||
'-'
|
||||
}
|
||||
})
|
||||
.collect();
|
||||
format!("{assessment_id}-{safe}")
|
||||
}
|
||||
|
||||
/// Summarizes what a set of rendered reports covered, for the command line.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `written` - how many files were written.
|
||||
/// * `students` - how many students they cover.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// A sentence.
|
||||
pub fn summary(written: usize, students: usize) -> String {
|
||||
format!(
|
||||
"{written} file(s) for {students} student(s); compile them with `typst compile` or the \
|
||||
loop in the guide"
|
||||
)
|
||||
}
|
||||
|
||||
/// Tallies what a class diagnostic would tell you to do next.
|
||||
///
|
||||
/// Kept here rather than in the template so that the command line and the PDF
|
||||
/// agree about what counts as a finding.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `diagnostic` - the class diagnostic.
|
||||
///
|
||||
/// # Returns
|
||||
///
|
||||
/// Short lines, most important first.
|
||||
pub fn headline(diagnostic: &CohortDiagnostic) -> Vec<String> {
|
||||
let mut out = Vec::new();
|
||||
out.push(format!(
|
||||
"{} student(s), mean {:.0}% (SD {:.1}), median {:.0}%",
|
||||
diagnostic.n_students,
|
||||
diagnostic.distribution.mean,
|
||||
diagnostic.distribution.sd,
|
||||
diagnostic.distribution.median
|
||||
));
|
||||
if !diagnostic.gaps.is_empty() {
|
||||
out.push(format!(
|
||||
"{} objective(s) the class did not meet; worst is {} at {:.0}%",
|
||||
diagnostic.gaps.len(),
|
||||
diagnostic.gaps[0].id,
|
||||
diagnostic.gaps[0].rate * 100.0
|
||||
));
|
||||
}
|
||||
if !diagnostic.revise.is_empty() {
|
||||
let numbers: Vec<String> = diagnostic
|
||||
.revise
|
||||
.iter()
|
||||
.take(6)
|
||||
.map(|q| format!("q{}", q.number))
|
||||
.collect();
|
||||
out.push(format!(
|
||||
"{} question(s) to look at before reuse: {}",
|
||||
diagnostic.revise.len(),
|
||||
numbers.join(", ")
|
||||
));
|
||||
}
|
||||
if diagnostic.forms.len() > 1 {
|
||||
let spread = diagnostic
|
||||
.forms
|
||||
.iter()
|
||||
.map(|f| f.mean)
|
||||
.fold(f64::NEG_INFINITY, f64::max)
|
||||
- diagnostic
|
||||
.forms
|
||||
.iter()
|
||||
.map(|f| f.mean)
|
||||
.fold(f64::INFINITY, f64::min);
|
||||
out.push(format!(
|
||||
"{} forms, {:.0} points apart at the mean",
|
||||
diagnostic.forms.len(),
|
||||
spread
|
||||
));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::diagnostic::{Distribution, ReliabilityRow};
|
||||
|
||||
fn empty_cohort() -> CohortDiagnostic {
|
||||
CohortDiagnostic {
|
||||
n_students: 24,
|
||||
n_items: 36,
|
||||
distribution: Distribution {
|
||||
mean: 72.5,
|
||||
median: 74.0,
|
||||
sd: 12.0,
|
||||
min: 41.0,
|
||||
max: 97.0,
|
||||
bins: vec![Bin {
|
||||
low: 70,
|
||||
high: 80,
|
||||
count: 9,
|
||||
}],
|
||||
},
|
||||
reliability: ReliabilityRow {
|
||||
alpha: Some(0.71),
|
||||
sem: Some(2.1),
|
||||
mean_p: 0.72,
|
||||
mean_point_biserial: Some(0.24),
|
||||
interpretation: "acceptable for a classroom exam".into(),
|
||||
},
|
||||
levels: Vec::new(),
|
||||
objectives: Vec::new(),
|
||||
gaps: Vec::new(),
|
||||
questions: Vec::new(),
|
||||
revise: Vec::new(),
|
||||
forms: Vec::new(),
|
||||
blueprint: Vec::new(),
|
||||
patterns: Vec::new(),
|
||||
warnings: Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_headline_leads_with_the_distribution() {
|
||||
let lines = headline(&empty_cohort());
|
||||
assert!(lines[0].contains("24 student(s)"), "{lines:?}");
|
||||
assert!(
|
||||
lines[0].contains("73%") || lines[0].contains("72%"),
|
||||
"{lines:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_student_stem_is_filesystem_safe() {
|
||||
assert_eq!(student_stem("e1", "s-9f8e7d"), "e1-s-9f8e7d");
|
||||
assert_eq!(student_stem("e1", "ada@x.edu"), "e1-ada-x-edu");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_cohort_value_carries_no_question_text() {
|
||||
let config = RenderConfig::for_variant(Variant::CohortReport);
|
||||
let text = cohort_value(&empty_cohort(), &config).to_typst(0);
|
||||
assert!(text.contains("reliability"));
|
||||
assert!(!text.contains("stem"));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user