Examples gallery

Two offline workflows show the path from raw inputs to CLI tables. Start with annotation, then compare detailed evidence. Open Notebooks gallery for rendered previews and notebook source downloads.

Tutorial · four rows and two pairs

Annotate a cohort

Run metadata and linked-pair inputs. Inspect identities, selections, invalid genes and the incomplete pair.

How-to · matched query identities

Compare geometries

Export fresh stem4 and vcdr12 evidence and join their full pMHC keys.

These examples run tiny synthetic raw inputs against a supplied offline reference. DEMO_A and DEMO_B are demonstration labels, not experimental binding truth. Every result is produced by the installed CLI; notebooks analyze only its final tables. There are no persisted feature inputs, skip/resume paths or reused predictions.

Download the release source ZIP or clone the repository and use its complete examples directory, keeping its inputs directory beside the scripts and notebooks. The source distribution also includes these files. Install vdjmatch in an isolated environment and activate it so vdjmatch is on PATH. Both scripts default to one native thread.

Annotation tutorial

From the repository root, choose a new output directory:

sh examples/annotate.sh annotation-demo

The metadata cohort has four single-chain rows across two samples. The wide paired input has two receptors, including one missing beta chain. Source identities and missing/invalid dispositions remain in *.queries.tsv and *.selection.tsv. *.manifest.json records the reference, scoring and resources.

• Annotation shell script

• Annotation notebook

• Read the annotation notebook

• Offline synthetic reference

• Sample metadata

• First AIRR sample

• Second AIRR sample

• Wide paired sample

Geometry comparison how-to

sh examples/compare.sh comparison-demo

This runs default stem4 and the retained advanced vcdr12 geometry, both with --exclude-exact --details and separate fresh output prefixes. The notebook joins detailed *.enrichment.tsv rows by source identity and complete pMHC key, then displays their continuous scores. Any arithmetic score delta is a geometry diagnostic, not an accuracy gain or calibrated comparison of score scales. It does not calculate scientific accuracy from demonstration labels or transfer calibration between geometries.

• Comparison shell script

• Comparison notebook

• Read the comparison notebook

Both scripts fail on nonzero CLI exit and reject an existing output directory. For another fresh run, choose another directory. Notebooks use a new temporary output directory each time and execute sys.executable -m vdjmatch.cli with check=True and a 120-second timeout. Open them from the repository root or examples directory. The notebook kernel and CLI therefore use the same Python environment and do not require a POSIX shell. Their committed cells contain no execution outputs. Documentation builds never execute notebooks.

For input formats and operational choices, see Work with releases and repertoires; for the meaning of scores and the distinction from binding probabilities, see Understand matching evidence. For all flags and library signatures, see Command-line interface and API reference.