vdjtools 2.2.0__tar.gz → 2.2.1__tar.gz

{vdjtools-2.2.0 → vdjtools-2.2.1}/.gitignore

@@ -45,3 +45,8 @@ examples/.data/
 
 # marimo session/run cache
 __marimo__/
+
+# coverage artifacts
+.coverage
+.coverage.*
+htmlcov/

{vdjtools-2.2.0 → vdjtools-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: vdjtools
-Version: 2.2.0
+Version: 2.2.1
 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>
@@ -88,7 +88,7 @@ Built on the antigenomics ecosystem:
 
 > **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
+> (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR, TRUST4, arda). 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`).
@@ -167,6 +167,48 @@ 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.
 
+## Analytics (Python API)
+
+Every reader returns one canonical `polars` clonotype frame (AIRR **junction** columns), and every
+analysis function takes and returns such frames — so results chain together and drop straight into
+plotting. A tour of the analysis modules (full runnable walkthrough in the
+[**User guide**](https://docs.isalgo.dev/vdjtools/usage.html)):
+
+```python
+from vdjtools import io as vio, stats, features, overlap, preprocess
+
+# load (auto-detects MiXcr / immunoSEQ / AIRR / native / … and converts), or a whole cohort:
+sample = vio.read("clones.tsv")
+cohort = vio.read_samples(vio.read_metadata("metadata.txt"), base_dir="samples/")
+
+# diversity, rarefaction, segment usage, spectratype
+stats.diversity_stats(sample)                 # observed, Chao1, Shannon, inverse-Simpson, d50, …
+stats.inext(sample, q=(0, 1, 2))              # Hill-number rarefaction/extrapolation + bootstrap CIs
+stats.segment_usage(sample, "v")              # V (or "j") usage;  stats.spectratype(sample)
+
+# CDR3 physicochemistry & k-mers
+features.physchem_profile(sample, region="all")
+
+# repertoire overlap & TCRnet (fuzzy/similarity/TCRnet via the [overlap] engine)
+overlap.overlap_metrics(sampleA, sampleB)     # F / D / Jaccard / Morisita-Horn …
+overlap.tcrnet(sample)                         # per-clonotype neighbourhood enrichment
+
+# preprocessing: downsample to a common depth, error-correct, filter, pool
+preprocess.downsample(sample, 100_000)
+preprocess.correct(preprocess.filter_functional(sample))
+```
+
+Incidence-based biomarkers (Fisher association, Emerson-2017 design) and single-cell paired-chain
+Pgen are one call each:
+
+```python
+from vdjtools.biomarker import fisher_association
+from vdjtools import sc
+
+fisher_association(cohort, phenotype, pheno_col="cmv")   # enriched/depleted clonotypes + p-values
+sc.paired_pgen(sc.pair_chains(sc.read_10x("filtered_contig_annotations.csv")))  # pgen_alpha·pgen_beta
+```
+
 ## Performance
 
 The Pgen / generation / EM / diversity hot paths are a native C++ (pybind11) core; everything else is
@@ -190,11 +232,12 @@ stays light — **~63 MB** resident for `import vdjtools` plus one loaded model,
 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/))
+## Capabilities (see the [User guide](https://docs.isalgo.dev/vdjtools/usage.html), the [API reference](https://docs.isalgo.dev/vdjtools/), and [ROADMAP.md](ROADMAP.md))
 
 - **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
+  for MiXcr (v1/2 + v3/4, incl. C-gene / BCR isotype), MiGec, Adaptive immunoSEQ (v1/v2),
+  IMGT/HighV-QUEST, Vidjil, RTCR, TRUST4, and arda AIRR output
   ([`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

{vdjtools-2.2.0 → vdjtools-2.2.1}/README.md

@@ -29,7 +29,7 @@ Built on the antigenomics ecosystem:
 
 > **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
+> (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil, RTCR, TRUST4, arda). 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`).
@@ -108,6 +108,48 @@ 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.
 
+## Analytics (Python API)
+
+Every reader returns one canonical `polars` clonotype frame (AIRR **junction** columns), and every
+analysis function takes and returns such frames — so results chain together and drop straight into
+plotting. A tour of the analysis modules (full runnable walkthrough in the
+[**User guide**](https://docs.isalgo.dev/vdjtools/usage.html)):
+
+```python
+from vdjtools import io as vio, stats, features, overlap, preprocess
+
+# load (auto-detects MiXcr / immunoSEQ / AIRR / native / … and converts), or a whole cohort:
+sample = vio.read("clones.tsv")
+cohort = vio.read_samples(vio.read_metadata("metadata.txt"), base_dir="samples/")
+
+# diversity, rarefaction, segment usage, spectratype
+stats.diversity_stats(sample)                 # observed, Chao1, Shannon, inverse-Simpson, d50, …
+stats.inext(sample, q=(0, 1, 2))              # Hill-number rarefaction/extrapolation + bootstrap CIs
+stats.segment_usage(sample, "v")              # V (or "j") usage;  stats.spectratype(sample)
+
+# CDR3 physicochemistry & k-mers
+features.physchem_profile(sample, region="all")
+
+# repertoire overlap & TCRnet (fuzzy/similarity/TCRnet via the [overlap] engine)
+overlap.overlap_metrics(sampleA, sampleB)     # F / D / Jaccard / Morisita-Horn …
+overlap.tcrnet(sample)                         # per-clonotype neighbourhood enrichment
+
+# preprocessing: downsample to a common depth, error-correct, filter, pool
+preprocess.downsample(sample, 100_000)
+preprocess.correct(preprocess.filter_functional(sample))
+```
+
+Incidence-based biomarkers (Fisher association, Emerson-2017 design) and single-cell paired-chain
+Pgen are one call each:
+
+```python
+from vdjtools.biomarker import fisher_association
+from vdjtools import sc
+
+fisher_association(cohort, phenotype, pheno_col="cmv")   # enriched/depleted clonotypes + p-values
+sc.paired_pgen(sc.pair_chains(sc.read_10x("filtered_contig_annotations.csv")))  # pgen_alpha·pgen_beta
+```
+
 ## Performance
 
 The Pgen / generation / EM / diversity hot paths are a native C++ (pybind11) core; everything else is
@@ -131,11 +173,12 @@ stays light — **~63 MB** resident for `import vdjtools` plus one loaded model,
 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/))
+## Capabilities (see the [User guide](https://docs.isalgo.dev/vdjtools/usage.html), the [API reference](https://docs.isalgo.dev/vdjtools/), and [ROADMAP.md](ROADMAP.md))
 
 - **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
+  for MiXcr (v1/2 + v3/4, incl. C-gene / BCR isotype), MiGec, Adaptive immunoSEQ (v1/v2),
+  IMGT/HighV-QUEST, Vidjil, RTCR, TRUST4, and arda AIRR output
   ([`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

{vdjtools-2.2.0 → vdjtools-2.2.1}/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.2.0"
+version = "2.2.1"
 description = "TCR/BCR repertoire analysis — Pgen/generation/inference, diversity, overlap, biomarkers (Python + C++)"
 readme = "README.md"
 requires-python = ">=3.10"

{vdjtools-2.2.0 → vdjtools-2.2.1}/python/vdjtools/__init__.py

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

{vdjtools-2.2.0 → vdjtools-2.2.1}/python/vdjtools/io/__init__.py

@@ -6,11 +6,13 @@ from . import schema
 from .batch import iter_samples, read, read_metadata, read_samples, sniff_format
 from .cohort import ingest_cohort, scan_cohort
 from .convert import (
+    read_arda,
     read_imgt,
     read_immunoseq,
     read_migec,
     read_mixcr,
     read_rtcr,
+    read_trust4,
     read_vidjil,
 )
 from .read import read_airr, read_parquet, read_vdjtools
@@ -44,6 +46,8 @@ __all__ = [
     "read_imgt",
     "read_vidjil",
     "read_rtcr",
+    "read_trust4",
+    "read_arda",
     "read_metadata",
     "read_samples",
     "iter_samples",

{vdjtools-2.2.0 → vdjtools-2.2.1}/python/vdjtools/io/batch.py

@@ -21,6 +21,7 @@ _CONVERTERS = {
     "mixcr": convert.read_mixcr, "migec": convert.read_migec,
     "immunoseq": convert.read_immunoseq, "imgt": convert.read_imgt,
     "vidjil": convert.read_vidjil, "rtcr": convert.read_rtcr,
+    "trust4": convert.read_trust4, "arda": convert.read_arda,
 }
 
 
@@ -46,14 +47,16 @@ def sniff_format(path: str | os.PathLike) -> str:
         path: Path to a clonotype table.
 
     Returns:
-        ``"parquet"`` if the path ends in ``.parquet`` / ``.pq`` (detected by
-        extension, without opening the file), ``"vdjtools"`` if the header looks
-        like the native vdjtools table (``cdr3aa`` / ``count`` + ``cdr3nt``), or
-        ``"airr"`` if it looks like AIRR Rearrangement (``v_call`` /
-        ``junction_aa`` / ``cdr3_aa``).
+        The detected format string, one of: ``"parquet"`` (``.parquet`` / ``.pq``
+        extension), ``"vidjil"`` (``.vidjil`` / ``.json`` or a leading ``{``),
+        ``"imgt"``, ``"migec"``, ``"rtcr"``, ``"mixcr"``, ``"immunoseq"``, ``"trust4"``
+        (each by its signature header columns), ``"arda"`` (AIRR + arda's ``d2_call``),
+        ``"vdjtools"`` (native table / MigMap — ``cdr3aa`` / ``count`` + ``cdr3nt``), or
+        ``"airr"`` (AIRR Rearrangement — ``v_call`` / ``junction_aa`` / ``junction_nt`` /
+        ``cdr3_aa``).
 
     Raises:
-        ValueError: If neither signature is recognised.
+        ValueError: If no known format signature is recognised.
     """
     if Path(path).suffix.lower() in (".parquet", ".pq"):
         return "parquet"
@@ -73,6 +76,12 @@ def sniff_format(path: str | os.PathLike) -> str:
     if "count (templates/reads)" in cols or ({"rearrangement", "amino_acid"} <= cols
                                              and "v_gene" in cols):
         return "immunoseq"
+    if "cid_full_length" in cols and "cdr3nt" in cols:
+        return "trust4"  # TRUST4 *_report.tsv (its own cid_full_length column)
+    # arda AIRR output — standard AIRR names plus arda's tandem-D ``d2_call`` column;
+    # match before plain AIRR so it routes to read_arda (nulls arda's ``""`` empty calls).
+    if "d2_call" in cols and cols & {"v_call", "junction_aa", "junction", "cdr3_aa"}:
+        return "arda"
     # Native vdjtools / migmap (cdr3nt/cdr3aa headers) and AIRR Rearrangement.
     if "cdr3aa" in cols or {"count", "cdr3nt"} <= cols:
         return "vdjtools"
@@ -86,10 +95,14 @@ def read(path: str | os.PathLike, fmt: str = "auto",
     """Read a clonotype table, auto-detecting the format by default.
 
     Args:
-        path: Path to a native vdjtools, AIRR Rearrangement, or Parquet table
-            (``.gz`` ok for the text formats).
+        path: Path to a native vdjtools, AIRR Rearrangement, or Parquet table, or a
+            third-party tool export (MiXcr, MiGec, immunoSEQ, IMGT/HighV-QUEST, Vidjil,
+            RTCR, TRUST4, arda) — see :mod:`vdjtools.io.convert` (``.gz`` ok for the
+            text formats).
         fmt: ``"auto"`` (sniff the header / extension), ``"vdjtools"``, ``"airr"``,
-            or ``"parquet"``.
+            ``"parquet"``, or a legacy format string (``"mixcr"``, ``"migec"``,
+            ``"immunoseq"``, ``"imgt"``, ``"vidjil"``, ``"rtcr"``, ``"trust4"``,
+            ``"arda"``).
         n_rows: If given, read at most this many data rows (preview huge files).
 
     Returns:
@@ -164,7 +177,9 @@ def iter_samples(metadata: pl.DataFrame, base_dir: str | os.PathLike,
     """
     base = Path(base_dir)
     keep = [*COLUMNS, LOCUS]
-    reserved = {"sample_id", "file_name"}
+    # Exclude the canonical clonotype columns (and the reserved sample tags): a metadata column
+    # named e.g. ``locus`` / ``frequency`` / ``duplicate_count`` must NOT overwrite clonotype data.
+    reserved = {"sample_id", "file_name", *COLUMNS, LOCUS}
     meta_cols = [c for c in metadata.columns if c not in reserved and c != sample_col]
     for row in metadata.iter_rows(named=True):
         sample = row[sample_col]

{vdjtools-2.2.0 → vdjtools-2.2.1}/python/vdjtools/io/convert.py

@@ -5,12 +5,14 @@ gene-name normalisation and CDR3 handling were lifted verbatim from the Groovy
 ``com.antigenomics.vdjtools.io.parser`` classes) so third-party tool output can be read
 straight into the canonical AIRR-junction frame of :mod:`vdjtools.io.schema`:
 
-* **MiXcr** (v1/2 *and* v3/4 header dialects) — :func:`read_mixcr`
+* **MiXcr** (v1/2 *and* v3/4 header dialects, incl. the C-gene / isotype hit) — :func:`read_mixcr`
 * **MiGec** — :func:`read_migec`
 * **Adaptive immunoSEQ** v1 and v2 — :func:`read_immunoseq`
 * **IMGT/HighV-QUEST** — :func:`read_imgt`
 * **Vidjil** (``.vidjil`` JSON) — :func:`read_vidjil`
 * **RTCR** — :func:`read_rtcr`
+* **TRUST4** (``*_report.tsv``) — :func:`read_trust4`
+* **arda** (AIRR annotation output) — :func:`read_arda`
 
 Every reader returns the canonical frame: V/D/J IMGT calls, ``junction_nt`` / ``junction_aa``
 (the AIRR junction — conserved Cys104 … Phe/Trp118 anchors **included**, matching the legacy
@@ -28,7 +30,7 @@ from pathlib import Path
 import polars as pl
 
 from . import schema
-from .read import _read_tsv
+from .read import _read_tsv, read_airr
 from .schema import (
     C_CALL,
     COUNT,
@@ -39,20 +41,21 @@ from .schema import (
     V_CALL,
 )
 
-PLACEHOLDER = "."
-
 
 def _to_int(*cells) -> int:
-    """First numeric cell as int (double-then-truncate); none numeric → 0.
+    """First cell parsing to a **positive** integer count (double-then-truncate); none → 0.
 
-    Variadic to support the legacy count fallback (e.g. Adaptive v1 ``templates`` is often
-    ``"null"`` and the real count lives in ``reads``).
+    Skips non-numeric *and* non-positive cells so the legacy count fallback fires correctly —
+    e.g. Adaptive immunoSEQ v1 ``templates`` is often ``"null"`` **or** ``"0"`` and the real
+    count lives in ``reads``. A genuinely zero count is dropped downstream by :func:`_finalize`.
     """
     for x in cells:
         try:
-            return int(float(x))
+            v = int(float(x))
         except (TypeError, ValueError):
             continue
+        if v > 0:
+            return v
     return 0
 
 
@@ -207,6 +210,7 @@ def read_mixcr(path: str | os.PathLike, n_rows: int | None = None) -> pl.DataFra
     v_c = _pick(lo, "all v hits", "allvhitswithscore")
     d_c = _pick(lo, "all d hits", "alldhitswithscore")
     j_c = _pick(lo, "all j hits", "alljhitswithscore")
+    c_c = _pick(lo, "all c hits", "allchitswithscore")  # C gene / BCR isotype (v1/2 & v3/4)
     nt_c = _pick(lo, "n. seq. cdr3", "nseqcdr3", "nseqimputedcdr3")
     aa_c = _pick(lo, "aa. seq. cdr3", "aaseqcdr3", "aaseqimputedcdr3")
     if not (count_c and v_c and j_c and nt_c and aa_c):
@@ -216,7 +220,7 @@ def read_mixcr(path: str | os.PathLike, n_rows: int | None = None) -> pl.DataFra
         cnt = r[count_c]
         rows.append({
             V_CALL: extract_vdj(r[v_c]), D_CALL: extract_vdj(r[d_c]) if d_c else None,
-            J_CALL: extract_vdj(r[j_c]),
+            J_CALL: extract_vdj(r[j_c]), C_CALL: extract_vdj(r[c_c]) if c_c else None,
             JUNCTION_NT: (r[nt_c] or "").upper() or None,
             JUNCTION_AA: r[aa_c],  # MiXcr aa is milib-based — kept verbatim (no unify)
             COUNT: _to_int(cnt),
@@ -323,7 +327,6 @@ def read_immunoseq(path: str | os.PathLike, n_rows: int | None = None) -> pl.Dat
         vg, vf, vt = _pick(lo, "vgenename"), _pick(lo, "vfamilyname"), _pick(lo, "vfamilyties")
         dg, df_, dt = _pick(lo, "dgenename"), _pick(lo, "dfamilyname"), _pick(lo, "dfamilyties")
         jg, jf, jt = _pick(lo, "jgenename"), _pick(lo, "jfamilyname"), _pick(lo, "jfamilyties")
-        in_frame = "in"
     else:
         count_c, count2_c = _pick(lo, "templates"), _pick(lo, "reads")  # templates often "null" → reads
         full_c, aa_c, frame_c = _pick(lo, "rearrangement"), _pick(lo, "amino_acid"), _pick(lo, "frame_type")
@@ -331,7 +334,6 @@ def read_immunoseq(path: str | os.PathLike, n_rows: int | None = None) -> pl.Dat
         vg, vf, vt = _pick(lo, "v_gene"), _pick(lo, "v_family"), _pick(lo, "v_family_ties")
         dg, df_, dt = _pick(lo, "d_gene"), _pick(lo, "d_family"), _pick(lo, "d_family_ties")
         jg, jf, jt = _pick(lo, "j_gene"), _pick(lo, "j_family"), _pick(lo, "j_family_ties")
-        in_frame = "in"
     if not (count_c and full_c and len_c and idx_c and vg and jg):
         raise ValueError(f"not an immunoSEQ table; have {raw.columns[:6]}…")
 
@@ -348,7 +350,7 @@ def read_immunoseq(path: str | os.PathLike, n_rows: int | None = None) -> pl.Dat
                 nt = full[start:start + ln].upper() or None
         status = (_cell(r, frame_c) or "").strip().lower()
         aa_src = _cell(r, aa_c)
-        if status == in_frame and aa_src:
+        if status == "in" and aa_src:
             junc_aa = to_unified_cdr3aa(aa_src)
         else:
             junc_aa = to_unified_cdr3aa(translate(nt)) if nt else None
@@ -393,3 +395,53 @@ def read_vidjil(path: str | os.PathLike, sample_id: int = 0) -> pl.DataFrame:
             COUNT: _to_int(cnt),
         })
     return _finalize(rows)
+
+
+def read_trust4(path: str | os.PathLike, n_rows: int | None = None) -> pl.DataFrame:
+    """Read a TRUST4 clonotype report (``*_report.tsv``).
+
+    The TRUST4 report header is
+    ``#count  frequency  CDR3nt  CDR3aa  V  D  J  C  cid  cid_full_length``. TRUST4's CDR3
+    spans the conserved Cys104 … Phe/Trp118 anchors (anchors **included**), i.e. it is the
+    AIRR junction, so ``CDR3nt``/``CDR3aa`` map straight to ``junction_nt``/``junction_aa``
+    (the ``_`` stop / ``?`` ambiguous-N markers are collapsed by :func:`to_unified_cdr3aa`).
+    ``V``/``D``/``J``/``C`` keep the first allele's gene (``*`` → missing); the C column is
+    the BCR isotype (or the TCR constant gene) when the constant region was captured. Rows
+    whose CDR3 nt is not clean ``ACGT`` (TRUST4 ``partial`` / ``out_of_frame`` / N-containing)
+    are dropped.
+    """
+    raw = _read_tsv(path, n_rows=n_rows)
+    lo = {c.lower().lstrip("#"): c for c in raw.columns}  # first column is ``#count``
+    count_c = _pick(lo, "count")
+    nt_c, aa_c = _pick(lo, "cdr3nt"), _pick(lo, "cdr3aa")
+    v_c, d_c, j_c, c_c = _pick(lo, "v"), _pick(lo, "d"), _pick(lo, "j"), _pick(lo, "c")
+    if not (count_c and nt_c and aa_c and v_c and j_c):
+        raise ValueError(f"not a TRUST4 report (need count / CDR3nt+aa / V,J); have {raw.columns}")
+    rows = []
+    for r in raw.iter_rows(named=True):
+        nt = (r[nt_c] or "").upper()
+        if not _ATGC_ONLY.match(nt):  # skip TRUST4 partial / out-of-frame / N-containing CDR3s
+            continue
+        rows.append({
+            V_CALL: extract_vdj(r[v_c]), D_CALL: extract_vdj(r[d_c]) if d_c else None,
+            J_CALL: extract_vdj(r[j_c]), C_CALL: extract_vdj(r[c_c]) if c_c else None,
+            JUNCTION_NT: nt, JUNCTION_AA: to_unified_cdr3aa(r[aa_c]),
+            COUNT: _to_int(r[count_c]),
+        })
+    return _finalize(rows)
+
+
+def read_arda(path: str | os.PathLike, n_rows: int | None = None) -> pl.DataFrame:
+    """Read arda's AIRR annotation output (per-sequence ``*.airr.tsv`` or ``clones.tsv``).
+
+    arda (AIRR annotation + markup repair) writes standard AIRR Rearrangement column names,
+    so this delegates to :func:`~vdjtools.io.read.read_airr` — which maps
+    ``v_call``/``d_call``/``j_call``/``c_call`` and ``junction``/``junction_aa`` and collapses
+    reads to clonotypes — then nulls the literal ``""`` arda emits for an empty gene call.
+    arda's extra columns (``d2_call``, ``c_class``, ``mmseqs2_*``) are ignored.
+    """
+    df = read_airr(path, n_rows=n_rows)
+    return df.with_columns(
+        pl.when(pl.col(c).str.strip_chars('"') == "").then(None).otherwise(pl.col(c)).alias(c)
+        for c in (D_CALL, C_CALL) if c in df.columns
+    )

{vdjtools-2.2.0 → vdjtools-2.2.1}/skills/vdjtools/SKILL.md

@@ -28,9 +28,11 @@ Iterating on C++: `cmake --build build/<wheel_tag>` then copy `_core.*.so` into
 
 ### `vdjtools.io` — IO, schema, format converters
 - **Readers**: `read(path, fmt="auto")` (sniffs + dispatches), `read_airr`, `read_vdjtools`,
-  `read_parquet`; **legacy converters** `read_mixcr` (v1/2+v3/4), `read_migec`, `read_immunoseq`
-  (Adaptive v1/v2), `read_imgt` (IMGT/HighV-QUEST), `read_vidjil` (JSON), `read_rtcr`
-  (`vdjtools.io.convert`; ported from the legacy Groovy parsers, incl. Adaptive→IMGT gene conversion).
+  `read_parquet`; **converters** `read_mixcr` (v1/2+v3/4, incl. C-gene/BCR isotype), `read_migec`,
+  `read_immunoseq` (Adaptive v1/v2), `read_imgt` (IMGT/HighV-QUEST), `read_vidjil` (JSON),
+  `read_rtcr`, `read_trust4` (`*_report.tsv`), `read_arda` (arda AIRR output, delegates to
+  `read_airr`) (`vdjtools.io.convert`; ported from the legacy Groovy parsers + tool docs, incl.
+  Adaptive→IMGT gene conversion).
 - **Cohorts**: `read_metadata`, `read_samples`, `iter_samples` (streaming), `sniff_format`;
   `ingest_cohort` / `scan_cohort` (hive-partitioned Parquet, lazy).
 - **Schema**: `SCHEMA, COLUMNS`, constants `V_CALL D_CALL J_CALL C_CALL JUNCTION_AA JUNCTION_NT COUNT

{vdjtools-2.2.0 → vdjtools-2.2.1}/src/core.cpp

@@ -11,6 +11,6 @@ int hamming(const std::string& a, const std::string& b) {
     return d;
 }
 
-const char* version() { return "2.2.0"; }
+const char* version() { return "2.2.1"; }
 
 }  // namespace vdjtools