ReferenceCartridgeBuilder

A fluent builder for custom reference cartridges from raw FASTA. Every call returns the same builder extended by one stage; at .build() the engine validates the typed planes and stamps a schema_sha256 on the resulting DataConfig. Every stage's inputs, warnings, and rejection details are captured in builder.report() - the cartridge ships with an auditable trail.

For the broader workflow, see Build a reference cartridge; for the estimator deep dive, see Estimate cartridge models from real data.

Common methods

Method	Purpose
.from_fasta(...)	Class-level constructor; parses V/D/J FASTA into the catalogue
.infer_identity(...)	Declare species / chain / locus / reference-set / name; missing species stays unknown
.with_build_date(date)	Fix metadata.last_updated so identical inputs reproduce the same checksum
.with_reference_evidence(..., anchors=...)	Attach sequence-bound landmark, coding-phase and coding-boundary evidence
.infer_v_subregions()	Annotate V alleles with FWR/CDR intervals (required for v_subregion_rates)
.with_rules(...)	Attach an explicit ReferenceRulesSpec
.with_models(...)	Attach an explicit ReferenceEmpiricalModels bundle
.estimate_allele_usage(records)	Estimate per-segment allele weights
.estimate_trim_distributions(records)	Estimate per-key trim distributions
.estimate_np_length_distributions(records)	Estimate NP1 / NP2 length distributions
.estimate_np_base_model(records, kind=...)	Estimate NP-base model (Markov or empirical first-base)
.estimate_p_nucleotide_lengths(records)	Estimate palindromic-insertion length distributions
.build()	Finalise, stamp checksum, return the DataConfig
.report()	Get the CartridgeBuildReport with stages / warnings / rejections

See Reference evidence and catalogue quarantine for source requirements, conservative anchor inference and legacy compatibility.

Class reference

GenAIRR.cartridge_builder.ReferenceCartridgeBuilder

Bases: _CartridgeEstimators

Stage-based builder for a :class:~GenAIRR.DataConfig.

See :mod:GenAIRR.cartridge_builder module docs and docs/reference_cartridge_authoring_audit.md for the design.

Usage::

builder = ReferenceCartridgeBuilder.from_fasta(
    v_fasta="igh_v.fasta",
    j_fasta="igh_j.fasta",
    d_fasta="igh_d.fasta",
    chain_type="BCR_HEAVY",
)
builder.infer_identity(species="HUMAN", reference_set="MY_REF")
builder.infer_v_subregions()
builder.with_rules(my_rules_spec)
builder.with_models(my_empirical_models)
cfg = builder.build()
report = builder.report()

Each stage method mutates the builder in place and returns self so calls can be chained.

from_fasta(*, v_fasta, j_fasta, d_fasta=None, c_fasta=None, chain_type) classmethod

Build a builder from FASTA inputs.

v_fasta and j_fasta are required; d_fasta is required only when the chain type has a D segment (BCR_HEAVY / TCR_BETA / TCR_DELTA). c_fasta is accepted but the parsed C alleles are not yet wired into the resulting cartridge — v1 limits to V/D/J authoring. Records dropped during parsing land in :attr:CartridgeBuildReport.rejected.

Each *_fasta argument can be a path-like, an open text file, or a raw FASTA string (a string containing a newline and starting with > is parsed directly).

infer_identity(*, species=None, locus=None, reference_set=None, name=None, source='ReferenceCartridgeBuilder')

Populate the cartridge's identity / metadata plane.

species / locus / reference_set are user-supplied — none of these can be reliably inferred from FASTA alone, so the audit (§7) requires explicit input. When locus is omitted the conventional label is derived from the chain type (BCR_HEAVY → "IGH", etc.).

source is recorded on every parsed allele's .source field so downstream consumers can identify cartridges produced by this builder vs the bundled OGRDB / IMGT loaders.

infer_v_subregions()

Derive per-V-allele IMGT subregion intervals.

Walks every V allele with a non-empty gapped_seq and runs :func:compute_v_region_boundaries, attaching the resulting {label: (start, end)} dict to allele.subregions. Alleles without gapped_seq (or with a derivation that raises) are left unset and counted in the per-stage report.

Idempotent — calling twice re-derives and overwrites the previous output, with a replaced=True flag on the report entry.

with_rules(reference_rules)

Attach an explicit :class:ReferenceRulesSpec.

The user-supplied spec is validated immediately so an author's bug surfaces at build-stage time, not at compile time. The report records the rule fields the spec defines.

with_models(reference_models)

Attach an explicit :class:ReferenceEmpiricalModels.

The supplied bundle is validated against the chain type (D-end keys rejected on VJ chains, etc.). The report records which typed planes are populated.

build()

Assemble and return a validated :class:DataConfig.

The cartridge is finalised with:

• allele dicts populated from FASTA.
• metadata from :meth:infer_identity (or a built-in stub when :meth:infer_identity was never called).
• reference_rules / reference_models when those stages ran.
• build_report populated with the audit trail + a manifest snapshot + the post-build checksum.

Final step calls :meth:DataConfig.verify_integrity so a malformed cartridge surfaces at build time, not at :func:Experiment.on time. The build report is attached before integrity check so :attr:build_report is consistent regardless of whether the check passes.

report()

Return the accumulated :class:CartridgeBuildReport.