246 lines
15 KiB
Markdown
246 lines
15 KiB
Markdown
# Terms, equations, values, and misconceptions
|
|
|
|
Schema 2.1 gives a course four registries beside its objectives and targets: the terms students meet, the equations they use, the numbers they are taught, and the mistakes they commonly make.
|
|
Each entry is defined once, keyed by id, and a target lists the entries it turns on.
|
|
The lecture page, the course glossary page, and student reports are built from those lists, so a definition you correct in one place is corrected everywhere it is shown.
|
|
|
|
A 2.0 course needs none of this and loads unchanged.
|
|
|
|
## The four registries
|
|
|
|
| Registry | Id prefix | One entry is |
|
|
|:--|:--|:--|
|
|
| `terms` | `term-` | a word or phrase, its one-sentence definition, and what the assigned texts call it |
|
|
| `equations` | `eq-` | a relation in LaTeX, what it says in words, its symbols, and what it implies |
|
|
| `values` | `val-` | a number as taught, the one wording every material uses for it, and its source |
|
|
| `misconceptions` | `mis-` | a belief students hold, in their voice, and its correction |
|
|
|
|
After the prefix, an id is lowercase words joined by hyphens, like every other id in the course.
|
|
Ids are unique across all six registries, objectives and targets included, so `{term-gap}` can only ever mean one thing.
|
|
Ids are also join keys: renaming one orphans every target, option, and brace reference that names it.
|
|
|
|
A term:
|
|
|
|
```yaml
|
|
terms:
|
|
term-gap-penalty:
|
|
term: gap penalty
|
|
symbol: 'd'
|
|
definition: 'The score subtracted for each position where one sequence is aligned against a {term-gap}.'
|
|
term-decade:
|
|
term: decade
|
|
definition: 'A factor of ten in a concentration ratio or an equilibrium constant.'
|
|
kind: coined
|
|
textbook:
|
|
- { term: order of magnitude, ref: KKW, locator: '§10.10' }
|
|
variants: [decades]
|
|
exam_wording: ten-fold
|
|
```
|
|
|
|
`kind` says whether a student can look the term up under this name: `standard` (the default), `renamed` (the course uses its own name for a standard idea), or `coined`.
|
|
A renamed or coined term should give the `textbook` name, and a coined one the `exam_wording` that items write instead of the label, because an exam should not test vocabulary only your lectures use.
|
|
|
|
An equation, a value, and a misconception:
|
|
|
|
```yaml
|
|
equations:
|
|
eq-global-recurrence:
|
|
name: the global alignment recurrence
|
|
tex: 'F(i,j) = \max\begin{cases} F(i-1,j-1) + s(x_i, y_j) \\ F(i-1,j) - d \\ F(i,j-1) - d \end{cases}'
|
|
says: >-
|
|
The best score for the first i letters of one sequence against the first j of the other is the best of
|
|
three moves into that cell.
|
|
symbols:
|
|
- { symbol: 'F(i,j)', meaning: 'the best score for aligning the two prefixes' }
|
|
- { symbol: 'd', term: term-gap-penalty }
|
|
implications:
|
|
- { form: direction, statement: 'Raising {term-gap-penalty} makes the diagonal win more cells.' }
|
|
assumes: ['Each gap position costs the same, whatever its neighbors.']
|
|
fails_when: ['Gaps come in long runs, which a linear penalty charges too much for.']
|
|
recall: true
|
|
|
|
values:
|
|
val-per-decade:
|
|
name: free energy per ten-fold concentration ratio at 37 °C
|
|
value: 6
|
|
units: kJ/mol
|
|
say: about 6 kJ/mol
|
|
exact: 5.9
|
|
source: { ref: KKW, locator: '§10.10' }
|
|
conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
|
|
recall: true
|
|
|
|
misconceptions:
|
|
mis-only-matches-count:
|
|
belief: 'An alignment score counts the matching positions, so the alignment with the most matches scores highest.'
|
|
correction: 'Every column counts: matches add, mismatches cost a little, and gaps cost more.'
|
|
```
|
|
|
|
An equation's `implications` are the things a question can ask about a relation without evaluating it, each in one of six forms: `direction`, `limit`, `scale`, `dominant_term`, `held_fixed`, or `misuse`.
|
|
A value's `say` is the wording the lecture page, slides, and items all use, and its `conflicts` are regular expressions for the wordings that must not appear anywhere students read.
|
|
`recall: true` means students are expected to know the value, so no item may print it.
|
|
|
|
Any entry may carry `status: proposed`, which a pipeline sets when it adds one; delete the line to approve it.
|
|
Proposed entries are checked like any other, and `coursebank lint` counts how many are waiting.
|
|
|
|
## Where entries live
|
|
|
|
An entry can be defined in three places:
|
|
|
|
| File | What goes there |
|
|
|:--|:--|
|
|
| `objectives/*.yaml` | the entries an objective's targets are the first in the course to need |
|
|
| `glossary.yaml` | cross-cutting entries, and whatever `migrate glossary` brought in, until each one is moved |
|
|
| `course.yaml` | anything, for a course that keeps everything in one file |
|
|
|
|
Lecture files and `references.yaml` cannot define entries.
|
|
Wherever an entry is defined, it is course-wide: a target in any later lecture lists it by id, and nothing redefines it.
|
|
The convention is the objective file whose targets first need the entry, and `lint` notes an entry that sits elsewhere (`glossary-defined-elsewhere`), without failing.
|
|
|
|
## Targets point at entries
|
|
|
|
A target lists the entries it turns on, and says in one student-facing paragraph what meeting it looks like:
|
|
|
|
```yaml
|
|
learning_targets:
|
|
t-align-gap-penalty-effect:
|
|
text: 'Predict how raising the gap penalty changes the optimal path through the matrix.'
|
|
objective: lo-alignment-recurrence
|
|
level_ceiling: 3
|
|
explanation: >-
|
|
A larger {term-gap-penalty} makes every horizontal or vertical step cost more, so the diagonal wins more
|
|
cells and the optimal path uses fewer gaps.
|
|
terms: [term-gap-penalty]
|
|
equations: [eq-global-recurrence]
|
|
misconceptions: [mis-only-matches-count]
|
|
authoring:
|
|
ceiling_item: 'Show the optimal path under d = 1 and ask which path wins under d = 4.'
|
|
supplied: ['the two sequences', 'the optimal path under the lower penalty']
|
|
relation_form: direction
|
|
```
|
|
|
|
The lists are what a lecture page draws its glossary sections from, and what decides each entry's first lecture: the first lecture, in teaching order, with a target that lists it.
|
|
Teaching order is the course's own: lectures in id order, objectives in each lecture's `teaches` order, and an objective's targets by ceiling and then id.
|
|
A term first needed in an earlier lecture appears on a later lecture's page as a link back, not as a new definition.
|
|
|
|
`authoring` holds the item-writing judgments that settle what a question at the target's ceiling looks like: `ceiling_item`, `supplied` data, `constraints`, `number_work`, `examples`, `relation_form`, and the evidence for the ceiling.
|
|
It is for the item pipelines and for you; students never see it.
|
|
|
|
## Other fields 2.1 adds
|
|
|
|
| On | Field | What it does |
|
|
|:--|:--|:--|
|
|
| objective | `description` | a short student-facing paragraph under the objective on the lecture page |
|
|
| lecture | `description` | the paragraph that opens the lecture page |
|
|
| lecture | `materials` | slides, briefs, notebooks, and other links, each `{kind, url, title}` |
|
|
| reading | `minutes` | the reading's length, summed at the top of the readings section |
|
|
| bank option | `misconception_id` | the registry misconception the distractor encodes |
|
|
| policy | `exam_conditions` | closed book or not, calculator, how equations are given, formats, seconds per item |
|
|
| policy | `blueprints` | named level counts, bonus counts, and minutes |
|
|
| policy | `levels` | the course's names for levels 1 to 5, used to label ceilings on the lecture page |
|
|
| policy | `target_text_forbid` | regular expressions that objective and target text must not match |
|
|
|
|
An option's own `misconception` text, when it has one, still wins for that item.
|
|
An option with only a `misconception_id` counts as designed, and its feedback is the registry's correction.
|
|
`exam_conditions` and `blueprints` are stored and validated, but no command reads them yet.
|
|
|
|
## Brace references
|
|
|
|
Student-facing prose can name an entry in braces, and every page that shows the prose renders the reference:
|
|
|
|
| Reference | Renders as |
|
|
|:--|:--|
|
|
| `{term-gap-penalty}` | the term, linked to its definition |
|
|
| `{eq-global-recurrence}` | the equation's name, linked to it |
|
|
| `{val-per-decade}` | the value's `say`, such as about 6 kJ/mol |
|
|
| `{mis-only-matches-count}` | the belief, in quotation marks |
|
|
| `{t-align-fill-matrix}` | `T 3`, the target's number on the page, or the target's text where it has no number |
|
|
| `{lo-alignment-recurrence}` | the objective's text |
|
|
|
|
On a Quarto lecture page, a link points at the definition on the same page when it is there (a term new in that lecture, or an equation its targets use).
|
|
Every other link points at the course glossary page: `glossary.html`, unless `--glossary-href` says otherwise.
|
|
Braces that are not a prefixed id, such as `10^{59}` or `\text{final}`, are left alone.
|
|
|
|
The fields that take references are the student-facing ones: definitions, `says`, implication statements, `assumes`, `fails_when`, corrections, objective and lecture descriptions, target explanations, and a reading's `summary`, `focus`, and `skip`.
|
|
|
|
## What students never see
|
|
|
|
`authoring`, `notes_private`, `evidence`, `conflicts`, and `status` are instructor-facing.
|
|
No lecture page, glossary page, student report, or student export (Canvas, the practice worksheet and its solutions, the site) prints them, and a test renders the example course through every one of those and checks.
|
|
A proposed entry is shown to students like an approved one, without saying it is proposed.
|
|
|
|
## Pages
|
|
|
|
```console
|
|
$ coursebank lecture page l09 --out site/l09.qmd
|
|
$ coursebank lecture glossary --out site/glossary.qmd
|
|
```
|
|
|
|
`lecture page` writes, in order: the lecture's description; each objective with its description and its targets, each with its explanation and its ceiling named by `policy.levels`; the new terms; earlier terms, linked; the equations; the numbers to know; common mistakes; readings, with minutes; and materials.
|
|
A lecture's pages show what it teaches, not what it builds on: an objective or target already covered in an earlier lecture is left off, even when it names this lecture in `lectures:`, unless the lecture lists its objective in `teaches`.
|
|
`lecture glossary` lists every term alphabetically with its definition and first lecture, then every equation and value.
|
|
Both write Quarto Markdown by default (numbered targets as `(@)` example lists, anchors as `{#glossary-term-...}`), or plain Markdown with `--style plain`.
|
|
|
|
Student reports gain two things.
|
|
Each missed target shows what meeting it looks like, from its `explanation`.
|
|
A chosen option with a `misconception_id` shows the misconception and its correction, and misses that share one across questions are grouped under it, so a student who made the same mistake three times reads about it once.
|
|
|
|
## Checks
|
|
|
|
`coursebank validate` reports these as errors, each prefixed with the file that defines the entry:
|
|
|
|
| Problem | Message |
|
|
|:--|:--|
|
|
| an id lacks its registry's prefix | ``term `x`: a term id is `term-` followed by lowercase words`` |
|
|
| an id is in two registries, or two files | `` `x` is declared as both a ``, or `is defined in two places` |
|
|
| a target lists an undeclared entry | ``target `t`: `terms` names `x`, which is not a declared term`` |
|
|
| an equation symbol names an undeclared term, or has neither `term` nor `meaning` | ``equation `eq-x`: symbol `d` `` |
|
|
| a value has neither `value` nor `range`, its range runs backwards, or its `term` is undeclared | ``value `val-x`: `` |
|
|
| a `source`, `textbook`, or `evidence` cites a key not in `references` | ``…: source cites `KEY`, which is not in references`` |
|
|
| a brace reference does not resolve | ``…: description refers to `{term-x}`, which is not a declared term`` |
|
|
| a `conflicts` or `target_text_forbid` pattern does not compile | ``value `val-x`: conflicts pattern `…` does not compile`` |
|
|
| an option's `misconception_id` is undeclared | ``option o-x: misconception_id `mis-x` is not a declared misconception`` |
|
|
|
|
An unresolved `{lo-...}` or `{t-...}` in a reading's `summary`, `focus`, or `skip` stays a lint warning (`glossary-unresolved-reference`) rather than an error, because 2.0 accepted it.
|
|
|
|
`coursebank lint` adds fourteen rules in a `glossary` family:
|
|
|
|
| Code | Severity | Flags |
|
|
|:--|:--|:--|
|
|
| `glossary-unused` | low | an entry no target, equation symbol, value, or option needs |
|
|
| `glossary-no-textbook-name` | medium | a renamed or coined term with no textbook name |
|
|
| `glossary-no-exam-wording` | low | a coined term with no `exam_wording` |
|
|
| `glossary-circular-definition` | low | a definition that uses the term it defines |
|
|
| `glossary-coined-in-item` | medium | a coined term in an item's stem or options |
|
|
| `glossary-value-unsourced` | low | a value with no `source` |
|
|
| `glossary-value-conflict` | medium | a `conflicts` pattern that matches student-facing text or an item |
|
|
| `glossary-forbidden-target-wording` | medium | objective or target text that matches `target_text_forbid` |
|
|
| `glossary-unlisted-term` | low | an explanation that names a term its target neither lists nor inherits from a prerequisite |
|
|
| `glossary-recall-value-printed` | medium | an item that prints a `recall: true` value |
|
|
| `glossary-equation-no-implications` | low | a target at ceiling 3 or above that turns on an equation with no implications |
|
|
| `glossary-unresolved-reference` | medium | an old prose field that refers to an undeclared objective or target |
|
|
| `glossary-defined-elsewhere` | note | an entry outside the objective file whose targets first need it |
|
|
| `glossary-proposed` | note | how many entries are waiting for approval |
|
|
|
|
A note is shown by default and never makes `lint` fail, so a course with proposed entries still passes a lint gate.
|
|
`--min-severity low` hides notes.
|
|
|
|
Regular expressions use Rust's `regex` syntax, which has no look-around and no backreferences.
|
|
`target_text_forbid` matches case-insensitively; `conflicts` matches as written.
|
|
|
|
## From `terms.yaml` and `values.yaml`
|
|
|
|
A course that kept its terms and numbers in 1.0 side files brings them in with one command:
|
|
|
|
```console
|
|
$ coursebank migrate glossary --terms terms.yaml --values values.yaml --dry-run
|
|
$ coursebank migrate glossary --terms terms.yaml --values values.yaml
|
|
```
|
|
|
|
Ids gain their prefix (`decade` becomes `term-decade`), `course` becomes `term`, `meaning` becomes `definition`, and a value's `term:` gains the prefix of the id it names.
|
|
`first` and `lectures` are dropped, because 2.1 derives them from the targets that list an entry; the command reports each one that disagrees with what the targets now say, each entry no target lists yet, and each field 2.1 has no place for.
|
|
The entries go into `glossary.yaml`, added at the end of its sections if it exists, with comments and quoting copied from the old files.
|
|
The old files are left alone, and an entry the course already declares is skipped, so a second run changes nothing.
|
|
|
|
Linking targets to the migrated entries, and moving each entry into the objective file that first needs it, is then yours or a pipeline's to do; `lint` lists what is left (`glossary-unused`, `glossary-defined-elsewhere`).
|