Marginal junction generation probability

The pgen command computes the amino-acid generation probability of each full, anchor-inclusive AIRR junction_aa under an explicitly selected raw vdjtools model directory:

vdjmatch pgen input.airr.tsv --model-path /path/to/raw/model \
    --species human --locus TRA --threads 12 --output-prefix result

Use a model whose manifest matches the declared species and locus. The command loads and validates that directory directly; it neither selects a bundled model implicitly nor collapses its alleles. vdjtools.load_model applies its documented anchor repairs. The manifest records the consumed model-file hashes, model metadata, loader and native binary hashes, options, input hash, row dispositions and timing. No model download or new model fitting occurs.

This is marginal P(junction_aa): all V/J alleles and recombination scenarios in the model contribute, with zero allowed amino-acid mismatches. Input V/J annotations are preserved but do not condition the probability. This is neither an antigen specificity probability nor a probability calibrated from the annotation score. The model’s generative mass does not include post-recombination selection merely because the input repertoire was observed or productive. Paired input remains one result per chain row; the command does not infer a joint pair probability.

result.scores.tsv preserves all raw rows, metadata and supplied unique, non-null query_id values. If absent, query_id is the zero-based raw row ordinal. junction_aa_normalized records uppercase, whitespace-stripped input; anchors are never fabricated from bare cdr3_aa. Canonical amino-acid junctions of the selected species/locus are sent to one native batch. Missing locus metadata uses the explicit --locus; missing V/J calls do not prevent marginal Pgen. Explicitly different species/loci, missing junctions and noncanonical sequences remain in the table with an explanatory status and null probabilities.

pgen is the marginal probability and log10_pgen is its base-10 logarithm when positive. available is true for a valid numeric result, including zero. zero_mass records a returned zero, with null logarithm; it does not distinguish impossible model mass from numerical underflow. Negative, nonfinite or greater-than-one native probabilities fail the command instead of being clipped or exported. result.manifest.json records the exact computation contract. Positive --threads caps native workers and the CLI’s table-thread budget; no outer worker pool or computed-intermediate cache is used.

VDJdb reference observations

Use --vdjdb to read a frozen local legacy or rich reference ZIP through the same database loader used for annotation:

vdjmatch pgen reference.zip --vdjdb --model-path /path/to/raw/model \
    --species human --locus TRA --threads 12 --output-prefix reference-tra

The loader selects the declared receptor species and locus. Every normalized reference observation in that selection is retained, including repeated junctions and its reference_id, peptide, MHC and other metadata. The command projects internal cdr3/v/j/gene fields to junction_aa/v_call/j_call/locus without renaming or dropping the original columns. Legacy VDJdb cdr3 is a full anchor-inclusive junction under the database loader’s source contract. Nested rich metadata is exported as JSON cells using the existing flat-table exporter. query_id is the selected loader row ordinal when not supplied.

The manifest declares input_format=vdjdb and records db.provenance together with the reference loader/normalizer hashes. Row counts refer to the selected normalized reference observations, rather than all records in the archive. Pgen remains marginal over the model’s V/J alleles; database V/J annotations, epitopes and study metadata do not condition it. Local reference tables and release directories are also supported by the existing loader. AIRR remains the default when --vdjdb is absent.