vdjtools 2.0.0a2__tar.gz → 2.2.0__tar.gz

{vdjtools-2.0.0a2 → vdjtools-2.2.0}/.gitignore

@@ -34,6 +34,9 @@ docs/_build/
 *.iml
 .DS_Store
 
+# Claude Code local state (session config + nested agent worktrees — never commit)
+.claude/
+
 # scratch
 tmp/
 

{vdjtools-2.0.0a2 → vdjtools-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: vdjtools
-Version: 2.0.0a2
+Version: 2.2.0
 Summary: TCR/BCR repertoire analysis — Pgen/generation/inference, diversity, overlap, biomarkers (Python + C++)
 Keywords: immunology,tcr,bcr,airr,repertoire,pgen,olga,igor,bioinformatics
 Author-Email: Mikhail Shugay <mikhail.shugay@gmail.com>
@@ -18,6 +18,7 @@ Requires-Python: >=3.10
 Requires-Dist: polars>=1.0
 Requires-Dist: numpy
 Requires-Dist: scipy
+Requires-Dist: typer>=0.12
 Provides-Extra: model
 Requires-Dist: arda-mapper>=2.5; extra == "model"
 Provides-Extra: overlap
@@ -31,8 +32,6 @@ Requires-Dist: scikit-learn; extra == "sc"
 Requires-Dist: pyyaml; extra == "sc"
 Requires-Dist: anndata; extra == "sc"
 Requires-Dist: huggingface_hub; extra == "sc"
-Provides-Extra: cli
-Requires-Dist: typer>=0.12; extra == "cli"
 Provides-Extra: examples
 Requires-Dist: marimo; extra == "examples"
 Requires-Dist: huggingface_hub; extra == "examples"
@@ -56,7 +55,6 @@ Requires-Dist: pybind11>=2.12; extra == "dev"
 Provides-Extra: all
 Requires-Dist: arda-mapper>=2.5; extra == "all"
 Requires-Dist: vdjmatch>=0.0.1; extra == "all"
-Requires-Dist: typer>=0.12; extra == "all"
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -88,9 +86,12 @@ Built on the antigenomics ecosystem:
 [vdjmatch](https://github.com/antigenomics/vdjmatch) (overlap + TCRnet),
 [arda](https://github.com/antigenomics/arda) (AIRR annotation + markup repair).
 
-> **Status: v2.0.0 under active development.** The legacy v1.x tool lives on the
-> [`legacy-1.x`](https://github.com/antigenomics/vdjtools/tree/legacy-1.x) branch and its
-> releases remain available under the repository tags (`v0.0.1` … `1.2.1`).
+> **Status: `v2.2.0`** — the native V(D)J model engine plus the full analytics suite (diversity,
+> overlap/TCRnet, preprocessing, biomarkers, single-cell), CDR features, and legacy-format ingestion
+> (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR). Clonotype columns follow the AIRR
+> **junction** convention (`junction_nt` / `junction_aa`). The legacy v1.x tool lives on the
+> [`legacy-1.x`](https://github.com/antigenomics/vdjtools/tree/legacy-1.x) branch and its releases
+> remain available under the repository tags (`v0.0.1` … `1.2.1`).
 
 ## Install
 
@@ -117,17 +118,95 @@ pip install -e ".[dev,test]"          # builds the _core C++ extension
 
 Or run the bootstrap script: `bash setup.sh --dev-parents --tests`.
 
-## Capabilities (rolling out by phase — see [ROADMAP.md](ROADMAP.md))
+## Quickstart — recombination model engine
 
-- **Model** — native V(D)J recombination model: generation probability (Pgen), sequence
-  generation, and EM model inference. Supersedes OLGA and IGoR: arda-driven scenario
-  enumeration, polars marginal tables, D-D tandem support, and a native (pybind11) Pgen/EM core.
+Precomputed models for all **7 human loci** ship in the wheel — no OLGA or download needed:
+
+```python
+from vdjtools.model import load_bundled, native
+from vdjtools.model.generate import generate
+
+model = load_bundled("TRB", source="olga")     # or source="learned" (fit to real repertoires)
+
+native.pgen_nt(model, "TGTGCCAGCAGC...")        # nucleotide generation probability (native C++)
+native.pgen_aa(model, "CASSLAPGATNEKLFF")       # amino-acid Pgen (codon-marginalised)
+native.pgen_aa(model, "CASSLAPGATNEKLFF", mismatches=1)   # + the whole Hamming-1 ball
+native.pgen_aa_batch(model, seqs, mismatches=1, threads=0)  # Pgen over many CDR3s, thread-parallel (~11×)
+generate(model, 1000)                           # sample a repertoire -> polars DataFrame
+```
+
+Matches OLGA's Pgen to machine precision across all 7 loci, and adds tandem-D (D-D) support that
+OLGA/IGoR lack. Learn a model from your own out-of-frame reads with `model.infer.infer_native`.
+
+Explore any model's recombination **Bayes net** interactively (entropy, mutual information, marginals):
+
+```bash
+pip install "vdjtools[examples]"
+marimo edit notebooks/model_explorer.py
+```
+
+## Command line
+
+`pip install vdjtools` installs the `vdjtools` command — the model engine (OLGA/IGoR-style) and the
+repertoire analytics (over sample files or a metadata table, like the legacy tool):
+
+```bash
+# recombination model engine — built-in models for all 7 loci (no download)
+vdjtools models                                # list the bundled models
+vdjtools generate -m TRB -n 1000 -o gen.tsv    # sample sequences   (cf. olga-generate_sequences)
+vdjtools pgen seqs.tsv -m TRB -o pgen.tsv      # Pgen per CDR3       (cf. olga-compute_pgen)
+vdjtools pgen seqs.tsv -m TRB --mismatches 1   # + the Hamming-1 ball; --v-col/--j-col to condition
+
+# repertoire analytics — sample files, or a cohort via -m/--metadata + --base-dir
+vdjtools diversity      sampleA.tsv sampleB.tsv -o diversity.tsv
+vdjtools overlap        *.tsv -o overlap.tsv
+vdjtools segment-usage  *.tsv --segment v -o usage.tsv
+vdjtools spectratype    *.tsv -o spectra.tsv
+```
+
+Native vdjtools and AIRR Rearrangement inputs are auto-detected; every command writes TSV to `-o`
+(or stdout, so it pipes). Run `vdjtools <command> --help` for options.
+
+## Performance
+
+The Pgen / generation / EM / diversity hot paths are a native C++ (pybind11) core; everything else is
+polars. Amino-acid Pgen matches OLGA to machine precision (1e-15) across all 7 loci while being
+several times faster, and the built-in models keep the resident set small. Single thread, Apple M3
+(arm64), bundled human TRB model:
+
+| operation | throughput | vs OLGA |
+|---|---|---|
+| nucleotide Pgen (single-D VDJ) | **~0.5 ms/seq** | **9×** |
+| amino-acid Pgen | **~0.6–0.9 ms/seq** | **8.6×** |
+| Pgen + Hamming-1 ball (1 substitution) | **~15 ms/seq** | **8.7×** |
+| sequence generation | **~32 000 seq/s** | — |
+
+Nucleotide Pgen (via the same transfer-matrix DP as the aa path — an in-frame CDR3 is an aa query with
+one codon fixed per position) is exact vs OLGA across all loci. Batched Pgen / 1-mismatch over many
+CDR3s parallelises over sequences (`native.pgen_aa_batch`, **~11× on 16 cores**, bitwise-identical to
+the serial result); the EM E-step parallelises over reads (~6.7× on 8 threads); diversity/rarefaction
+run on a native iNEXT kernel (bootstrap + parallel batch). Memory
+stays light — **~63 MB** resident for `import vdjtools` plus one loaded model, **~123 MB** with all
+seven bundled models resident. Reproduce with `appendix/bench_pgen.py` and the `test_*_benchmark.py`
+suites (`RUN_BENCHMARK=1`).
+
+## Capabilities (see [ROADMAP.md](ROADMAP.md) and the [API reference](https://docs.isalgo.dev/vdjtools/))
+
+- **IO** — canonical clonotype frame on AIRR **junction** columns (`junction_nt` / `junction_aa`);
+  readers for native vdjtools, AIRR Rearrangement TSV, and Parquet, plus format-detecting converters
+  for MiXcr (v1/2 + v3/4), MiGec, Adaptive immunoSEQ (v1/v2), IMGT/HighV-QUEST, Vidjil, and RTCR
+  ([`vdjtools.io.convert`](python/vdjtools/io/convert.py)); metadata-driven batch + hive-partitioned cohorts.
+- **Model** — native V(D)J recombination model: generation probability (Pgen — nt, aa,
+  1-mismatch, V/J-agnostic, **thread-parallel batch**), sequence generation, and EM inference, all in a
+  native (pybind11) core. Supersedes OLGA and IGoR: arda-driven scenario enumeration, polars marginal
+  tables, read-parallelised EM, and **tandem-D (D-D)** support. Concordant with OLGA across all 7 loci;
+  precomputed OLGA + real-data-learned models bundled ([`load_bundled`](python/vdjtools/model/bundled.py)).
 - **Stats** — diversity (Chao1/Shannon/Simpson/…), spectratype, V/J/VJ usage.
 - **Features** — CDR physicochemical profiles, k-mer / V+k-mer summaries.
-- **Overlap** — sample overlap and TCRnet (via vdjmatch/seqtree).
+- **Overlap** — sample overlap and TCRnet (via vdjmatch/seqtree), similarity-aware overlap, clustering.
 - **Preprocess** — downsampling, error-correction, VJ-usage batch-effect correction, pooling/joining.
 - **Biomarker** — incidence-based association (Fisher) vs HLA / condition / chain-pairing; metaclonotypes.
-- **Single-cell** — AIRR Cell / 10x interoperability.
+- **Single-cell** — AIRR Cell / 10x interoperability, chain pairing + QC, and paired α/β Pgen.
 
 ## License
 

vdjtools-2.2.0/README.md

@@ -0,0 +1,154 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/vdjtools_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/vdjtools_light.svg">
+    <!-- Absolute PNG fallback: PyPI strips <picture>/<source> and cannot render a relative or
+         raw-served SVG, so the logo must be an absolute-URL raster here. GitHub uses the SVG sources. -->
+    <img alt="vdjtools" src="https://raw.githubusercontent.com/antigenomics/vdjtools/master/assets/vdjtools_dark.png" width="320">
+  </picture>
+</p>
+
+<h1 align="center">vdjtools — immune-repertoire analysis</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/vdjtools/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vdjtools"></a>
+  <a href="https://github.com/antigenomics/vdjtools/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/antigenomics/vdjtools/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://docs.isalgo.dev/vdjtools/"><img alt="docs" src="https://github.com/antigenomics/vdjtools/actions/workflows/docs.yml/badge.svg"></a>
+  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-blue">
+  <img alt="license" src="https://img.shields.io/badge/license-GPLv3-green">
+</p>
+
+TCR/BCR immune-repertoire analysis — a clean-room **Python + C++** rewrite of the legacy
+Groovy/Java [vdjtools](https://doi.org/10.1371/journal.pcbi.1004503), standardised on the
+**AIRR schema** and **polars** DataFrames with minimal object-orientation.
+
+Built on the antigenomics ecosystem:
+[seqtree](https://github.com/antigenomics/seqtree) (fuzzy search / e-value engine),
+[vdjmatch](https://github.com/antigenomics/vdjmatch) (overlap + TCRnet),
+[arda](https://github.com/antigenomics/arda) (AIRR annotation + markup repair).
+
+> **Status: `v2.2.0`** — the native V(D)J model engine plus the full analytics suite (diversity,
+> overlap/TCRnet, preprocessing, biomarkers, single-cell), CDR features, and legacy-format ingestion
+> (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR). Clonotype columns follow the AIRR
+> **junction** convention (`junction_nt` / `junction_aa`). The legacy v1.x tool lives on the
+> [`legacy-1.x`](https://github.com/antigenomics/vdjtools/tree/legacy-1.x) branch and its releases
+> remain available under the repository tags (`v0.0.1` … `1.2.1`).
+
+## Install
+
+```bash
+pip install vdjtools
+```
+
+Prebuilt wheels ship for CPython 3.10–3.13 on Linux, macOS (Apple Silicon), and Windows; the
+native `_core` C++ extension is bundled (the source distribution compiles it on install). The
+pure-analytics paths (diversity / spectratype / usage / overlap) work out of the box; the model
+and annotation paths additionally pull in [arda](https://github.com/antigenomics/arda) (MMseqs2):
+
+```bash
+pip install "vdjtools[model]"
+```
+
+### Development
+
+```bash
+conda env create -f environment.yml   # python + mmseqs2 (arda backend) + C++ toolchain
+conda activate vdjtools
+pip install -e ".[dev,test]"          # builds the _core C++ extension
+```
+
+Or run the bootstrap script: `bash setup.sh --dev-parents --tests`.
+
+## Quickstart — recombination model engine
+
+Precomputed models for all **7 human loci** ship in the wheel — no OLGA or download needed:
+
+```python
+from vdjtools.model import load_bundled, native
+from vdjtools.model.generate import generate
+
+model = load_bundled("TRB", source="olga")     # or source="learned" (fit to real repertoires)
+
+native.pgen_nt(model, "TGTGCCAGCAGC...")        # nucleotide generation probability (native C++)
+native.pgen_aa(model, "CASSLAPGATNEKLFF")       # amino-acid Pgen (codon-marginalised)
+native.pgen_aa(model, "CASSLAPGATNEKLFF", mismatches=1)   # + the whole Hamming-1 ball
+native.pgen_aa_batch(model, seqs, mismatches=1, threads=0)  # Pgen over many CDR3s, thread-parallel (~11×)
+generate(model, 1000)                           # sample a repertoire -> polars DataFrame
+```
+
+Matches OLGA's Pgen to machine precision across all 7 loci, and adds tandem-D (D-D) support that
+OLGA/IGoR lack. Learn a model from your own out-of-frame reads with `model.infer.infer_native`.
+
+Explore any model's recombination **Bayes net** interactively (entropy, mutual information, marginals):
+
+```bash
+pip install "vdjtools[examples]"
+marimo edit notebooks/model_explorer.py
+```
+
+## Command line
+
+`pip install vdjtools` installs the `vdjtools` command — the model engine (OLGA/IGoR-style) and the
+repertoire analytics (over sample files or a metadata table, like the legacy tool):
+
+```bash
+# recombination model engine — built-in models for all 7 loci (no download)
+vdjtools models                                # list the bundled models
+vdjtools generate -m TRB -n 1000 -o gen.tsv    # sample sequences   (cf. olga-generate_sequences)
+vdjtools pgen seqs.tsv -m TRB -o pgen.tsv      # Pgen per CDR3       (cf. olga-compute_pgen)
+vdjtools pgen seqs.tsv -m TRB --mismatches 1   # + the Hamming-1 ball; --v-col/--j-col to condition
+
+# repertoire analytics — sample files, or a cohort via -m/--metadata + --base-dir
+vdjtools diversity      sampleA.tsv sampleB.tsv -o diversity.tsv
+vdjtools overlap        *.tsv -o overlap.tsv
+vdjtools segment-usage  *.tsv --segment v -o usage.tsv
+vdjtools spectratype    *.tsv -o spectra.tsv
+```
+
+Native vdjtools and AIRR Rearrangement inputs are auto-detected; every command writes TSV to `-o`
+(or stdout, so it pipes). Run `vdjtools <command> --help` for options.
+
+## Performance
+
+The Pgen / generation / EM / diversity hot paths are a native C++ (pybind11) core; everything else is
+polars. Amino-acid Pgen matches OLGA to machine precision (1e-15) across all 7 loci while being
+several times faster, and the built-in models keep the resident set small. Single thread, Apple M3
+(arm64), bundled human TRB model:
+
+| operation | throughput | vs OLGA |
+|---|---|---|
+| nucleotide Pgen (single-D VDJ) | **~0.5 ms/seq** | **9×** |
+| amino-acid Pgen | **~0.6–0.9 ms/seq** | **8.6×** |
+| Pgen + Hamming-1 ball (1 substitution) | **~15 ms/seq** | **8.7×** |
+| sequence generation | **~32 000 seq/s** | — |
+
+Nucleotide Pgen (via the same transfer-matrix DP as the aa path — an in-frame CDR3 is an aa query with
+one codon fixed per position) is exact vs OLGA across all loci. Batched Pgen / 1-mismatch over many
+CDR3s parallelises over sequences (`native.pgen_aa_batch`, **~11× on 16 cores**, bitwise-identical to
+the serial result); the EM E-step parallelises over reads (~6.7× on 8 threads); diversity/rarefaction
+run on a native iNEXT kernel (bootstrap + parallel batch). Memory
+stays light — **~63 MB** resident for `import vdjtools` plus one loaded model, **~123 MB** with all
+seven bundled models resident. Reproduce with `appendix/bench_pgen.py` and the `test_*_benchmark.py`
+suites (`RUN_BENCHMARK=1`).
+
+## Capabilities (see [ROADMAP.md](ROADMAP.md) and the [API reference](https://docs.isalgo.dev/vdjtools/))
+
+- **IO** — canonical clonotype frame on AIRR **junction** columns (`junction_nt` / `junction_aa`);
+  readers for native vdjtools, AIRR Rearrangement TSV, and Parquet, plus format-detecting converters
+  for MiXcr (v1/2 + v3/4), MiGec, Adaptive immunoSEQ (v1/v2), IMGT/HighV-QUEST, Vidjil, and RTCR
+  ([`vdjtools.io.convert`](python/vdjtools/io/convert.py)); metadata-driven batch + hive-partitioned cohorts.
+- **Model** — native V(D)J recombination model: generation probability (Pgen — nt, aa,
+  1-mismatch, V/J-agnostic, **thread-parallel batch**), sequence generation, and EM inference, all in a
+  native (pybind11) core. Supersedes OLGA and IGoR: arda-driven scenario enumeration, polars marginal
+  tables, read-parallelised EM, and **tandem-D (D-D)** support. Concordant with OLGA across all 7 loci;
+  precomputed OLGA + real-data-learned models bundled ([`load_bundled`](python/vdjtools/model/bundled.py)).
+- **Stats** — diversity (Chao1/Shannon/Simpson/…), spectratype, V/J/VJ usage.
+- **Features** — CDR physicochemical profiles, k-mer / V+k-mer summaries.
+- **Overlap** — sample overlap and TCRnet (via vdjmatch/seqtree), similarity-aware overlap, clustering.
+- **Preprocess** — downsampling, error-correction, VJ-usage batch-effect correction, pooling/joining.
+- **Biomarker** — incidence-based association (Fisher) vs HLA / condition / chain-pairing; metaclonotypes.
+- **Single-cell** — AIRR Cell / 10x interoperability, chain pairing + QC, and paired α/β Pgen.
+
+## License
+
+GPL-3.0-or-later.

{vdjtools-2.0.0a2 → vdjtools-2.2.0}/include/vdjtools/model.hpp

@@ -64,6 +64,13 @@ double pgen_aa(const PackedModel& m, const std::string& aa, int v_idx, int j_idx
 // via the inclusion-exclusion identity over per-position wildcards. v_idx/j_idx as above.
 double pgen_aa_hamming1(const PackedModel& m, const std::string& aa, int v_idx, int j_idx);
 
+// Batch aa Pgen over many sequences, parallelized across sequences (mismatches: 0 = exact,
+// 1 = Hamming-1 ball). Bitwise-identical to the per-sequence calls. Per-sequence v/j indices;
+// empty v_idxs/j_idxs → all -1 (gene-agnostic). nthreads=0 → auto (hw-2).
+std::vector<double> pgen_aa_batch(const PackedModel& m, const std::vector<std::string>& seqs,
+                                  const std::vector<int>& v_idxs, const std::vector<int>& j_idxs,
+                                  int mismatches, int nthreads);
+
 // EM soft counts — one accumulator per event realization, laid out like the PackedModel prob
 // arrays so the Python M-step can renormalize them directly.
 struct Counts {
@@ -85,12 +92,15 @@ Counts make_counts(const PackedModel& m);
 // in a fixed order); 0 = auto (hardware_concurrency - 2). Small batches run single-threaded so their
 // result stays bitwise-identical. The soft counts are exact regardless of thread count (up to the
 // float summation order, which the fixed reduction keeps deterministic per ``nthreads``).
+// ``dd_allowed`` optionally gates the tandem (n_D=2) E-step per read (1 = may be tandem, 0 = single-D
+// only); empty = every read may be tandem. Used to anchor D-D learning to arda's tandem calls.
 double estep_batch(const PackedModel& m,
                    const std::vector<std::vector<int8_t>>& seqs,
                    const std::vector<std::vector<int>>& vmasks,
                    const std::vector<std::vector<int>>& jmasks,
                    const std::vector<std::vector<int>>& dmasks,
                    Counts& counts,
-                   int nthreads = 0);
+                   int nthreads = 0,
+                   const std::vector<int>& dd_allowed = {});
 
 }  // namespace vdjtools

vdjtools-2.2.0/notebooks/model_explorer.py

@@ -0,0 +1,142 @@
+# vdjtools — interactive recombination-model explorer.
+# Reactive marimo app: pick a locus and model source, see its Bayes net (nodes = marginal entropy H,
+# edges = mutual information I), the per-event entropy / MI tables, a marginal distribution, and an
+# OLGA-vs-learned comparison. Run with:  marimo edit notebooks/model_explorer.py
+import marimo
+
+__generated_with = "0.23.14"
+app = marimo.App(width="medium")
+
+
+@app.cell
+def _():
+    import marimo as mo
+    return (mo,)
+
+
+@app.cell
+def _(mo):
+    import subprocess
+
+    import matplotlib.pyplot as plt
+    import polars as pl
+
+    from vdjtools.model import analyze, list_bundled, load_bundled
+    return analyze, list_bundled, load_bundled, mo, pl, plt, subprocess
+
+
+@app.cell
+def _(mo):
+    mo.md(
+        """
+        # V(D)J recombination model explorer
+
+        Explore any bundled recombination model as a **Bayes net** — nodes are recombination events
+        (sized/annotated by their marginal Shannon entropy *H*), edges are the conditioning
+        dependencies (annotated by mutual information *I*). Compare the **OLGA** bootstrap models to
+        the **EM-learned** models fit to real out-of-frame repertoires.
+        """
+    )
+    return
+
+
+@app.cell
+def _(list_bundled, mo):
+    avail = list_bundled()
+    source = mo.ui.dropdown(list(avail), value="olga", label="Model source")
+    return avail, source
+
+
+@app.cell
+def _(avail, mo, source):
+    loci = avail.get(source.value, [])
+    locus = mo.ui.dropdown(loci, value=(loci[0] if loci else None), label="Locus")
+    mo.hstack([source, locus], justify="start", gap=2)
+    return (locus,)
+
+
+@app.cell
+def _(load_bundled, locus, mo, source):
+    mo.stop(locus.value is None, mo.md("*No bundled models found — build them first.*"))
+    model = load_bundled(locus.value, source.value)
+    mo.md(f"**{locus.value}** · *{source.value}* · chain **{model.chain_type}** · "
+          f"{model.genomic['genes_v'].height} V / {model.genomic['genes_j'].height} J genes")
+    return (model,)
+
+
+@app.cell
+def _(analyze, mo, model, subprocess):
+    # Render the Bayes net to inline SVG via the graphviz `dot` CLI (no python-graphviz dep).
+    dot = analyze.bayes_net_dot(model)
+    try:
+        svg = subprocess.run(["dot", "-Tsvg"], input=dot, capture_output=True, text=True, check=True).stdout
+        svg = svg[svg.index("<svg"):]  # drop the <?xml?> / <!DOCTYPE> preamble for clean inline embedding
+        bn = mo.Html(svg)
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        bn = mo.md("`dot` (graphviz) not found — showing the DOT source instead:").callout("warn")
+        bn = mo.vstack([bn, mo.plain_text(dot)])
+    mo.vstack([mo.md("### Bayes net &nbsp; *(node = event · H bits; edge = conditioning · I bits)*"), bn])
+    return
+
+
+@app.cell
+def _(analyze, mo, model):
+    ent = analyze.entropy_table(model)
+    mi = analyze.mutual_information(model)
+    mo.hstack([
+        mo.vstack([mo.md("### Marginal entropy *H* (bits)"), ent]),
+        mo.vstack([mo.md("### Mutual information *I* (bits)"), mi]),
+    ], widths=[1, 1], gap=2)
+    return
+
+
+@app.cell
+def _(mo, model):
+    # Pick a marginal to plot (insertion length or a gene-usage table).
+    plottable = [e for e in ("vd_ins", "dj_ins", "vj_ins", "dd_ins", "d_del", "n_d", "v_choice", "j_choice")
+                 if e in model.tables]
+    event = mo.ui.dropdown(plottable, value=plottable[0] if plottable else None, label="Marginal to plot")
+    event
+    return (event,)
+
+
+@app.cell
+def _(event, mo, model, plt):
+    mo.stop(event.value is None)
+    df = model.tables[event.value]
+    fig, ax = plt.subplots(figsize=(7, 3))
+    cols = df.columns
+    if "length" in cols:
+        ax.bar(df["length"], df["p"]); ax.set_xlabel("insertion length (nt)")
+    elif "n_d" in cols:
+        ax.bar(df["n_d"].cast(str), df["p"]); ax.set_xlabel("number of D segments")
+    elif "ndel5" in cols:  # 2D deletion: marginal over 3'
+        agg = df.group_by("ndel5").agg(__import__("polars").col("p").sum()).sort("ndel5")
+        ax.bar(agg["ndel5"], agg["p"]); ax.set_xlabel("D 5' deletion (nt; neg = P-nt)")
+    else:  # gene usage: top 15 by probability
+        top = df.sort("p", descending=True).head(15)
+        gcol = [c for c in cols if c.endswith("_allele")][-1]
+        ax.barh(top[gcol].to_list()[::-1], top["p"].to_list()[::-1]); ax.set_xlabel("P")
+    ax.set_ylabel("probability"); ax.set_title(f"{event.value}"); fig.tight_layout()
+    ax
+    return
+
+
+@app.cell
+def _(analyze, avail, load_bundled, locus, mo):
+    # OLGA vs learned entropy side-by-side, when both are available for this locus.
+    both = {s: load_bundled(locus.value, s) for s in ("olga", "learned")
+            if locus.value in avail.get(s, [])}
+    if len(both) == 2:
+        import polars as _pl
+        cmp = analyze.compare_entropy(both).with_columns(
+            (_pl.col("learned") - _pl.col("olga")).round(3).alias("Δ (learned−olga)"))
+        out = mo.vstack([mo.md("### OLGA vs learned — marginal entropy *H* (bits)"), cmp])
+    else:
+        out = mo.md("*Load a locus present in both `olga` and `learned` to see the comparison.*").callout()
+    out
+    return
+
+
+if __name__ == "__main__":
+    app.run()

{vdjtools-2.0.0a2 → vdjtools-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "vdjtools"  # if the PyPI name is taken, fall back to a distinct dist name (cf. arda -> arda-mapper)
-version = "2.0.0a2"
+version = "2.2.0"
 description = "TCR/BCR repertoire analysis — Pgen/generation/inference, diversity, overlap, biomarkers (Python + C++)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,21 +26,24 @@ dependencies = [
     "polars>=1.0",
     "numpy",
     "scipy",
+    "typer>=0.12",  # the `vdjtools` CLI (Phase 8) is a core entry point
 ]
 
+[project.scripts]
+vdjtools = "vdjtools.cli:app"
+
 [project.optional-dependencies]
 model = ["arda-mapper>=2.5"]           # Phase 1: scenario enumeration + markup repair (brings mmseqs2)
 overlap = ["vdjmatch>=0.0.1", "seqtree>=0.3", "scikit-learn"]  # Phase 4: overlap + TCRnet (brings the seqtree engine); sklearn for MDS clustering; seqtree for similarity-weighted (TINA) overlap
 preprocess = ["seqtree>=0.3"]          # Phase 5: freq-based error correction (near-neighbour search)
 sc = ["scikit-learn", "pyyaml", "anndata", "huggingface_hub"]  # Phase 7: single-cell — sklearn for cluster_eval contingency, pyyaml for AIRR Cell export, anndata for the scverse bridge (to_anndata), HF for the dCODE benchmark fetch (tests only)
-cli = ["typer>=0.12"]                  # Phase 8
 examples = ["marimo", "huggingface_hub", "matplotlib", "scikit-learn"]  # example notebooks (scipy is a base dep)
 oracle = ["olga"]                      # Pgen cross-check oracle (tests only)
 test = ["pytest>=7.4", "pytest-cov"]
 bench = ["huggingface_hub"]  # test-only: real-data fetch; never a runtime dep
 docs = ["sphinx>=7", "pydata-sphinx-theme>=0.15", "nbsphinx"]
 dev = ["ruff", "pytest>=7.4", "pybind11>=2.12"]
-all = ["arda-mapper>=2.5", "vdjmatch>=0.0.1", "typer>=0.12"]
+all = ["arda-mapper>=2.5", "vdjmatch>=0.0.1"]
 
 [project.urls]
 Homepage = "https://github.com/antigenomics/vdjtools"

{vdjtools-2.0.0a2 → vdjtools-2.2.0}/python/vdjtools/__init__.py

@@ -13,5 +13,5 @@ vdjmatch/seqtree) until a feature that needs them is used.
 """
 from ._core import hamming
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"
 __all__ = ["hamming", "__version__"]

vdjtools-2.2.0/python/vdjtools/biomarker/__init__.py

@@ -0,0 +1,8 @@
+"""vdjtools.biomarker — Incidence-based association (Fisher) and metaclonotype grouping."""
+from .fisher import fisher_association
+from .metaclonotype import metaclonotypes
+
+__all__ = [
+    "fisher_association",   # Fisher-exact clonotype-incidence vs phenotype association
+    "metaclonotypes",       # edit-scope metaclonotype grouping (1mm matching)
+]