From a6f221bf11bfe6f35573da80144e245d88b04080 Mon Sep 17 00:00:00 2001 From: "J. Sebastian Paez" Date: Fri, 28 Aug 2026 09:11:29 -0700 Subject: [PATCH] docs: correct the glossary where it disagreed with the code Three entries described behaviour that no longer exists, and one licensed the bug #98 was about. `Output id` said "the source id where there is one, the arena index otherwise". `seal` mints a source id for every unnamed row, so an arena index can no longer reach a result -- which was the point of the work. The term has collapsed into `Source id` and is gone; "output id" moves to that entry's avoid list. `Decoy group` said "a target and its decoy variants". A declared group is interned by label, so it can span several targets -- the reverse-decoy case the speclib generator emits. Competition keys on `(group, charge)`, so the entry now says one result survives per group and charge, and distinguishes declared from derived groups. `Variant` was defined as a member of a decoy group. It is a member of one row's decoy expansion; under a declared group those are different sets. `Arena index` loses its mechanics. What it means is in `mod index`'s doc and the constraint is enforced by the type -- `pub(super)` construction, no `Display`, no `Serialize` -- so prose repeating it can only go stale. The naming guidance stays, since that is the part no code states. --- CONTEXT.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 737907ce..ffa5cacd 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -31,20 +31,18 @@ ion chemistry; distinct from an opaque string label, which does not. ### How rows are named **Arena index**: -A row's position in the in-memory columnar store. Self-incrementing, assigned on -insertion, meaningful only within one process. Feeds decoy grouping and q-value -determinism, so it is never caller-supplied. +Where a row sits in memory. Internal to the process and never an identifier: it +addresses storage, and nothing else. _Avoid_: id, library_id, row id **Source id**: What the source file called a precursor -- the JSON target payload's `id`, mzSpecLib's `` key, DIA-NN's `transition_group_id`. Opaque: carried -through and echoed back, never used to address anything. Absent in some formats. -_Avoid_: id, library id +through and echoed back, never used to address anything. -**Output id**: -The identifier a result carries, so a caller can map results onto the request -they sent. The source id where there is one, the arena index otherwise. +Every row has one. A format that names nothing gets ids minted at load, so a +result is never keyed by where its row happened to land. +_Avoid_: id, library id, output id ### Decoys @@ -53,12 +51,22 @@ A deliberately wrong analyte scored alongside real ones to estimate the false discovery rate. Either shipped by the library or generated as a mass shift. **Decoy group**: -A target and its decoy variants, competing as a unit so exactly one survives. +The set of analytes that compete, so that one result survives per group and +charge. Two ways a group arises, and they differ in size: + +- _Declared_ by the library, which can put **several targets** in one group -- + `PEPTIDEK/2` and its reversed partner `PEDITPEP/2` compete because the file + says they are alternatives for the same evidence. +- _Derived_ when the library declares nothing, where a target competes only with + its own decoy variants. + +The declared case is the reason a group is not simply "a target and its decoys". **Variant**: -One member of a decoy group -- the target itself, or one of its mass-shifted -decoys. A stored row expands into several scored variants, so "one row" is not -"one result". +One member of a single target's decoy expansion -- the target itself, or one of +its mass-shifted decoys. Scoped to one row, not to a group: a declared group +holds several targets, each with its own variants. A stored row expands into +several scored variants, so "one row" is not "one result". ### Capabilities