Catalogue · v1.0.4

Reference.

Every public symbol, every config key, every AIRR field. Reference is exhaustive — Concepts explain why, Guides walk you through how, and this is the page you grep when you already know what you're looking for.

38Public classes

182Public functions

~70AIRR truth fields

6CLI commands

{ } Python API 220 ⌗ Configs 14 ▦ AIRR fields 70 ›_ CLI 6

⌕ /

01

Python API.

Everything importable from genairr. Grouped by module, sorted by what you'll touch first.

genairr.experiment core

class Experiment(config: str | Config, seed: int = None) The DSL entrypoint. Chain .recombine(), .mutate(), .corrupt_*() and .run(n). fn Experiment.recombine(productive_only: bool = True) Append the recombination phase (sample · trim · assemble · NP). fn Experiment.mutate(model: str = "s5f", count: tuple[int,int] = None, rate: float = None) Append the somatic-hypermutation phase. Pass count or rate, not both. fn Experiment.corrupt_5prime_loss(p: float, max_loss: int = 60) Probabilistically truncate the 5′ end up to max_loss bp. fn Experiment.corrupt_indels(rate: float) Insert low-rate ins/del events; uniform over positions. fn Experiment.run(n: int) → list[Record] Execute the chain and return n AIRR records. fn Experiment.iter(n: int) → Iterator[Record] Streaming variant for large n — never materializes the full batch. fn Experiment.add_pass(p: Pass, at: str = "end") Insert a custom Pass into the pipeline. at may be "start" / "end" / "after:<name>".

genairr.pipeline extending

trait Pass.apply(ir: Simulation, rt: PassRuntime) → Simulation The one method every pass must implement. Pure: in goes IR, out comes IR. class SampleAllelePass(weights: str = "uniform") Draws V·D·J alleles from the reference; supports empirical weight tables. class TrimPass(distributions: TrimDistributions) Samples 3′ V / 5′ D / 3′ D / 5′ J trim lengths. class S5FMutationPass(count: tuple, kernel: str = "yaari_2013") 5-mer-conditioned SHM substitutions. Built-in kernels: yaari_2013, cui_2016. class EndLossPass(p_5prime: float, p_3prime: float, max_loss: int = 60) End truncation model for short-read library prep. class NCorruptionPass(rate: float) Scatters N-bases at the given per-position rate.

genairr.contracts predicates

fn productive(strict: bool = True) → Contract Bundle of anchor_preserved + productive_junction_frame + no_stop_codon_in_junction. fn anchor_preserved() → Contract Cys-104 (V) and Trp/Phe (J) anchor codons survive trimming. fn productive_junction_frame() → Contract CDR3 length divisible by 3. fn no_stop_codon_in_junction() → Contract No TAA/TAG/TGA inside CDR3.

genairr.io export

fn write_airr_tsv(records, path, truth: bool = True) Write to AIRR-spec TSV. Set truth=False to strip truth_* fields. fn write_parquet(records, path, compression: str = "zstd") Columnar export. ~10× smaller than TSV at default compression. fn write_fasta(records, path, header: str = "{seq_id}") Plain FASTA. Header template is f-string over record fields. + Show all 28 io symbols → readers, schema validators, AIRR↔IMGT mappers

02

Configs.

14 built-in configs. Drop a name into Experiment("…") or fork the YAML and pass a path. Schema is documented per-key.

Human IGH human_igh_naivePre-GC repertoire, low SHM, default V-usage human_igh_memoryHigh SHM, biased toward IGHV3 / IGHV4 human_igh_plasmablastHypermutated, class-switched isotype distribution

Human TCR human_trb_naive human_tra_naive human_trg_naive human_trd_naive

Mouse mouse_igh_c57bl6 mouse_igk mouse_igl mouse_trb

Synthetic / testing minimal_igh3 V · 1 D · 2 J — for unit tests synthetic_uniformPathological uniform priors custom (template)Copy-paste starter YAML

03

AIRR fields.

~70 fields per record. truth_* is the simulator's ground-truth answer. evidence is what an aligner would output. Use the former to score the latter.

Field Type Group Source pass Description

sequencestrmetaioFinal nucleotide sequence as written to the AIRR file.

sequence_lengthintmetaEndLossPassLength after all corruption passes.

v_callstrevidencelive-callV allele(s) the evidence-based caller supports, comma-separated when ambiguous; truth-first when the sampled allele survives the tie.

truth_v_callstrtruthSampleAllelePassThe V allele the simulator actually sampled.

truth_d_callstrtruthSampleAllelePassThe D allele actually sampled.

truth_j_callstrtruthSampleAllelePassThe J allele actually sampled.

junctionstrsegmentsAssembleSegmentPassCDR3 nucleotide sequence inclusive of anchors.

junction_aastrsegmentsAssembleSegmentPassCDR3 amino-acid translation.

productivebooltruthcontracts.productiveTrue if in-frame, no stop codon, anchors preserved.

truth_n_mutationsinttruthS5FMutationPassTotal SHM substitution count.

mutation_ratefloattruthS5FMutationPasstruth_n_mutations / sequence_length.

mutation_poslist[int]truthS5FMutationPassPer-substitution position, 0-indexed.

v_identityfloattruthderivedFraction of V positions identical to germline.

corruption_addedboolcorruptionEndLossPass+True if any corruption pass modified the sequence.

n_countintcorruptionNCorruptionPassNumber of ambiguous N bases.

5_prime_lossintcorruptionEndLossPassBases truncated from the 5′ end.

04

CLI.

Six commands installed alongside the Python package. For one-off simulations and CI.

genairr simulate Run a config and write AIRR output. The 90% command. genairr simulate human_igh_naive -n 50000 -o out.tsv

genairr inspect Print a single sequence's full trace — every pass, every event. genairr inspect human_igh_naive --seed 42

genairr validate Run marginal QC on a TSV against an empirical reference panel. genairr validate out.tsv --against oas_human_b

genairr configs List built-in configs with their key parameters. genairr configs --filter human

genairr benchmark Plug-and-play aligner benchmark against simulated truth. genairr benchmark igblast --n 10000

genairr export Convert a saved run between TSV / Parquet / FASTA. genairr export out.tsv -o out.parquet