API reference¶

A map of the public surface. The reference is 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 live on the dedicated pages in the API Reference nav section (Experiment, SimulationResult, ReferenceCartridgeBuilder, reference models).

How to read this reference¶

The page below is workflow-first, not signature-first. Each section starts with the user-facing surface - what to call, in what order - and links to the dedicated guide for context. Use 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 API Reference nav section has mkdocstrings- generated pages for Experiment, SimulationResult, ReferenceCartridgeBuilder, and the reference models and rules. The generated SimulationResult section below shows what those auto-rendered pages look like.

Top-level imports¶

35 names ship in GenAIRR.__all__. Grouped by what they do:

Simulation entry points¶

Symbol	Purpose	Guide
`Experiment`	Fluent pipeline builder	The Experiment builder
`CompiledExperiment`	Compiled plan (compile once, run many)	The Experiment builder
`SimulationResult`	Records + outcomes + parents wrapper	Quick start
`set_seed`, `get_seed`, `reset_seed`	Thread-local seed management	Validation hub
`__version__`	Resolved via `importlib.metadata`; falls back to `"0.0.0"` for editable installs	-

Reference data - cartridges and bridges¶

Symbol	Purpose	Guide
`DataConfig`	The Python-side cartridge dataclass	Reference cartridge
`RefDataConfig`	The engine-side refdata bridge object	Reference cartridge
`dataconfig_to_refdata`	Bridge function - `DataConfig → RefDataConfig`	`validate_records`
`ConfigInfo`	Identity metadata	Reference cartridge
`ChainType`	`BCR_HEAVY` / `BCR_LIGHT_KAPPA` / ...	-
`Species`	`HUMAN` / `MOUSE` / ...	-
`Productivity`	Productive / NonProductive enumeration	-
`list_configs`	Enumerate the 100+ bundled cartridges	-
`DataConfigError`	DataConfig validation failure	-

Bundled cartridges (lazy-loaded)¶

import GenAIRR as ga

cfg = ga.HUMAN_IGH_OGRDB     # pickled cartridge - loaded on first access

Symbol	Locus / chain
`HUMAN_IGH_OGRDB`	Human IGH, OGRDB
`HUMAN_IGH_EXTENDED`	Human IGH, extended catalogue
`HUMAN_IGK_OGRDB`	Human IGK, OGRDB
`HUMAN_IGL_OGRDB`	Human IGL, OGRDB
`HUMAN_TCRB_IMGT`	Human TRB, IMGT

The five top-level bundled cartridges above are the most commonly used. The full 100+-cartridge catalogue stays reachable via ga.list_configs() and GenAIRR.data.<NAME> (lazy attribute access).

Reference cartridge authoring¶

Symbol	Purpose	Guide
`ReferenceCartridgeBuilder`	Fluent builder for custom cartridges from FASTA	Build a reference cartridge
`CartridgeBuildReport`	Auditable build trail dataclass	Build a reference cartridge
`ReferenceRulesSpec`	Anchor + alphabet + severity rules	Reference cartridge
`AnchorRuleSpec`	Per-anchor expected-AA + required flag	Reference cartridge
`ReferenceEmpiricalModels`	Typed empirical-model bundle	Reference cartridge
`EmpiricalDistributionSpec`	`[(value, weight), ...]` shape	Reference cartridge
`NpBaseModelSpec`	NP-base sampling model (uniform / empirical / Markov)	Junction N/P additions
`AlleleUsageSpec`	Per-segment allele-usage weights	Reference cartridge

Validation reports and exceptions¶

Symbol	Purpose	Guide
`ValidationReport`	Per-record AIRR-validator output	`validate_records`
`FamilyValidationReport`	Family-validator output	Clonal simulation overview
`RecordValidationFailedError`	Raised when strict record validation fails	`validate_records`
`FamilyValidationFailedError`	Raised when strict family validation fails	Clonal simulation overview
`StrictSamplingError`	Raised under `strict=True` on empty admissible support	Validation hub
`productive`	Convenience contract bundle for productive sampling	Recombination biology

Experiment¶

The fluent pipeline builder. Every chained method returns the same Experiment extended by one more pass; the pipeline runs when .run_records(...) / .run(...) / .compile().run(...) is called.

Surface	Methods	Notes
Bind to a cartridge	`Experiment.on(cfg_or_name)`	Accepts a string shortcut, a `DataConfig`, or a `RefDataConfig`
Recombination	`.recombine()`, `.invert_d(prob=...)`, `.receptor_revision(prob=...)`	Ancestor-phase mechanisms
Constraints	`.productive_only()`, `.restrict_alleles(v=..., d=..., j=...)`	Constrain the sample space
Biological mutation	`.mutate(model="s5f"\\|"uniform", rate=..., count=..., segment_rates=..., v_subregion_rates=...)`	The only pass that increments `n_mutations`
Clonal structure	`.clonal_lineage(...)`, `.clonal_repertoire(...)`, legacy `.expand_clones(...)`	BCR trees, TCR / flat-BCR abundance repertoires, or fixed-size star families
Trims override	`.trim(v_3=..., d_5=..., d_3=..., j_5=..., enabled=...)`	Per-experiment trim distribution overrides
Library / sequencer artefacts	`.pcr_amplify(...)`, `.polymerase_indels(...)`, `.ambiguous_base_calls(...)`, `.sequencing_errors(...)`, `.end_loss_5prime(...)`, `.end_loss_3prime(...)`	All descendant-phase
Read layout	`.paired_end(r1_length=..., r2_length=..., insert_size=...)`, `.random_strand_orientation(prob=...)`	Per-read projection
Bookkeeping	`.with_metadata(...)`, `.contaminate(prob=...)`	Stamp metadata; inject background contaminants
Run	`.run_records(n=..., seed=..., validate_records=..., strict=..., expose_provenance=...)`, `.run(...)`, `.stream(...)`, `.stream_records(...)`	Compile + run + project
Compile reuse	`.compile()`	Compile once, reuse across many batches
Compile mode	`.allow_curatable_refdata()`, `.curate_refdata(policy)`	Cartridge-validation mode at compile time

See The Experiment builder for the full pipeline-stage map and ordering rules.

SimulationResult¶

The output of run_records(...) - a list-like wrapper around AIRR record dicts plus the underlying Outcome objects.

Surface	Methods / properties	Notes
List-like access	`len(result)`, `result[i]`, `result[a:b]`, `for rec in result:`	One AIRR dict per element
Underlying state	`.records`, `.outcomes`, `.parents`, `.lineage_trees`	`outcomes` is `None` when built from records only; `parents` exists only for legacy `expand_clones`; `lineage_trees` exists on lineage results
Validation	`.validate_records(refdata)`, `.validate_families()`, `.validate_families_with_parents(refdata)`	See Validation hub
Export	`.to_tsv(path, , airr_strict=True)`, `.to_csv(path, , airr_strict=False)`, `.to_fasta(path, , prefix="seq")`, `.to_fastq(path, , quality="illumina", *kw)`, `.to_paired_fastq(r1, r2, , quality="illumina", overwrite=False, *kw)`, `.to_dataframe(, airr_strict=False)`	TSV defaults to AIRR coordinate/CIGAR conversion and `T` / `F` booleans; see Export the results
Construction	`SimulationResult.from_outcomes(outcomes, refdata, *, id_prefix="seq", expose_provenance=False)`	Build a result from Rust `Outcome` objects + refdata; `expose_provenance=True` injects `truth_*_call` columns

Reports and exceptions¶

`ValidationReport`¶

report = result.validate_records(refdata)
report.ok        # bool - every record passed
report.count     # int - total records validated
report.failures  # list[dict] - per-record failure entries with structured issues
report.summary() # str - histogram of issue kinds
bool(report)     # == report.ok

`FamilyValidationReport`¶

report = result.validate_families()
report.ok                  # bool
report.count               # total records inspected
report.family_count        # int - distinct clone_ids found
report.members_per_family  # dict[int, int] - descendant count per clone
report.failures            # list[dict] - per-family failure entries
report.summary()           # histogram of issue kinds
bool(report)               # == report.ok

Same dataclass shape is returned by validate_families_with_parents(refdata).

`CartridgeBuildReport`¶

report = builder.report()           # or cfg.build_report
report.stages                       # list[dict] - one entry per builder call
report.warnings                     # list[str] - build-finalisation warnings
report.rejected                     # list[dict] - per-allele drops + per-row estimator rejections
report.manifest_snapshot            # dict | None - cartridge_manifest() at build time
report.checksum_at_build_time       # str | None - schema_sha256 stamped on cfg
report.to_dict()                    # JSON-clean dict for CI artifacts

See Build a reference cartridge for the full surface.

Exceptions¶

Exception	Raised by	When
`StrictSamplingError`	`run_records(..., strict=True)`	Empty admissible support at a sampling site
`RecordValidationFailedError`	Strict record-validation code paths	A validator gate fired in strict mode
`FamilyValidationFailedError`	Strict family-validation code paths	A family-validator gate fired in strict mode
`DataConfigError`	`DataConfig` validation	Cartridge spec rejected

StrictSamplingError is NOT a ValueError subclass - except ValueError will not catch it. Catch it explicitly:

try:
    result = exp.run_records(n=10, seed=42, strict=True)
except ga.StrictSamplingError as e:
    pass_name, address, reason = e.args

Generated `SimulationResult`¶

What an autogenerated section looks like (rendered via mkdocstrings from the docstrings in src/GenAIRR/result.py). The same treatment is on the dedicated pages for Experiment, ReferenceCartridgeBuilder, and the reference-model specs.

`GenAIRR.SimulationResult` ¶

Bases: _ResultExport, _ResultValidation

List-like wrapper around a batch of AIRR records.

result[i] returns the i-th record dict; len(result) is the number of records; iteration yields records in order.

The original Outcome objects (with their full trace + revision history) are kept on .outcomes for advanced inspection — most users won't need them.

`records` `property` ¶

The underlying list of record dicts. Mutation through this view propagates back into the result.

`outcomes` `property` ¶

The underlying list of Outcome objects, or None when this :class:SimulationResult was built from records directly (e.g. loaded from a TSV).

`parents` `property` ¶

Per-clone parent Outcome objects for clonal results; None for non-clonal results and for results built from records directly.

parents[c] is the recombination ancestor of clone c: every descendant record with record["clone_id"] == record["parent_id"] == c was produced by running the post-fork plan from this parent's :meth:final_simulation.

The parent Outcome carries the pre-fork addressed-choice .trace(), the pre-fork .events() ledger, the per-revision IR history (.revision(i)), and the final assembled IR (.final_simulation()). Use these for replay, lineage analysis, or building a parent-aware family validator (Slice 3+ scope).

The flat .outcomes list continues to carry only the descendant outcomes (one entry per AIRR record); parents live exclusively here. len(.parents) equals the clonal pipeline's n_clones; len(.outcomes) equals n_clones * per_clone.

What's not documented here yet¶

A few surfaces deliberately don't appear on this page:

Deep Rust engine internals. GenAIRR._engine exposes the PyO3 bindings (Outcome, TraceFile, RefDataConfig, Simulation, etc.). These are reachable from Python but are engine-developer surfaces; the user-facing surface above (SimulationResult.outcomes[i].trace(), compiled.simulator.replay_from_trace_file(...)) is what user code should touch.
Experimental / private helpers. Anything under GenAIRR._* is private; signatures and behaviour can change between releases without notice.
Pre-engine documentation. The historical _old_docs/ directory in the repository carries an earlier docs system that predates the Rust engine; it's preserved for reference but not migrated into the current site.

For the full per-symbol docstring inventory, the API Reference nav section carries mkdocstrings-driven pages for Experiment, SimulationResult, ReferenceCartridgeBuilder, and the cartridge-spec dataclasses.