diff --git a/mkdocs.yml b/mkdocs.yml index ab12c80..a92800e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,19 +1,17 @@ # MkDocs Material site configuration for GenAIRR docs. # -# Status: scaffold only. Phase 0 of the migration plan in -# `docs/docs_mkdocs_migration_plan.md`. No content has been -# migrated yet — most nav entries below point at placeholder -# files or files that don't exist yet. The contract pins in -# `tests/test_docs_mkdocs_migration_contract.py` verify -# scaffold completeness, not buildability. +# The site is live and built from `site_docs/`. Some deeper pages +# (a handful of concept/validation/cartridge-estimator stubs) are +# still being written; the nav below ships the pages that have +# content. The contract pins in +# `tests/test_docs_mkdocs_migration_contract.py` guard structure. # -# To build (once Phase 1 installs deps): +# To build: # pip install -e ".[docs]" # mkdocs build --strict # # Existing live URLs at `mutejester.github.io/GenAIRR/.html` -# are preserved via the `redirects` plugin block (commented out -# below until mkdocs-redirects is installed in Phase 1). +# are preserved via the `redirects` plugin block below. site_name: GenAIRR site_description: Synthetic immune-receptor-sequence simulator with absolute ground truth @@ -140,7 +138,9 @@ plugins: # — preserving every live `mutejester.github.io/GenAIRR/.html`. # 29 entries: one per existing website/*.html page, modulo # `index.html` which is the homepage itself (`/` already serves it). - "learn.md": "getting-started/index.md" + # NOTE: no 'learn.md' redirect — learn.md is a real nav page + # ("Choose your path"); a redirect here would clobber the built + # learn.html with a stub and make the page unreachable. "lesson-1.md": "getting-started/lesson-1-vdj-recombination-from-bases-up.md" "lesson-2.md": "getting-started/lesson-2-the-pipeline-scrubber.md" "lesson-3.md": "getting-started/lesson-3-s5f-mutation-isnt-uniform.md" @@ -197,10 +197,11 @@ nav: - Core Concepts: - concepts/index.md - AIRR Record: concepts/airr-record.md - - Reference Cartridge: concepts/reference-cartridge.md + - Reference Cartridge (concept): concepts/reference-cartridge.md - Simulation Guides: - guides/index.md - The Experiment builder: guides/experiment-builder.md + - Sample only productive sequences: guides/productive.md - Biology map: guides/biology-map.md - Recombination + junction biology: guides/recombination-junction.md - D inversion + receptor revision: guides/recombination-editing.md diff --git a/site_docs/concepts/airr-record.md b/site_docs/concepts/airr-record.md index c0f590d..6d08cdb 100644 --- a/site_docs/concepts/airr-record.md +++ b/site_docs/concepts/airr-record.md @@ -98,8 +98,8 @@ comma-separated **tie set** when the engine sampled an indistinguishable group: ```text -v_call: "IGHV3-23*01" -v_call: "IGHV3-23*01,IGHV3-23*04" ← tie set: two-way ambiguity +v_call: "IGHVF1-G2*01" +v_call: "IGHVF1-G2*01,IGHVF1-G2*02" ← tie set: two-way ambiguity ``` Downstream code that wants the single committed allele should diff --git a/site_docs/concepts/reference-cartridge.md b/site_docs/concepts/reference-cartridge.md index ae93bb7..9fd17b5 100644 --- a/site_docs/concepts/reference-cartridge.md +++ b/site_docs/concepts/reference-cartridge.md @@ -70,8 +70,9 @@ opt-in can mask it. The set of V / D / J / C alleles available to the simulator. Each allele carries a name, gene, sequence, segment, and an optional anchor position (V Cys / J W-or-F codon offset). The catalogue is -exactly what `cfg.add_v_allele(...)` etc. have always populated - -the cartridge concept is unchanged from earlier GenAIRR versions. +read through `cfg.v_alleles` / `cfg.d_alleles` / `cfg.j_alleles` +(dicts keyed by gene) - the cartridge concept is unchanged from +earlier GenAIRR versions. V alleles can additionally carry **subregion annotations** - the five canonical IMGT region intervals (`FWR1` / `CDR1` / `FWR2` / @@ -79,7 +80,7 @@ five canonical IMGT region intervals (`FWR1` / `CDR1` / `FWR2` / region mutation counters. When a V allele has a populated IMGT- gapped sequence, the bridge derives these intervals for you; otherwise you can supply them explicitly. See -[V-subregion annotations](../cartridges/v-subregion-annotations.md). +[Build a reference cartridge](../guides/build-reference-cartridge.md). ### Rules @@ -123,7 +124,7 @@ from GenAIRR import ( cfg.reference_models = ReferenceEmpiricalModels( allele_usage=AlleleUsageSpec( - v={"IGHV1-2*02": 100.0, "IGHV3-23*01": 60.0}, + v={"IGHVF1-G1*01": 100.0, "IGHVF1-G2*01": 60.0}, ), trims={ "V_3": EmpiricalDistributionSpec([(0, 5.0), (1, 3.0), (2, 1.0)]), @@ -234,7 +235,7 @@ P-nucleotide lengths) and writes the result into the corresponding typed empirical-model sub-plane. The build report's `stages` list captures every estimator's inputs and inferred distributions for provenance. See -[Cartridge estimators](../cartridges/estimators/index.md) for +[Estimate models from data](../guides/estimate-cartridge-models.md) for per-estimator detail. ## The manifest diff --git a/site_docs/getting-started/export-results.md b/site_docs/getting-started/export-results.md index 93c856b..6b0b438 100644 --- a/site_docs/getting-started/export-results.md +++ b/site_docs/getting-started/export-results.md @@ -175,7 +175,7 @@ on the TSV/DataFrame; the FASTQ files only carry sequence + quality. - **[Validate AIRR records](../validation/validate-records.md)** - confirm every field is internally consistent before downstream analysis. -- **[The simulation pipeline concept](../concepts/pipeline.md)** - +- **[The Experiment builder](../guides/experiment-builder.md)** - the mental model behind the DSL and what each pass actually does. - **[Productive sampling guide](../guides/productive.md)** - what "productive" means biologically and how the constraint composes diff --git a/site_docs/guides/biology-map.md b/site_docs/guides/biology-map.md index 5cba038..f9c8fcf 100644 --- a/site_docs/guides/biology-map.md +++ b/site_docs/guides/biology-map.md @@ -107,9 +107,9 @@ experimental design (Experiment). The reference cartridge carries the immutable biological priors: -- **Allele universe** - `cfg.alleles.v`, `cfg.alleles.d`, - `cfg.alleles.j`, `cfg.alleles.c`. The sequences and metadata - the recombinase has access to. +- **Allele universe** - `cfg.v_alleles`, `cfg.d_alleles`, + `cfg.j_alleles`, `cfg.c_alleles` (dicts keyed by gene). The + sequences and metadata the recombinase has access to. - **Empirical recombination distributions** - `cfg.reference_models.allele_usage`, `cfg.reference_models.trims`, @@ -119,7 +119,7 @@ The reference cartridge carries the immutable biological priors: draws the recombination pass samples from. - **SHM kernel** - the cartridge's S5F mutability table (used when `.mutate(model="s5f", ...)` runs). -- **V-subregion annotations** - `cfg.alleles.v[i].subregions`. +- **V-subregion annotations** - `cfg.v_alleles[gene][i].subregions`. Required for `v_subregion_rates`. - **Rules / anchors** - `cfg.reference_rules` (V Cys + J anchor expectations, allowed bases, severity). diff --git a/site_docs/guides/experiment-builder.md b/site_docs/guides/experiment-builder.md index 3adb406..8a746b6 100644 --- a/site_docs/guides/experiment-builder.md +++ b/site_docs/guides/experiment-builder.md @@ -183,7 +183,7 @@ exp.mutate(model="uniform", count=12) # exactly 12 uniform mutations per recor `end_loss_*prime(length=...)` follows the same `int` / `(low, high)` / `[(value, weight), ...]` shape. Read [`Tune corruption -rates`](tune-corruption.md) for the per-mechanism shape reference; +rates`](corruption-sequencing.md) for the per-mechanism shape reference; the API reference page has the formal signatures. ## How `productive_only()` works @@ -269,5 +269,5 @@ seed produces the same draws, which is how golden tests work. | Authoring or tuning a custom reference cartridge | [Reference cartridge](../concepts/reference-cartridge.md) | | Confirming output integrity post-run | [`validate_records`](../validation/validate-records.md) | | Per-record AIRR field catalogue | [Your first AIRR record](../getting-started/first-airr-record.md) | -| The mental model behind the DSL | [The simulation pipeline](../concepts/pipeline.md) | +| The mental model behind the DSL | [Core concepts](../concepts/index.md) | | Every public symbol's signature | [API reference](../reference/index.md) | diff --git a/site_docs/guides/genotype-benchmarking.md b/site_docs/guides/genotype-benchmarking.md index baf0297..cf50615 100644 --- a/site_docs/guides/genotype-benchmarking.md +++ b/site_docs/guides/genotype-benchmarking.md @@ -160,3 +160,10 @@ Because the genotype is planted, every tool is scored identically: recovered allele set vs `genotype.to_table()` - presence precision/recall, zygosity, and deletion calls. +## Where to go next + +- [Genotypes (overview)](genotype.md) - building genotypes, novel alleles, and + the `to_table()` / `to_tsv()` ground truth you score against. +- [Genotype cohorts](genotype-cohorts.md) - scale this recipe to many donors in + one `run_cohort` call. + diff --git a/site_docs/guides/genotype-cohorts.md b/site_docs/guides/genotype-cohorts.md index 65b308a..b3420ac 100644 --- a/site_docs/guides/genotype-cohorts.md +++ b/site_docs/guides/genotype-cohorts.md @@ -58,3 +58,11 @@ a cohort is fully reproducible and subjects are independent. its own carried alleles); clonal forks are not combined with a cohort in this release. +## Where to go next + +- [Genotypes (overview)](genotype.md) - the core model and the `Genotype` builder. +- [Sampling & population priors](genotype-priors.md) - draw the per-subject + genotypes a cohort runs on. +- [Benchmarking genotype inference](genotype-benchmarking.md) - score a tool + against the planted truth; the recipe applies per subject across a cohort. + diff --git a/site_docs/guides/genotype.md b/site_docs/guides/genotype.md index ba75a5c..5564156 100644 --- a/site_docs/guides/genotype.md +++ b/site_docs/guides/genotype.md @@ -95,6 +95,11 @@ result[0]["haplotype"] # 0 or 1 - which chromosome this read used result.genotypes[0].to_table() # ground-truth genotype (per gene, per haplotype) ``` +`subject_id` and `haplotype` are on every record; add +`run_records(..., expose_provenance=True)` to also get the +`truth_v_call` / `truth_d_call` / `truth_j_call` columns (the alleles the +engine actually sampled). + ## How recombination samples from a genotype When a genotype is attached, recombination runs a single phased sampling pass per @@ -195,8 +200,9 @@ Notes and guard-rails: - **`complete_from_reference(policy=...)`** fills only genes you haven't touched. `"homozygous_first_reference"` (default) makes each unspecified gene homozygous for its first cartridge allele - note this is the *first listed* allele, **not** - a population-frequency-common one (GenAIRR has no frequency prior in this - release; the name says exactly what it does). `"heterozygous_first_two"` uses + a population-frequency-common one (this policy consults no frequency prior; for + frequency-driven genotypes use + [`Genotype.sample`](genotype-priors.md)). `"heterozygous_first_two"` uses the first two alleles. - Unknown gene/allele names, NaN/inf chromosome weights, and segments left with no usable allele are all rejected at build/attach with clear messages. @@ -216,8 +222,8 @@ allele-usage model (`reference_models.allele_usage`), aggregated to the gene level, and scaled by **copy-number dosage** (a duplicated gene recombines proportionally more often). Cartridges that don't author a typed `allele_usage` fall back to uniform-over-present-genes (× dosage). See -[Allele usage](v-usage.md) and [Estimate models from data](estimate-cartridge-models.md) -for authoring usage. +[Allele usage](recombination-junction.md#controlling-the-allele-universe) and +[Estimate models from data](estimate-cartridge-models.md) for authoring usage. ### More genotype recipes diff --git a/site_docs/guides/productive.md b/site_docs/guides/productive.md index e460f13..053873c 100644 --- a/site_docs/guides/productive.md +++ b/site_docs/guides/productive.md @@ -1,11 +1,83 @@ # Sample only productive sequences -!!! info "Migration placeholder" - This page is a placeholder. Content lands in **Phase 3** - of the migration plan documented in - [`docs/docs_mkdocs_migration_plan.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/docs_mkdocs_migration_plan.md). - - Until then, see the corresponding live page on the existing - documentation site at - [mutejester.github.io/GenAIRR](https://mutejester.github.io/GenAIRR/) - or the source markdown referenced above (if any). +

`productive_only()` constrains V(D)J sampling so the engine only ever +produces productive rearrangements - in-frame junction, no stop +codon in the junction, and the conserved V (Cys) and J (Trp/Phe) anchors intact. +It is a chainable, order-independent step on the Experiment.

+ +```python +import GenAIRR as ga + +result = ( + ga.Experiment.on("human_igh") + .recombine() + .productive_only() # constrain to productive rearrangements + .run_records(n=1000, seed=7) +) +# every record: rec["productive"] is True +``` + +## What "productive" means here + +A rearrangement is productive when its assembled coding sequence could yield a +functional receptor. GenAIRR enforces the **productive triad**: + +- the junction is **in-frame** (the V(D)J join preserves the reading frame), +- there is **no stop codon in the junction**, and +- the conserved anchors are intact - the **V cysteine** and the **J + tryptophan/phenylalanine** that bound the CDR3. + +## How it works - constrain before propose + +`productive_only()` is **not** a reject-and-resample loop that throws away bad +draws after the fact. GenAIRR follows a **constrain-before-propose** discipline: +the constraint narrows the *candidate support at each draw*, so out-of-frame or +stop-bearing candidates are never proposed in the first place. The engine samples +only from the admissible set. + +This is why it is efficient and why the productive fraction jumps from the +unconstrained baseline (heavy chains are productive only a minority of the time +by chance - about [18.5% in the demo](../demo.md)) to 100%. It also composes +with the other sampling constraints (e.g. +[`restrict_alleles`](recombination-junction.md#controlling-the-allele-universe)) - +the engine intersects all active constraints into one admissible support, so the +choice of where in the chain you call `productive_only()` doesn't matter. + +## Interaction with SHM + +The same discipline extends to somatic hypermutation. When `productive_only()` is +in the pipeline, the [mutation pass](shm-targeting.md#interaction-with-productive_only) +never proposes a substitution that would break the productive triad - the +constraint masks the per-site proposal support, so a mutation that would +introduce a junction stop or destroy an anchor simply can't be drawn. `productive` +stays `True`, and `n_mutations` counts only the substitutions that landed and +survived the mask. + +## What you get on the record + +Every record carries the AIRR `productive` field; with `productive_only()` it is +`True` for all of them. The output is productive *by construction* - you do not +need to filter post-hoc, and [`validate_records`](../validation/validate-records.md) +will confirm the productive invariants hold for every row. + +## When to use it + +- **Realistic functional repertoires** - most expressed immunoglobulin (BCR) + sequences are productive; `productive_only()` matches that without discarding + samples. +- **Benchmarks that assume productive input** - aligners/annotators are usually + evaluated on productive reads. + +Leave it off when you specifically want the unconstrained mix (including +non-productive rearrangements) - e.g. to study out-of-frame rates or to +stress-test a tool on non-productive input. + +!!! warning "Immunoglobulin (BCR) only" + The productive contract's anchor checks assume BCR semantics, so it is an + immunoglobulin feature. TCR refdata accepts the call but raises a + `ValueError` at compile time - don't add `productive_only()` to a TCR + pipeline. + +The constraint is implemented as a bundle of engine contracts (anchor +preservation, junction frame, no-junction-stop); the contributor-facing details +live in the [architecture guide](../architecture/index.md). diff --git a/site_docs/guides/recombination-editing.md b/site_docs/guides/recombination-editing.md index 9b4d05a..6838653 100644 --- a/site_docs/guides/recombination-editing.md +++ b/site_docs/guides/recombination-editing.md @@ -350,6 +350,6 @@ not let you accidentally split them. biology stage that runs *after* recombination edits; SHM accumulates on the post-revision V and the inverted D. - For the engine-side mechanics + audit details, see - [`docs/d_inversion_design.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/d_inversion_design.md) + [`audit-docs/d_inversion_design.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/d_inversion_design.md) and - [`docs/receptor_revision_design.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/receptor_revision_design.md). + [`audit-docs/receptor_revision_design.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/receptor_revision_design.md). diff --git a/site_docs/guides/recombination-junction.md b/site_docs/guides/recombination-junction.md index 8553951..8bbd67a 100644 --- a/site_docs/guides/recombination-junction.md +++ b/site_docs/guides/recombination-junction.md @@ -83,7 +83,7 @@ walker can't disambiguate between alleles from the assembled sequence alone: ```python -rec["v_call"] # 'IGHV1-2*02,IGHV1-2*04' ← tie set: two alleles equally consistent +rec["v_call"] # 'IGHVF1-G1*01,IGHVF1-G1*02' ← tie set: two alleles equally consistent ``` Two facts to know about call provenance: @@ -125,11 +125,11 @@ the universe: # Per-experiment subset: ga.Experiment.on("human_igh") \ .recombine() \ - .restrict_alleles(v=["IGHV1-2*02", "IGHV3-23*01"]) + .restrict_alleles(v=["IGHVF1-G1*01", "IGHVF1-G2*01"]) # Per-cartridge weights: cfg.reference_models = ReferenceEmpiricalModels( - allele_usage=AlleleUsageSpec(v={"IGHV1-2*02": 100.0, "IGHV3-23*01": 60.0}), + allele_usage=AlleleUsageSpec(v={"IGHVF1-G1*01": 100.0, "IGHVF1-G2*01": 60.0}), ) ``` diff --git a/site_docs/index.md b/site_docs/index.md index 34bac84..886966f 100644 --- a/site_docs/index.md +++ b/site_docs/index.md @@ -27,9 +27,9 @@ an aligner.

// 01

Benchmark

-

Compare alignment, clustering, or annotation tools against a ground truth - the engine emitted by construction, not by an oracle aligner that can be - wrong.

+

Score alignment, clustering, annotation, or genotype-inference + tools (TIgGER, IgDiscover) against a ground truth the engine emitted by + construction, not an oracle aligner that can be wrong.

@@ -61,7 +61,7 @@ an aligner.

Byte-stable replay
-## What GenAIRR does. Six capabilities. One composable engine. +## What GenAIRR does. Seven capabilities. One composable engine.
@@ -72,36 +72,43 @@ an aligner.

models per cartridge plane.

+
+

// Diploid · 02

+

Genotype

+

Per-individual diploid germline: phased V(D)J from one chromosome, + zygosity, gene deletion, novel alleles, and multi-subject cohorts.

+
+
-

// SHM · 02

+

// SHM · 03

Mutate

Uniform or S5F context-aware SHM. Per-segment + per-V-subregion rate targeting (FWR/CDR).

-

// Lineage · 03

+

// Lineage · 04

Simulate clones

BCR lineage trees, TCR clone-size repertoires, and flat abundance benchmarks with planted clone IDs.

-

// Library · 04

+

// Library · 05

Corrupt

Primer trimming, structural indels, PCR errors, N-base injection. Each knob tunable per workload.

-

// Contracts · 05

+

// Contracts · 06

Constrain

Productive-only sampling at compile time. The engine never proposes out-of-frame or stop-bearing candidates.

-

// Replay · 06

+

// Replay · 07

Replay

Trace every random draw. Byte-identical replay across runs, platforms, and one-knob-changed counterfactuals.

@@ -134,26 +141,24 @@ newick = result.lineage_trees[0].to_newick() # ground-truth lineage tree per
[See the full quick start →](getting-started/quick-start.md){ .btn .btn-primary } -[Learn by simulating one molecule →](getting-started/index.md){ .btn .btn-ghost } +[Start the getting-started track →](getting-started/index.md){ .btn .btn-ghost } --- ## Choose your path -Five paths through the docs, organised by what you came here to -do. Each one is a short curriculum. Pick the one that matches -your task. +A few of the most common starting points - the +**[Choose your path](learn.md)** page has the full set (eight paths), +each expanded into a short ordered reading list. | If you want to ... | Start here | |---|---| | **Simulate sequences** | [Quick start](getting-started/quick-start.md) → [The Experiment builder](guides/experiment-builder.md) → [API reference](reference/index.md) | +| **Simulate per-individual genotypes** | [Genotypes](guides/genotype.md) → [Sampling & population priors](guides/genotype-priors.md) → [Cohorts](guides/genotype-cohorts.md) | +| **Simulate clonal repertoires** | [Clonal overview](guides/clonal-families.md) → [Lineage trees](guides/clonal-lineage.md) → [Repertoires](guides/clonal-repertoire.md) | | **Build a reference cartridge** | [Reference cartridge concept](concepts/reference-cartridge.md) → [Build a reference cartridge](guides/build-reference-cartridge.md) | -| **Get reproducible / validated output** | [Validation hub](validation/index.md) → [Validate AIRR records](validation/validate-records.md) → [Trace, replay, reproducibility](guides/trace-replay.md) | -| **Understand the biological mechanisms** | [Recombination + junction biology](guides/recombination-junction.md), [SHM and mutation targeting](guides/shm-targeting.md), [Corruption + sequencing artefacts](guides/corruption-sequencing.md), [Clonal simulation overview](guides/clonal-families.md) | -| **Contribute to GenAIRR** | [Architecture (Contributor)](architecture/index.md) | - -The **[Choose your path](learn.md)** page expands each of these -into a short ordered reading list. +| **Benchmark tools against ground truth** | [Quick start](getting-started/quick-start.md) → [Benchmarking genotype inference](guides/genotype-benchmarking.md) | +| **Get validated / reproducible output** | [Validate AIRR records](validation/validate-records.md) → [Trace, replay, reproducibility](guides/trace-replay.md) | --- diff --git a/site_docs/learn.md b/site_docs/learn.md index ceccdb7..fb3ae8f 100644 --- a/site_docs/learn.md +++ b/site_docs/learn.md @@ -1,6 +1,6 @@ # Choose your path -

Five paths through the docs, organised by what +

Eight paths through the docs, organised by what you came here to do. Each path is a short curriculum - read in order and you'll have a working mental model by the end. Skip to any starting point that matches your current task.

@@ -23,6 +23,56 @@ batch. If you only ever read one page after the quick start, make it the Experiment builder. +## I want to simulate per-individual genotypes + +Phased, diploid germline per subject - the basis for genotype/ +haplotype-inference benchmarks. + +1. **[Genotypes (overview)](guides/genotype.md)** - what a genotype + is, how phased recombination samples from it, and how to build + one (zygosity, deletion, duplication, novel alleles). +2. **[Sampling & population priors](guides/genotype-priors.md)** - + draw a genotype with `Genotype.sample`, or author/estimate a + donor-population prior on the cartridge. +3. **[Genotype cohorts](guides/genotype-cohorts.md)** - simulate + many subjects in one `run_cohort` call, each with its own + genotype and per-subject provenance. + +With no genotype attached the engine is byte-for-byte unchanged; +attaching one is the only thing that switches recombination onto +the phased path. + +## I want to simulate clonal repertoires + +Shared-ancestor structure: BCR affinity-maturation trees and +TCR / abundance repertoires with planted clone IDs. + +1. **[Clonal simulation overview](guides/clonal-families.md)** - + choose `clonal_lineage` for BCR trees, `clonal_repertoire` for + TCR / abundance repertoires, or legacy `expand_clones`. +2. **[Clonal lineage trees](guides/clonal-lineage.md)** - BCR SHM + trees, selection, final-cell sampling, lineage metadata, and + tree exports (Newick). +3. **[Clonal repertoires](guides/clonal-repertoire.md)** - TCR and + flat-BCR clone sizes, `duplicate_count`, and AIRR clone-caller + export. + +## I want to benchmark tools against ground truth + +GenAIRR's core use case: simulate a *known* answer, run a tool, +score it - with no real-data uncertainty about what's correct. + +1. **[Quick start](getting-started/quick-start.md)** - produce a + repertoire with by-construction truth columns + (`expose_provenance=True`). +2. **[Validate AIRR records](validation/validate-records.md)** - + confirm every reported field is internally consistent before + you score anything. +3. **[Benchmarking genotype inference](guides/genotype-benchmarking.md)** - + the end-to-end recipe with a worked TIgGER / IgDiscover example + recovering a planted genotype; the same pattern applies to + aligner / annotation benchmarks. + ## I want to build a reference cartridge Custom alleles, custom empirical distributions, custom biology. @@ -73,21 +123,14 @@ where the v1 boundary sits. 4. **[SHM and mutation targeting](guides/shm-targeting.md)** - uniform vs S5F, per-segment and per-V-subregion rates, counter partitions. -5. **[Clonal simulation overview](guides/clonal-families.md)** - - choose `clonal_lineage` for BCR trees, `clonal_repertoire` for - TCR / abundance repertoires, or legacy `expand_clones`. -6. **[Clonal lineage trees](guides/clonal-lineage.md)** - BCR SHM - trees, selection, final-cell sampling, lineage metadata, and - tree exports. -7. **[Clonal repertoires](guides/clonal-repertoire.md)** - TCR and - flat-BCR clone sizes, `duplicate_count`, and AIRR clone-caller - export. -8. **[Corruption + sequencing artefacts](guides/corruption-sequencing.md)** +5. **[Corruption + sequencing artefacts](guides/corruption-sequencing.md)** the observation-stage mechanisms (PCR, sequencing errors, indels, end-loss, N corruption, strand). Each guide opens with the biology, names the v1 boundary decisions, and links back to the audit doc that defined them. +Clonal structure has its own path above +([simulate clonal repertoires](#i-want-to-simulate-clonal-repertoires)). ## I'm contributing to GenAIRR @@ -98,13 +141,13 @@ workflow, mechanism additions. engine mental model, the audit-first workflow, the "before you add a new mechanism" checklist, deep links into the audit corpus. -2. **[`docs/engine_architecture.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/engine_architecture.md)** +2. **[`audit-docs/engine_architecture.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/engine_architecture.md)** the seven engine invariants. Required reading before any kernel work. -3. **[`docs/adding_a_pass.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/adding_a_pass.md)** +3. **[`audit-docs/adding_a_pass.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/adding_a_pass.md)** the pass-author playbook with the minimal pass template and the three required test patterns. -4. **[`docs/validation_matrix.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/validation_matrix.md)** +4. **[`audit-docs/validation_matrix.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/validation_matrix.md)** the navigable map: every guarantee → audit doc → test file → kernel invariant. diff --git a/site_docs/reference/index.md b/site_docs/reference/index.md index 75894cb..43a8e7f 100644 --- a/site_docs/reference/index.md +++ b/site_docs/reference/index.md @@ -4,7 +4,9 @@ organised by workflow - how you actually compose a simulation - rather than alphabetically. For each symbol, the user guide that explains how to use it is linked; the autogenerated -per-symbol signatures are still being expanded.

+per-symbol signatures live on the dedicated pages in the +API Reference nav section (Experiment, +SimulationResult, ReferenceCartridgeBuilder, reference models).

## How to read this reference @@ -15,9 +17,13 @@ this page to find the right symbol; use the guides to learn when and why to use it. If you want the precise method signatures or the underlying -docstrings, the [generated SimulationResult section](#generated-simulationresult) -below shows what auto-rendered API docs look like (one example -class today; the rest land in a follow-up slice). +docstrings, the **API Reference** nav section has `mkdocstrings`- +generated pages for [Experiment](experiment.md), +[SimulationResult](simulation-result.md), +[ReferenceCartridgeBuilder](reference-cartridge-builder.md), and the +[reference models and rules](reference-models.md). The +[generated SimulationResult section](#generated-simulationresult) +below shows what those auto-rendered pages look like. ## Top-level imports @@ -196,8 +202,8 @@ except ga.StrictSamplingError as e: What an autogenerated section looks like (rendered via `mkdocstrings` from the docstrings in `src/GenAIRR/result.py`). -One class today; the full reference fills in over follow-up -slices. +The same treatment is on the dedicated pages for `Experiment`, +`ReferenceCartridgeBuilder`, and the reference-model specs. ::: GenAIRR.SimulationResult options: @@ -232,9 +238,8 @@ A few surfaces deliberately don't appear on this page: that predates the Rust engine; it's preserved for reference but not migrated into the current site. -When you need the full per-symbol docstring inventory, the -follow-up slice will land `mkdocstrings`-driven pages for -`Experiment`, `SimulationResult`, `ReferenceCartridgeBuilder`, -`DataConfig`, and the cartridge-spec dataclasses. Today, the -[generated `SimulationResult` section](#generated-simulationresult) -above is the only one. +For the full per-symbol docstring inventory, the **API Reference** +nav section carries `mkdocstrings`-driven pages for +[`Experiment`](experiment.md), [`SimulationResult`](simulation-result.md), +[`ReferenceCartridgeBuilder`](reference-cartridge-builder.md), and the +[cartridge-spec dataclasses](reference-models.md). diff --git a/site_docs/stylesheets/extra.css b/site_docs/stylesheets/extra.css index dda7ddb..21aea64 100644 --- a/site_docs/stylesheets/extra.css +++ b/site_docs/stylesheets/extra.css @@ -639,7 +639,7 @@ code, kbd, pre, samp, } } -/* 6-card capabilities grid (3×2) */ +/* capabilities grid (3 columns; flows to as many rows as cards) */ .md-typeset .cap-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); @@ -665,6 +665,7 @@ code, kbd, pre, samp, } .md-typeset .cap-card.cap-recombine .cap-num { color: var(--accent-ink); } +.md-typeset .cap-card.cap-genotype .cap-num { color: var(--data-slate); } .md-typeset .cap-card.cap-mutate .cap-num { color: var(--data-cyan); } .md-typeset .cap-card.cap-clone .cap-num { color: var(--archive-ink); } .md-typeset .cap-card.cap-corrupt .cap-num { color: var(--data-rust); } diff --git a/site_docs/validation/validate-records.md b/site_docs/validation/validate-records.md index d484792..00e2e2e 100644 --- a/site_docs/validation/validate-records.md +++ b/site_docs/validation/validate-records.md @@ -242,7 +242,7 @@ what to reach for when you need them: cached `SegmentLiveCall` against a from-scratch recompute. That layer is internal to engine maintenance - users rarely need it unless they're filing a bug against the cache. Both layers are - documented in the [two-layer integrity model](two-layer-model.md). + documented in the [architecture guide](../architecture/index.md#the-two-layer-integrity-model). --- @@ -254,7 +254,7 @@ and is exposed to Python through `SimulationResult.validate_records`. For the full check catalogue, the §5A/§5B silent invariants the validator pins, and the empirical sweep that drove the original landing, see the contributor audit at -[`docs/airr_record_validator.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/airr_record_validator.md). +[`audit-docs/airr_record_validator.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/airr_record_validator.md). For the engine-wide validation matrix (every guarantee → audit doc → test file → Rust kernel mapping), see -[`docs/validation_matrix.md`](https://github.com/MuteJester/GenAIRR/blob/master/docs/validation_matrix.md). +[`audit-docs/validation_matrix.md`](https://github.com/MuteJester/GenAIRR/blob/master/audit-docs/validation_matrix.md).