feat(schema): 2.1 types, fragments, and JSON Schemas

Add the term, equation, value, and misconception registries
(src/model/course/glossary.rs) and the new optional fields on objectives,
targets, lectures, readings, bank options, and policy. Load registry
entries from objective files, glossary.yaml, and course.yaml, with one
definition site per id as for every other registry. Port every edit in
docs/design/2.1/build_schemas.py into the hand-written schema builders,
add glossary.schema.json, and test the generated schemas against the
targets; the only differences are two 2.0 spellings the code already had.

The 2.0 example fragments load and validate unchanged. The 2.1 example
bank gains `status: draft`, which every coursebank item requires.
tests/docs.rs skips docs/design/, which holds design records rather than
guide pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-11-16 11:55:18 -05:00
1 parent 15175f64fd
commit 51a2fd235f
47 files changed
+10568 -55

No files matched your search

@@ -0,0 +1,16 @@
# banks/alignment.yaml (coursebank 2.1): one option names the registry misconception it encodes
bank: { id: alignment, title: Alignment }
items:
- id: q-align-which-scores-higher
status: draft # coursebank requires a status on every item; an approved one also needs cognitive_process, sources, and design
level: 2
stem: 'Two alignments of the same pair have the same number of matching columns. Why can their scores differ?'
learning_targets: [t-align-score-columns]
options:
- { id: o-columns-all-count, text: 'Mismatches and gaps also add to the score, so the other columns differ.', correct: true }
- id: o-matches-only
text: 'They cannot differ; the score counts matching columns.'
misconception_id: mis-only-matches-count
error_type: incomplete_understanding
- { id: o-length, text: 'The longer alignment always scores lower.', misconception: 'students pick this when they think length alone is penalized' }
- { id: o-order, text: 'The score depends on which sequence is written on top.', error_type: plausible_irrelevant, misconception: 'students pick this when they confuse the matrix layout with the score' }
+28
View File
@@ -0,0 +1,28 @@
# course.yaml (coursebank 2.1): identity, policy, and units; the new policy blocks shown in full
schema_version: '2.1'
course:
code: BIOSC 1540
title: Computational Biology
term: 2027s
policy:
options_per_item: 4
min_items_for_mastery: 2
mastery_threshold: 0.75
exam_conditions:
closed_book: true
calculator: false
equations: never_printed
formats: [single_best_answer]
seconds_per_item: 120
blueprints:
module: { level_counts: { '1': 6, '2': 18, '3': 9, '4': 3 }, bonus_counts: { '5': 1 }, minutes: 75 }
final: { level_counts: { '1': 8, '2': 24, '3': 12, '4': 4 }, bonus_counts: { '5': 1 }, minutes: 110 }
levels:
'1': { name: Definitions, description: 'Match a term to its name or definition.' }
'2': { name: Concepts, description: 'Explain how something works, as it normally is.' }
'3': { name: Application, description: 'Change one thing and follow it to the result.' }
'4': { name: Analytical, description: 'Weigh several interacting conditions at once.' }
'5': { name: Synthesis, description: 'Extend to an unseen case, or judge competing explanations.' }
target_text_forbid: ['\bcomput', '\bcalculat', '\bestimat'] # calculator-free exams: no text may promise a calculation
units:
- { id: u1, title: Sequences and alignment }
@@ -0,0 +1,26 @@
# glossary.yaml (coursebank 2.1)
# Entries brought in by `coursebank migrate glossary --terms terms.yaml --values values.yaml`, waiting to be moved to
# the objective file whose targets first need them, plus anything genuinely cross-cutting.
terms:
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' }
- { term: ten-fold }
variants: [decades]
exam_wording: ten-fold
status: proposed
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
term: term-decade
source: { ref: KKW, locator: '§10.10' }
conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
recall: true
status: proposed
@@ -0,0 +1,73 @@
<!-- What prototype/check21.py derives for l09: the content and order the 2.1 lecture page should show. Layout is the renderer's. -->
# l09: Pairwise alignment
How alike are two sequences? This lecture scores one alignment column by column, shows that there are far too many alignments to score one at a time (about 10^{59} for two 100-letter sequences), and builds the table that finds the best one anyway. It ends on when to align end to end and when to look for a shared region.
## Account for how an alignment is scored, and choose a scoring scheme and gap penalty suited to a given pair of sequences.
Before anything can find the best alignment, "best" needs a number. This objective is that number: a score added up column by column, where the [gap penalty] and the [substitution score] decide what a good alignment looks like.
- **Define the alignment matrix, the scoring scheme, and the gap penalty, and identify each on a filled matrix.** (Definitions)
The [alignment matrix] puts one sequence along the top and the other down the side. The scoring scheme gives a [substitution score] to every pair of letters and a [gap penalty] to every gap.
- **Explain why two alignments of one pair with the same number of matches can score differently under one scheme.** (Concepts)
An alignment's score is the sum over its columns. Matches add, mismatches cost a little and gaps cost more, so alignments with equal matches differ in what their other columns cost.
## Use the dynamic-programming recurrence to produce an optimal alignment, and predict how the result moves when the scoring changes.
Two short sequences already have more alignments than anyone could score one at a time. The recurrence finds the best one anyway, by scoring every pair of prefixes once and reusing those scores ([the global alignment recurrence]). This objective is the method the rest of the unit builds on: database search in the next lecture is this table with most of its cells skipped.
- **Given a match, mismatch, and gap scheme and two short sequences, determine the optimal global alignment score by filling the matrix from the recurrence, and read the alignment off the traceback.** (Application)
Each cell holds the best score for aligning the two prefixes that end there, and it is the best of three offers: the diagonal neighbour plus the score of pairing the two letters, or either other neighbour minus the [gap penalty]. The first row and column are all gaps. The bottom-right cell is the optimal score, and following each cell back to the neighbour that won it gives the alignment ([traceback]).
- **Predict how raising the gap penalty changes the optimal path through the matrix.** (Application)
A larger [gap penalty] makes every horizontal or vertical step cost more, so the diagonal wins more cells and the optimal path uses fewer gaps, accepting mismatches it would have avoided before.
- **Given two sequences that share one conserved region, and the global and local optimal alignments of them, determine which alignment answers whether the region is shared and which assumption the other one violates.** (Analytical)
Global alignment assumes the sequences are related end to end, so it pays for every unrelated flank and can bury a shared region under gap and mismatch costs. Local alignment drops that assumption: any cell may restart at zero, so the best region is found wherever it sits.
## New terms
- **alignment matrix**: A table with one sequence along the top and the other down the side, where each cell holds the best score for aligning the two prefixes that end there. (textbooks: dynamic programming matrix)
- **gap**: A position where one sequence has a letter and the other has a dash.
- **gap penalty** $d$: The score subtracted for each position where one sequence is aligned against a [gap].
- **substitution score** $s(a,b)$: The score for pairing two letters in one column: positive for pairs that are often swapped in related sequences, negative for pairs that rarely are.
- **traceback**: Following each cell of a filled alignment matrix back to the neighbour that gave it its score, from the last cell to the first, to read off the alignment.
- **global alignment**: An alignment of two sequences from end to end, every letter of both included.
- **local alignment**: The best-scoring alignment of any part of one sequence with any part of the other.
## Equations
### the global alignment recurrence
$$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}$$
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: pair the two last letters, or put a gap against one of them.
- F(i,j): the best score for aligning the first i letters of x with the first j letters of y
- s(x_i, y_j): substitution score
- d: gap penalty
- What it tells you (direction): Raising [gap penalty] makes the diagonal win more cells, so optimal alignments use fewer gaps.
- What it tells you (held fixed): Two optimal scores can be compared only under the same scoring scheme; the scheme sets the scale.
- What it tells you (misuse): A high global score does not show that any one region is shared: unrelated flanks lower it and a strong region can hide in it.
- Assumes: Each gap position costs the same, whatever its neighbours.
- Assumes: A column's score depends only on the two letters in it.
- Assumes: Both sequences are related from end to end.
- Fails when: Gaps come in long runs, which a linear penalty charges too much for; an affine penalty fits better.
- Fails when: The sequences share only a region, which global alignment can bury; local alignment finds it.
## Numbers to know
- number of global alignments of two 100-letter sequences: about 10^{59}
## Common mistakes
- *An alignment score counts the matching positions, so the alignment with the most matches scores highest.* Every column counts: matches add, mismatches cost a little, and gaps cost more, so two alignments with the same matches can score differently.
- *A local alignment is the global alignment with its unmatched ends trimmed off.* Local alignment changes the recurrence: any cell can restart at zero, so its best region can sit where the global path never passes.
## Readings
- Durbin ch. 2 (40 min): Fill one small matrix by hand and follow the traceback (T t-align-fill-matrix). Watch what changes at the matrix boundaries and where the traceback starts; that is the whole global-versus-local distinction.
## Materials
- slides: https://example.edu/slides/l09
- Lecture brief: https://example.edu/briefs/l09
- Fill a matrix in Python: https://example.edu/notebooks/l09.ipynb
@@ -0,0 +1,28 @@
# lectures/l09.yaml (coursebank 2.1)
lectures:
l09:
title: Pairwise alignment
unit: u1
description: >-
How alike are two sequences? This lecture scores one alignment column by column, shows that there are far too
many alignments to score one at a time ({val-alignment-count-100} for two 100-letter sequences), and builds the
table that finds the best one anyway. It ends on when to align end to end and when to look for a shared region.
teaches:
- lo-alignment-scoring
- lo-alignment-recurrence
materials:
- { kind: slides, url: 'https://example.edu/slides/l09' }
- { kind: brief, title: 'Lecture brief', url: 'https://example.edu/briefs/l09' }
- { kind: notebook, title: 'Fill a matrix in Python', url: 'https://example.edu/notebooks/l09.ipynb' }
readings:
- ref: durbin1998biological
locator: 'ch. 2'
minutes: 40
targets: [t-align-matrix-terms, t-align-score-columns, t-align-fill-matrix, t-align-local-vs-global-diagnose]
summary: >-
Introduces the alignment matrix and {eq-global-recurrence}, then contrasts the global and local fills.
focus: >-
Fill one small matrix by hand and follow the traceback ({t-align-fill-matrix}). Watch what changes at the
matrix boundaries and where the traceback starts; that is the whole global-versus-local distinction.
skip: >-
Gloss the affine-gap extension. It comes in a later lecture.
@@ -0,0 +1,129 @@
# objectives/lo-alignment-recurrence.yaml (coursebank 2.1)
#
# One objective, its targets, and the glossary entries its targets are the first to need. The terms, equation,
# value, and misconceptions defined here are course-wide: any later target lists them by id, and nothing redefines them.
# Fields marked student-facing render on the lecture page; `authoring` and `notes_private` never do.
learning_objectives:
lo-alignment-recurrence:
text: 'Use the dynamic-programming recurrence to produce an optimal alignment, and predict how the result moves when the scoring changes.'
description: >-
Two short sequences already have more alignments than anyone could score one at a time. The recurrence finds the
best one anyway, by scoring every pair of prefixes once and reusing those scores ({eq-global-recurrence}). This
objective is the method the rest of the unit builds on: database search in the next lecture is this table with
most of its cells skipped.
unit: u1
level_ceiling: 4
prerequisites: [lo-alignment-scoring]
tags: [alignment, algorithms]
learning_targets:
t-align-fill-matrix:
text: 'Given a match, mismatch, and gap scheme and two short sequences, determine the optimal global alignment score by filling the matrix from the recurrence, and read the alignment off the traceback.'
objective: lo-alignment-recurrence
level_ceiling: 3
prerequisites: [t-align-matrix-terms]
tags: [alignment, algorithms]
explanation: >-
Each cell holds the best score for aligning the two prefixes that end there, and it is the best of three
offers: the diagonal neighbour plus the score of pairing the two letters, or either other neighbour minus the
{term-gap-penalty}. The first row and column are all gaps. The bottom-right cell is the optimal score, and
following each cell back to the neighbour that won it gives the alignment ({term-traceback}).
terms: [term-alignment-matrix, term-gap-penalty, term-substitution-score, term-traceback]
equations: [eq-global-recurrence]
values: [val-alignment-count-100]
misconceptions: [mis-only-matches-count]
authoring:
ceiling_item: 'Supply a 3 by 3 matrix with all but the last cell filled and ask for the last cell and the traceback it starts.'
supplied: ['the scoring scheme', 'the two sequences', 'all but one or two cells of the matrix']
constraints: ['keep each sequence to four letters or fewer, or supply a partly filled matrix: a full 5 by 5 fill runs past the two-minute budget']
number_work: 'one addition and a three-way comparison per cell, a few seconds each'
examples: ['the two short globin fragments in the lecture worked example']
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
prerequisites: [t-align-fill-matrix]
tags: [alignment]
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, accepting mismatches it would have avoided before.
terms: [term-gap-penalty]
equations: [eq-global-recurrence]
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
t-align-local-vs-global-diagnose:
text: 'Given two sequences that share one conserved region, and the global and local optimal alignments of them, determine which alignment answers whether the region is shared and which assumption the other one violates.'
objective: lo-alignment-recurrence
level_ceiling: 4
prerequisites: [t-align-fill-matrix]
tags: [alignment]
explanation: >-
Global alignment assumes the sequences are related end to end, so it pays for every unrelated flank and can bury a
shared region under gap and mismatch costs. Local alignment drops that assumption: any cell may restart at zero,
so the best region is found wherever it sits.
terms: [term-global-alignment, term-local-alignment]
equations: [eq-global-recurrence]
misconceptions: [mis-local-is-trimmed-global]
authoring:
ceiling_item: 'Give both alignments and their scores, and ask which supports the claim that the region is shared and why the other misleads.'
supplied: ['both sequences', 'both optimal alignments with their scores']
relation_form: misuse
terms:
term-traceback:
term: traceback
definition: 'Following each cell of a filled alignment matrix back to the neighbour that gave it its score, from the last cell to the first, to read off the alignment.'
term-global-alignment:
term: global alignment
definition: 'An alignment of two sequences from end to end, every letter of both included.'
term-local-alignment:
term: local alignment
definition: 'The best-scoring alignment of any part of one sequence with any part of the other.'
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: pair the two last letters, or put a gap against one of them.
symbols:
- { symbol: 'F(i,j)', meaning: 'the best score for aligning the first i letters of x with the first j letters of y' }
- { symbol: 's(x_i, y_j)', term: term-substitution-score }
- { symbol: 'd', term: term-gap-penalty }
implications:
- { form: direction, statement: 'Raising {term-gap-penalty} makes the diagonal win more cells, so optimal alignments use fewer gaps.' }
- { form: held_fixed, statement: 'Two optimal scores can be compared only under the same scoring scheme; the scheme sets the scale.' }
- { form: misuse, statement: 'A high global score does not show that any one region is shared: unrelated flanks lower it and a strong region can hide in it.' }
assumes:
- 'Each gap position costs the same, whatever its neighbours.'
- 'A column''s score depends only on the two letters in it.'
- 'Both sequences are related from end to end.'
fails_when:
- 'Gaps come in long runs, which a linear penalty charges too much for; an affine penalty fits better.'
- 'The sequences share only a region, which global alignment can bury; local alignment finds it.'
recall: true
source: { ref: durbin1998biological, locator: 'ch. 2' }
values:
val-alignment-count-100:
name: number of global alignments of two 100-letter sequences
value: 1.0e+59
say: 'about 10^{59}'
exact: 9.05e+58
source: { ref: durbin1998biological, locator: 'ch. 2' }
conflicts: ['10\^\{?100\}?\s*alignments']
recall: false
misconceptions:
mis-local-is-trimmed-global:
belief: 'A local alignment is the global alignment with its unmatched ends trimmed off.'
correction: 'Local alignment changes the recurrence: any cell can restart at zero, so its best region can sit where the global path never passes.'
error_type: misconception
evidence:
- { kind: instructor, detail: 'Asked in office hours most terms.' }
@@ -0,0 +1,66 @@
# objectives/lo-alignment-scoring.yaml (coursebank 2.1)
# The first objective l09 teaches. Its targets are the first to need gaps, the gap penalty, substitution scores, and the
# "only matches count" mistake, so those entries are defined here; the recurrence objective lists them by id.
learning_objectives:
lo-alignment-scoring:
text: 'Account for how an alignment is scored, and choose a scoring scheme and gap penalty suited to a given pair of sequences.'
description: >-
Before anything can find the best alignment, "best" needs a number. This objective is that number: a score added
up column by column, where the {term-gap-penalty} and the {term-substitution-score} decide what a good alignment
looks like.
unit: u1
level_ceiling: 2
tags: [alignment]
learning_targets:
t-align-matrix-terms:
text: 'Define the alignment matrix, the scoring scheme, and the gap penalty, and identify each on a filled matrix.'
objective: lo-alignment-scoring
level_ceiling: 1
tags: [alignment]
explanation: >-
The {term-alignment-matrix} puts one sequence along the top and the other down the side. The scoring scheme gives a
{term-substitution-score} to every pair of letters and a {term-gap-penalty} to every gap.
terms: [term-alignment-matrix, term-gap, term-gap-penalty, term-substitution-score]
t-align-score-columns:
text: 'Explain why two alignments of one pair with the same number of matches can score differently under one scheme.'
objective: lo-alignment-scoring
level_ceiling: 2
prerequisites: [t-align-matrix-terms]
tags: [alignment]
explanation: >-
An alignment's score is the sum over its columns. Matches add, mismatches cost a little and gaps cost more, so
alignments with equal matches differ in what their other columns cost.
terms: [term-gap, term-gap-penalty, term-substitution-score]
misconceptions: [mis-only-matches-count]
terms:
term-alignment-matrix:
term: alignment matrix
definition: 'A table with one sequence along the top and the other down the side, where each cell holds the best score for aligning the two prefixes that end there.'
kind: renamed
textbook:
- { term: dynamic programming matrix, ref: durbin1998biological, locator: 'ch. 2' }
variants: [alignment matrices]
term-gap:
term: gap
definition: 'A position where one sequence has a letter and the other has a dash.'
variants: [gaps]
term-gap-penalty:
term: gap penalty
definition: 'The score subtracted for each position where one sequence is aligned against a {term-gap}.'
symbol: '$d$'
variants: [gap penalties]
term-substitution-score:
term: substitution score
definition: 'The score for pairing two letters in one column: positive for pairs that are often swapped in related sequences, negative for pairs that rarely are.'
symbol: '$s(a,b)$'
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, so two alignments with the same matches can score differently.'
error_type: incomplete_understanding
evidence:
- { kind: persona, detail: 'Incoming-student probe: scored by identity alone.' }
@@ -0,0 +1,17 @@
references:
durbin1998biological:
label: Durbin
kind: book
role: required
title: 'Biological Sequence Analysis: Probabilistic Models of Proteins and Nucleic Acids'
authors: ['Durbin, Richard', 'Eddy, Sean R.', 'Krogh, Anders', 'Mitchison, Graeme']
year: 1998
publisher: Cambridge University Press
KKW:
label: KKW
kind: book
role: required
title: 'The Molecules of Life: Physical and Chemical Principles'
authors: ['Kuriyan, John', 'Konforti, Boyana', 'Wemmer, David']
year: 2013
publisher: Garland Science