Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,56 @@ All notable changes to GenAIRR are documented here.

### Changed

- **`DETERMINISM_VERSION` is now 4.** Affinity selection scores the protein the
cell actually expresses. Seed-moving wherever selection is active;
`selection_strength=0` runs with no target are unaffected.

The cell's amino acids came from concatenating a per-region translation, and a
codon was kept only if it fitted wholly inside one region. Every region
boundary in a rearrangement is a junction boundary, so the residues selection
could not see were exactly the ones it exists to select on: measured over 200
`human_igh` records, 2.68 codons dropped per record (range 0 to 4) and **536
of 536 of them straddling V/NP1, NP1/D, D/NP2 or NP2/J**. The frame did not
restart, so every scored codon was real - the dropped ones simply vanished and
shifted every amino-acid position after them left. For one record the scored
protein began `VYYCARGYCSSTSC` where the real one is `VYYCARDRGYCSSTSC*KK`:
the loss starts at the conserved CDR3 anchor.

Measured through the public API: a cell grown with `rate=0`, and therefore
identical to its founder, scored against the founder's own protein reported
an affinity of **3.57e-67 instead of 1.0**. The model could not recognise a
cell as identical to itself.

Both paths now translate the coding span continuously, in the frame resolved
from the V allele's native reference phase - the same protein a record reports
as `sequence_aa`. Because the frame comes from the reference, an affinity
model now travels with its reference data, and `simulate_lineage` requires
`refdata` when selection is active.

- **A stop codon no longer scores as a perfect match.** `substitution_cost` is
`S(a,a) - S(a,b)`, and for a stop or an unresolved `X` both terms fell through
to the same `-4`, so the cost cancelled to exactly zero against every target
residue and `affinity` came out at 1.0 - the maximum. A `KPGT*` cell reported
affinity 1.0 against `KPGTA`, `KPGTW` and `KPGTAAAAAAAA` alike. Non-residues
are now charged the maximal substitution cost, so a receptor that cannot be
translated is scored as far from the target rather than close to it.

It is deliberately *not* treated as lethal. SHM here is not constrained to
keep a receptor productive, so stops accumulate fast -- **96% of sampled
cells carry one at the default `rate=0.05`**, 89% at `rate=0.01`, and 50% even
at `rate=0`, inherited from founders, 54% of which carry one already. Giving a
stop-bearing cell no offspring would therefore extinguish essentially every
lineage under selection rather than modelling a germinal centre. That the
mutation model produces mostly untranslatable receptors is a separate matter
from how affinity scores them.

- **A `target_aa` of the wrong length is refused.** The distance compared
`min(len, len)` positions and ignored the rest, so a truncated or over-long
target scored silently and reported a number that was not a distance to it.
A supplied target must now match the receptor protein's length; the error
names both.


- **`DETERMINISM_VERSION` is now 3.** Clonal lineage population regulation is
Beverton-Holt, `lambda_base / (1 + (lambda_base - 1) * P / n_max)`, in place
of the discrete logistic map `lambda_base * max(0, 1 - P / n_max)` and the
Expand Down
3 changes: 2 additions & 1 deletion engine_rs/src/determinism.rs
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@
//! | (absent) / 1 | one random stream shared by the whole plan; a substitution could redraw the base already present |
//! | 2 | one random substream per pass, and one per clonal-family role (growth, sampling, target) instead of a seed salted by XOR; a clone, a survival retry and a read take keyed substreams of the run seed instead of offsets added to it; a cohort subject and a genotype viability attempt take keyed substreams instead of words from a `random.Random` seeded with the run seed; a substitution draws a base the site does not hold |
//! | 3 | clonal lineage population regulation is Beverton-Holt, `lambda/(1 + (lambda-1)N/n_max)`, in place of the discrete logistic map `lambda(1 - N/n_max)`; `n_max` is the population a lineage settles at rather than the pivot of a law settling at `n_max(1 - 1/lambda)`, the law is monotone so it no longer oscillates above `lambda = 3`, and a generation may overshoot `n_max` instead of being truncated at it -- the truncation landed the population on `n_max` exactly, where the old law returned a rate of exactly zero, so reaching capacity extinguished the lineage |
//! | 4 | affinity selection scores the protein the cell expresses. The cell's amino-acid sequence is the continuous translation of its coding span (`productivity::coding_span`, resolved from the V allele's native reference phase) instead of the per-region codon rail, which dropped every codon straddling a region boundary -- all of them junction codons, so all of them CDR3; a stop or an unresolved residue is charged the maximal substitution cost instead of cancelling to zero against every target |

/// The engine's sampling-model version. Stamped on every exported
/// record and readable as `GenAIRR.DETERMINISM_VERSION`.
pub const DETERMINISM_VERSION: u32 = 3;
pub const DETERMINISM_VERSION: u32 = 4;
129 changes: 118 additions & 11 deletions engine_rs/src/lineage/affinity.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,24 @@ use crate::rng::Rng;
/// 20 standard amino acids in the BLOSUM62 matrix's row/column order.
pub(crate) const AA_ORDER: &[u8; 20] = b"ARNDCQEGHILKMFPSTWYV";

/// Position of `aa` in `AA_ORDER`, or `None` for anything that is not one of
/// the twenty residues -- a stop (`*`), an unresolved base (`X`), any other
/// byte. `substitution_cost` keys on this rather than on the matrix, because
/// the matrix cannot express "not a protein".
fn residue_index(aa: u8) -> Option<usize> {
AA_ORDER.iter().position(|&x| x == aa)
}

/// BLOSUM62 substitution score for two amino-acid bytes (uppercase one-letter
/// codes). Unknown / non-standard residues (including `*` and `X`) score as a
/// strong mismatch so they contribute maximally to distance.
/// codes). Unknown / non-standard residues (including `*` and `X`) score `-4`.
///
/// That is *not* the same as contributing maximally to distance, which this
/// comment used to claim: `substitution_cost` subtracts `S(a,a)` from `S(a,b)`,
/// and for a non-residue `a` both terms are this same `-4`, so the cost
/// cancelled to zero. The maximal-contribution rule lives in
/// `substitution_cost`, where it can see which side the non-residue is on.
pub fn blosum62(a: u8, b: u8) -> i8 {
fn idx(aa: u8) -> Option<usize> {
AA_ORDER.iter().position(|&x| x == aa)
}
let idx = residue_index;
// Canonical BLOSUM62, rows/cols in AA_ORDER.
const M: [[i8; 20]; 20] = [
// A R N D C Q E G H I L K M F P S T W Y V
Expand Down Expand Up @@ -44,9 +55,26 @@ pub fn blosum62(a: u8, b: u8) -> i8 {
}
}

/// The largest cost any substitution between two real residues can carry:
/// `S(W,W) - S(W,D) = 11 - (-4)`. `max_real_substitution_cost_is_the_constant`
/// holds this against the matrix.
const MAX_SUBSTITUTION_COST: f64 = 15.0;

/// Per-position substitution cost from BLOSUM62: `S(a,a) - S(a,b)`, which is 0
/// when `b == a` and grows as the substitution becomes less favorable.
///
/// A character that is not one of the twenty residues -- a stop (`*`) or an
/// unresolved base (`X`) -- is charged `MAX_SUBSTITUTION_COST` instead of being
/// scored through the matrix. Through the matrix it fell through to `-4` on
/// *both* terms, so `S(a,a) - S(a,b)` was exactly 0 and a stop cost nothing
/// against any target: a cell whose receptor cannot be translated scored
/// affinity 1.0, the perfect antibody, against every target. The asymmetry was
/// the tell -- a stop in the target cost the full amount, a stop in the cell
/// was free. A sequence that is not a protein is not a near match for one.
fn substitution_cost(a: u8, b: u8) -> f64 {
if residue_index(a).is_none() || residue_index(b).is_none() {
return MAX_SUBSTITUTION_COST;
}
(blosum62(a, a) as f64 - blosum62(a, b) as f64).max(0.0)
}

Expand Down Expand Up @@ -104,9 +132,20 @@ pub(crate) fn make_mature_target_with_choices(
Ok(target)
}

/// Translate a `Simulation` to its amino-acid sequence by concatenating the
/// in-frame translation of each region (respecting each region's frame phase),
/// in biological order. Used to score a cell's affinity to a target antigen.
/// Translate a `Simulation` by concatenating the in-frame translation of each
/// region. **Not the protein the cell expresses**, and no longer used to score
/// affinity -- see `coding_sim_to_aa`.
///
/// `compute_codon_rail` keeps a codon only if it fits wholly inside one region,
/// so every codon straddling a region boundary is dropped and the amino-acid
/// indices after it shift left. Every region boundary in a rearrangement is a
/// junction boundary, so what this drops is CDR3: measured over 200
/// `human_igh` records, 2.68 codons per record, and 536 of 536 of them
/// straddling V/NP1, NP1/D, D/NP2 or NP2/J. Scored against a real protein, a
/// cell identical to the target reported an affinity of 3.57e-67.
///
/// Retained because the per-region rail is what the region-level stop and
/// frame bookkeeping is defined against; it is not a translation of the cell.
pub fn sim_to_aa(sim: &Simulation) -> Vec<u8> {
let mut aa = Vec::new();
for region in sim.sequence.regions.iter() {
Expand All @@ -116,9 +155,17 @@ pub fn sim_to_aa(sim: &Simulation) -> Vec<u8> {
aa
}

/// Translate the observed coding span across source and junction boundaries.
/// Duplex body placement is independent of the region's legacy phase cache.
pub fn duplex_sim_to_aa(
/// Translate the cell's coding span continuously, across source and junction
/// boundaries. **This is the protein the cell expresses**, and the one affinity
/// is scored on.
///
/// `productivity::coding_span` resolves the frame from the V allele's native
/// reference phase, its 5' trim and its observation loss, which is why this
/// needs the reference and why concatenating pool bytes and translating from
/// zero would not do: the frame itself can be wrong. It agrees with the
/// record's own `sequence_aa`, which the projection derives independently from
/// `coding_frame_start`.
pub fn coding_sim_to_aa(
sim: &Simulation,
refdata: &crate::refdata::RefDataConfig,
) -> Result<Vec<u8>, String> {
Expand Down Expand Up @@ -209,6 +256,66 @@ mod tests {
assert_eq!(sim_to_aa(&sim), b"KK".to_vec());
}

#[test]
fn max_real_substitution_cost_is_the_constant() {
// The constant stands in for "worse than any real substitution", so it
// has to actually be that. Derived here rather than trusted.
let residues = b"ACDEFGHIKLMNPQRSTVWY";
let worst = residues
.iter()
.flat_map(|a| residues.iter().map(move |b| (*a, *b)))
.map(|(a, b)| blosum62(a, a) as f64 - blosum62(a, b) as f64)
.fold(0.0f64, f64::max);
assert_eq!(worst, MAX_SUBSTITUTION_COST, "matrix maximum is {worst}");
}

#[test]
fn a_stop_in_the_cell_costs_the_most_against_every_target() {
// `blosum62` falls through to -4 for anything outside the 20 residues,
// and the cost is S(a,a) - S(a,b). For a == '*' both terms are -4, so a
// stop cost nothing against any target and a cell whose receptor cannot
// be translated scored as the perfect antibody.
for target in b"ACDEFGHIKLMNPQRSTVWY" {
let stop = substitution_cost(b'*', *target);
assert!(
stop > 0.0,
"a stop costs {stop} against {}",
*target as char
);
// It must also be the worst available cost, not merely nonzero: a
// residue that cannot exist is not a mild substitution.
let worst_real = b"ACDEFGHIKLMNPQRSTVWY"
.iter()
.map(|a| substitution_cost(*a, *target))
.fold(0.0f64, f64::max);
assert!(
stop >= worst_real,
"a stop costs {stop} against {}, less than the worst real \
substitution at {worst_real}",
*target as char
);
}
}

#[test]
fn an_unknown_residue_costs_the_most_too() {
// `X` is a base the simulator could not resolve, not a known protein.
// It shared the stop's -4 fallthrough and so shared its zero cost.
assert!(substitution_cost(b'X', b'A') > 0.0);
}

#[test]
fn a_cell_full_of_stops_is_not_a_perfect_match() {
// Reproduced on the real model before the fix: a KPGT* cell reported
// affinity 1.0 against KPGTA, KPGTW and KPGTAAAAAAAA alike.
let m = AffinityModel::new(b"KPGTA".to_vec(), vec![1.0; 5], 1.0, 1.0, b"KPGTA");
let with_stop = m.affinity_value(b"KPGT*");
assert!(
with_stop < 1.0,
"a cell whose receptor ends in a stop scored {with_stop}"
);
}

#[test]
fn affinity_value_is_one_at_target() {
let m = AffinityModel::new(b"KK".to_vec(), vec![1.0; 2], 1.0, 1.0, b"KK");
Expand Down
Loading
Loading