mirpy-lib 4.0.0__tar.gz → 4.2.0__tar.gz

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/CHANGELOG.md

@@ -3,6 +3,66 @@
 All notable changes to `mirpy-lib` (import `mir`). This project follows semantic versioning; the v3 line is a
 greenfield ML/embedding rewrite (the classical v1.x/v2 toolkit is frozen on branch `legacy-v2`).
 
+## 4.2.0 — 2026-09-28
+
+The `rsig` half of the three real corpora, and the mechanism that ships them. Requires vdjtools
+**>=4.2.0**, which owns the fit and the resolver.
+
+**Five new corpora**: `blood` (11,117 samples, 947 study_ids), `blood-uncapped` (22,441), `tissue`
+(21,131 / 1,934), `tissue-uncapped` (33,874) and `deep-tcr` (3,936 amplicon samples, TRA + TRB). All
+nine corpora are now fitted at **k=256** per locus, up from 128, and the full rotation ships —
+truncating downward at apply time is exact, so a wider artifact serves every narrower request.
+
+**Artifacts are no longer bundled in the wheel.** At k=256 an `rsig` artifact is ~3.1 MB and the pair
+of halves across nine corpora is ~110 MB, so the wheel carries a few KB of `corpora.json` — every
+corpus name with its size and SHA-256 — and the library fetches an artifact on first use into
+`$VDJTOOLS_CORPUS_DIR` (default `~/.cache/vdjtools/signature`), verified against that digest. One
+resolver serves both halves, so they cannot disagree about precedence: a local path always beats a
+download. `mir corpus --fetch all` pre-warms the cache, which is the install-time step.
+
+`publish.yml` publishes **only for a `v*` tag** now: without that guard, creating the `corpora-*`
+release fires it and tries to upload whatever version `pyproject` carries.
+
+The two halves of a corpus are published by the library that owns each — `vsig` in vdjtools' release
+assets, `rsig` in mirpy's — so neither repo has to know the other's layout, and they share one cache
+directory because a `vsig`/`rsig` pair belongs in one place.
+
+A real corpus's manifest carries no cohort label, no dataset name and no accession: the population is
+recorded as rule text with aggregate counts, per-locus read floors and the measured read band. A
+rotation is about features and components.
+
+## 4.1.0 — 2026-09-28
+
+**Two corpora that describe a real compartment**, `synthetic-blood` and `synthetic-tissue`, shipped
+as `rsig_synthetic-blood.npz` / `rsig_synthetic-tissue.npz` beside the `naive` and `memory` pair.
+Requires vdjtools **>=4.1.0**, which is where the draw lives: one `corpus_plan` resolves a corpus name
+for both halves and one `corpus_meta` writes both manifests, so a `vsig_<name>`/`rsig_<name>` pair
+cannot disagree about the cohort, the three ladders, the rank correlations or the germline it was drawn
+from -- which is what makes joining them on `sample_id` mean anything.
+
+Each repertoire is a naive/memory **mixture** drawn across three quantile ladders measured per locus
+on the compartment it is named after: clonotype richness, reads per expanded clone, and the singleton
+fraction that stands in for the naive share. The construction, why reads per *expanded* clone is the
+drawable quantity, and the acceptance table are in [vdjtools'
+CHANGELOG](https://github.com/antigenomics/vdjtools/blob/master/CHANGELOG.md) and
+`docs/signature.rst`. The short version: `naive` and `memory` draw depth over 2.4x-11.0x per locus,
+while real blood TRB richness spans 43x (74 to 3,162 clonotypes, n = 34,365 samples) and tissue IGH
+259x -- and a corpus estimates its bounds, centre and per-PC scaling from its own draw, none of which
+extrapolates.
+
+### Changed: `synthesize` takes a corpus name, and the rsig manifest records its depth
+
+`mir.signature.synthesize`'s first parameter is `corpus_name` (`naive` | `memory` |
+`synthetic-blood` | `synthetic-tissue`), not `regime`. `mir corpus --corpus` accepts all four, and
+`--size` defaults to `auto` -- 10,000 for a pure regime, the cohort's median richness per locus for a
+`synthetic-*` one. `--depth-spread` is new and is **refused** on a `synthetic-*` corpus rather than
+silently ignored, because that band is measured.
+
+The rsig manifest now carries `depth_spread`, `depth_spread_requested`, `cohort`, `richness_band`,
+`expanded_count_band`, `singleton_frac_band` and `rank_corr`. It previously carried **no depth field at
+all**, which left the one thing a reader needs in order to know whether a corpus covers their samples
+readable only from the vsig half.
+
 ## 4.0.0 — 2026-09-27
 
 **Signatures rewritten from scratch.** The geometry half; the statistics half is vdjtools, which

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mirpy-lib
-Version: 4.0.0
+Version: 4.2.0
 Summary: ML-oriented embeddings for immune receptor repertoires (TCR/BCR)
 Project-URL: Homepage, https://github.com/antigenomics/mirpy
 Project-URL: Repository, https://github.com/antigenomics/mirpy
@@ -24,7 +24,7 @@ Requires-Dist: polars
 Requires-Dist: scikit-learn
 Requires-Dist: scipy
 Requires-Dist: seqtree>=1.0.0
-Requires-Dist: vdjtools>=4.0.1
+Requires-Dist: vdjtools>=4.2.0
 Provides-Extra: ann
 Requires-Dist: numba>=0.60; extra == 'ann'
 Requires-Dist: pynndescent; extra == 'ann'
@@ -38,7 +38,7 @@ Requires-Dist: matplotlib; extra == 'bench'
 Requires-Dist: seaborn; extra == 'bench'
 Provides-Extra: build
 Requires-Dist: biopython; extra == 'build'
-Requires-Dist: vdjtools[model]>=4.0.1; extra == 'build'
+Requires-Dist: vdjtools[model]>=4.2.0; extra == 'build'
 Provides-Extra: dev
 Requires-Dist: psutil>=5; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -145,9 +145,9 @@ mir embed repertoires cohort/*.tsv.gz -o phi.tsv --mmd mmd.tsv
 
 # the portable signature  ->  one fixed, named, standardised feature vector per sample
 # One tool per half: mirpy emits the geometry, vdjtools the statistics. Join on sample_id.
-mir corpus --corpus naive --smoke -o rsig_naive.npz             # fit a corpus; no cohort needed
-mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet   # geometry half
-mir signature --corpus rsig_naive.npz --components 32 --describe        # exactly what you get
+mir signature --corpus blood cohort/*.tsv.gz -o rsig.parquet   # fetched on first use
+mir signature --corpus blood --components 32 --describe        # exactly what you get
+mir corpus --fetch all                                         # pre-warm the corpus cache
 ```
 
 `mir embed clonotypes -h` / `mir embed repertoires -h` list every flag (species, locus,
@@ -503,17 +503,30 @@ regression, boosting or an MLP with no scaler of their own.
 Command line and library both, and they emit the same columns:
 
 ```bash
-mir corpus    --corpus naive --smoke -o rsig_naive.npz
-mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet
+mir signature --corpus synthetic-blood cohort/*.tsv.gz -o rsig.parquet
+mir corpus    --corpus synthetic-tissue -o rsig_synthetic-tissue.npz   # or build your own
 ```
 
 ```python
 from mir.signature import Corpus, rsig_cohort
 
-corpus = Corpus.load("rsig_naive.npz")      # REQUIRED -- there is no default
-F = rsig_cohort(samples, corpus, n_jobs=0)  # one row per sample
+corpus = Corpus.load("rsig_synthetic-blood.npz")   # REQUIRED -- there is no default
+F = rsig_cohort(samples, corpus, n_jobs=0)         # one row per sample
 ```
 
+**Nine corpora, all at 256 components per locus.** Three are fitted on real repertoires -- `blood`
+(11,117 bulk RNA-seq blood samples, 947 study groups), `tissue` (21,131 / 1,934) and `deep-tcr` (3,936
+amplicon samples, TRA+TRB) -- each with an uncapped variant so the per-study cap's effect is
+measurable. `synthetic-blood` and `synthetic-tissue` draw each repertoire as a naive/memory mixture
+across three quantile ladders measured per locus on that compartment (richness, reads per expanded
+clone, and the singleton fraction that stands in for the naive share), so they span the real depth
+range while needing no cohort to rebuild; `naive` and `memory` remain the pure-regime references.
+
+Artifacts are **fetched on first use** rather than bundled: at k=256 the nine corpora are ~110 MB
+across both halves, so the wheel carries a few KB of index and downloads what you name into
+`~/.cache/vdjtools/signature`, verified against the shipped SHA-256. `mir corpus --fetch all`
+pre-warms it.
+
 Two halves, joined on `sample_id` and namespaced so they never collide: `vsig` (statistics of the
 clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig` (geometry —
 functionals of `Φ`). A column is `<sig>:<block>:<locus>:<feature>`. What comes out per locus is
@@ -532,9 +545,11 @@ and its centre and scale were fitted on zero rows of that artifact and arrived f
 corpus. Two independent fits, stitched; one shipped reference paired a centre of exactly `0.0` with
 a scale plainly fitted from data and put a corpus-typical sample **81 robust deviations** out.
 
-The two synthetic corpora need no cohort at all and are reproducible by anyone who installs the
-library — `naive` (every clone size 1, what the recombination model emits) and `memory` (Zipf
-rank-abundance clone sizes). `deep-tcr`, `blood` and `tissue` are fitted on real cohorts.
+All four shipped corpora need no cohort at all and are reproducible by anyone who installs the
+library — `synthetic-blood` and `synthetic-tissue` (the naive/memory mixture drawn across a
+compartment's measured per-locus ladders), plus the pure regimes `naive` (every clone size 1, what
+the recombination model emits) and `memory` (Zipf rank-abundance clone sizes). `deep-tcr`, `blood`
+and `tissue` will be fitted on real cohorts and are not shipped yet.
 
 **Holes are never zeros.** An unsequenced locus, a compartment below its clonotype floor, or a
 statistic the sample is too shallow to estimate is `nan` plus a `mask:` column, because a model that

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/README.md

@@ -89,9 +89,9 @@ mir embed repertoires cohort/*.tsv.gz -o phi.tsv --mmd mmd.tsv
 
 # the portable signature  ->  one fixed, named, standardised feature vector per sample
 # One tool per half: mirpy emits the geometry, vdjtools the statistics. Join on sample_id.
-mir corpus --corpus naive --smoke -o rsig_naive.npz             # fit a corpus; no cohort needed
-mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet   # geometry half
-mir signature --corpus rsig_naive.npz --components 32 --describe        # exactly what you get
+mir signature --corpus blood cohort/*.tsv.gz -o rsig.parquet   # fetched on first use
+mir signature --corpus blood --components 32 --describe        # exactly what you get
+mir corpus --fetch all                                         # pre-warm the corpus cache
 ```
 
 `mir embed clonotypes -h` / `mir embed repertoires -h` list every flag (species, locus,
@@ -447,17 +447,30 @@ regression, boosting or an MLP with no scaler of their own.
 Command line and library both, and they emit the same columns:
 
 ```bash
-mir corpus    --corpus naive --smoke -o rsig_naive.npz
-mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet
+mir signature --corpus synthetic-blood cohort/*.tsv.gz -o rsig.parquet
+mir corpus    --corpus synthetic-tissue -o rsig_synthetic-tissue.npz   # or build your own
 ```
 
 ```python
 from mir.signature import Corpus, rsig_cohort
 
-corpus = Corpus.load("rsig_naive.npz")      # REQUIRED -- there is no default
-F = rsig_cohort(samples, corpus, n_jobs=0)  # one row per sample
+corpus = Corpus.load("rsig_synthetic-blood.npz")   # REQUIRED -- there is no default
+F = rsig_cohort(samples, corpus, n_jobs=0)         # one row per sample
 ```
 
+**Nine corpora, all at 256 components per locus.** Three are fitted on real repertoires -- `blood`
+(11,117 bulk RNA-seq blood samples, 947 study groups), `tissue` (21,131 / 1,934) and `deep-tcr` (3,936
+amplicon samples, TRA+TRB) -- each with an uncapped variant so the per-study cap's effect is
+measurable. `synthetic-blood` and `synthetic-tissue` draw each repertoire as a naive/memory mixture
+across three quantile ladders measured per locus on that compartment (richness, reads per expanded
+clone, and the singleton fraction that stands in for the naive share), so they span the real depth
+range while needing no cohort to rebuild; `naive` and `memory` remain the pure-regime references.
+
+Artifacts are **fetched on first use** rather than bundled: at k=256 the nine corpora are ~110 MB
+across both halves, so the wheel carries a few KB of index and downloads what you name into
+`~/.cache/vdjtools/signature`, verified against the shipped SHA-256. `mir corpus --fetch all`
+pre-warms it.
+
 Two halves, joined on `sample_id` and namespaced so they never collide: `vsig` (statistics of the
 clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig` (geometry —
 functionals of `Φ`). A column is `<sig>:<block>:<locus>:<feature>`. What comes out per locus is
@@ -476,9 +489,11 @@ and its centre and scale were fitted on zero rows of that artifact and arrived f
 corpus. Two independent fits, stitched; one shipped reference paired a centre of exactly `0.0` with
 a scale plainly fitted from data and put a corpus-typical sample **81 robust deviations** out.
 
-The two synthetic corpora need no cohort at all and are reproducible by anyone who installs the
-library — `naive` (every clone size 1, what the recombination model emits) and `memory` (Zipf
-rank-abundance clone sizes). `deep-tcr`, `blood` and `tissue` are fitted on real cohorts.
+All four shipped corpora need no cohort at all and are reproducible by anyone who installs the
+library — `synthetic-blood` and `synthetic-tissue` (the naive/memory mixture drawn across a
+compartment's measured per-locus ladders), plus the pure regimes `naive` (every clone size 1, what
+the recombination model emits) and `memory` (Zipf rank-abundance clone sizes). `deep-tcr`, `blood`
+and `tissue` will be fitted on real cohorts and are not shipped yet.
 
 **Holes are never zeros.** An unsequenced locus, a compartment below its clonotype floor, or a
 statistic the sample is too shallow to estimate is `nan` plus a `mask:` column, because a model that

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/docs/signature.rst

@@ -24,7 +24,10 @@ Quickstart
 
 .. code-block:: bash
 
-   # build a corpus once -- uses no samples from anybody's cohort
+   # four corpora ship with the wheel; name one, no build and no cohort needed
+   mir signature --corpus synthetic-blood cohort/*.tsv.gz -o rsig.tsv
+
+   # or build your own -- still uses no samples from anybody's cohort
    mir corpus --corpus naive --smoke -o naive_rsig.npz
 
    mir signature --corpus naive_rsig.npz cohort/*.tsv.gz -o rsig.tsv
@@ -187,11 +190,28 @@ Building a corpus
 
 .. code-block:: bash
 
+   mir corpus --corpus synthetic-blood  -o synthetic-blood_rsig.npz
+   mir corpus --corpus synthetic-tissue -o synthetic-tissue_rsig.npz
    mir corpus --corpus naive  -o naive_rsig.npz
    mir corpus --corpus memory --size n_eff --components 0.95 -o memory_rsig.npz
    mir corpus --smoke -o /tmp/smoke.npz
    mir corpus --corpus naive -j 8 -o naive_rsig.npz     # 8 worker processes
 
+Four corpora ship, all synthetic. ``synthetic-blood`` and ``synthetic-tissue`` are the ones to reach
+for: each repertoire is a naive/memory **mixture** drawn from three quantile ladders measured per
+locus on the cohort it is named after -- richness, reads per expanded clone, and the singleton
+fraction that stands in for the naive compartment -- through that cohort's measured rank
+correlations. ``naive`` and ``memory`` are the pure regimes, and neither varies what a cohort varies:
+``memory`` at a fixed size has the same read count in every sample. The construction, the
+acceptance table and why reads per *expanded* clone is the drawable quantity are in `the vdjtools
+half <https://docs.isalgo.dev/vdjtools/signature.html#the-two-cohort-corpora-three-measured-ladders-per-locus>`_,
+since one module draws for both.
+
+Both halves must be built from the **same corpus name and seed**: they resolve the name through one
+``corpus_plan`` and write the manifest through one ``corpus_meta``, so the cohort, the three ladders,
+the rank correlations and the germline fingerprint cannot disagree between ``vsig_<name>`` and
+``rsig_<name>`` -- which is what makes joining them on ``sample_id`` meaningful.
+
 The build runs across worker **processes**, one contiguous block of samples each; ``-j/--jobs``
 defaults to every core the process may use (``-j 1`` stays in-process). Both halves share one
 builder, so a sample is the same repertoire in either -- its generator is seeded from

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/pyproject.toml

@@ -36,7 +36,7 @@ dependencies = [
   # `vdjtools.signature.corpus`, which does not exist before 4.0.0, and 4.0.0 never
   # reached PyPI. On the old `>=3.18.0` pip would have resolved vdjtools 3.18.1 beside
   # mirpy 4.0.0 and every signature entry point would have failed on import.
-  "vdjtools>=4.0.1",
+  "vdjtools>=4.2.0",
 ]
 license = { text = "GPL-3.0-or-later" }
 
@@ -46,7 +46,7 @@ annotate = ["vdjmatch"]
 # Build-time only: regenerate region_annotations.txt (arda) and the baked
 # germline distance matrices (BioPython). Runtime needs neither. arda comes
 # via vdjtools[model] (single arda version across the ecosystem), not pinned directly.
-build = ["vdjtools[model]>=4.0.1", "biopython"]
+build = ["vdjtools[model]>=4.2.0", "biopython"]
 # Part 2: neural codecs and density methods.
 ml = ["torch"]
 # Benchmark harness: DBSCAN eps selection + plotting + HuggingFace dataset fetch +

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/skills/mirpy/SKILL.md

@@ -63,11 +63,11 @@ pip install "mirpy-lib[build]"            # BioPython + arda: regenerate baked r
 ```bash
 mir embed clonotypes  SAMPLE  -o out.parquet      # per-clonotype table (e0…)
 mir embed repertoires S1 S2 … -o phi.tsv --mmd mmd.tsv   # one Φ(S) per sample per chain (phi0…)
-mir corpus --corpus naive --smoke -o rsig_naive.npz             # build + fit a corpus
-mir signature S1 S2 … --corpus rsig_naive.npz -o rsig.parquet  # geometry ONLY (rsig)
+mir corpus --fetch all                                      # pre-warm the corpus cache
+mir signature S1 S2 … --corpus blood -o rsig.parquet         # geometry ONLY (rsig)
 # the vsig half is `vdjtools signature`, against the SAME corpus name and seed;
 # join the two on sample_id for the full vector
-mir signature --corpus rsig_naive.npz --describe   # exactly what this invocation emits
+mir signature --corpus blood --describe   # exactly what this invocation emits
 ```
 
 - Reads anything `vdjtools.io.read` sniffs (AIRR TSV, vdjtools, MiXCR, immunoSEQ, parquet).
@@ -153,7 +153,7 @@ one contract: `vsig` (statistics, from `vdjtools.signature`) and `rsig` (geometr
 
 ```python
 from mir.signature import Corpus, rsig, rsig_cohort, raw_and_channels, synthesize
-corpus = Corpus.load("rsig_naive.npz")     # REQUIRED -- there is no default corpus
+corpus = Corpus.load(bundled_path("blood"))        # REQUIRED -- no default corpus
 v = rsig({"TRB": df}, corpus)
 F = rsig_cohort(samples, corpus, n_jobs=0)
 raw, chan = raw_and_channels({"TRB": df}, corpus.vocab)    # un-rotated, natural units

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/src/mir/__init__.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 import os
 
-__version__ = "4.0.0"
+__version__ = "4.2.0"
 
 __all__ = ["__version__", "get_resource_path", "TCREmp", "PairedTCREmp"]
 

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/src/mir/cli.py

@@ -407,12 +407,30 @@ def cmd_corpus(a: argparse.Namespace) -> None:
 
     from mir.signature import synthesize
 
-    size = a.size
-    if size not in ("n_eff", "p05", "p95"):
+    if a.fetch:
+        from vdjtools.signature.corpus import corpora_index, corpus_cache_dir, fetch_artifact
+
+        from mir.signature.signature import CORPUS_REPO, _RES, bundled_names
+        idx = corpora_index(_RES)
+        if not idx:
+            raise SystemExit("this version ships no corpus index, so there is nothing to fetch; "
+                             f"the corpora it knows are {', '.join(bundled_names()) or '(none)'}")
+        for nm in (sorted(idx) if a.fetch == "all" else [a.fetch]):
+            if nm not in idx:
+                raise SystemExit(f"no published corpus named {nm!r}; have {', '.join(sorted(idx))}")
+            p = fetch_artifact(nm, sig="rsig", res_dir=_RES, repo=CORPUS_REPO)
+            print(f"[mir] {p}  {p.stat().st_size / 1e6:.2f} MB", file=sys.stderr)
+        print(f"[mir] cache: {corpus_cache_dir()}", file=sys.stderr)
+        return
+    if not a.output:
+        raise SystemExit("-o/--output is required when building a corpus (--fetch does not use it)")
+
+    size = None if a.size == "auto" else a.size
+    if a.size not in ("auto", "n_eff", "p05", "p95"):
         try:
-            size = int(size)
+            size = int(a.size)
         except ValueError:
-            raise SystemExit(f"--size must be an integer or one of n_eff, p05, p95; "
+            raise SystemExit(f"--size must be an integer or one of auto, n_eff, p05, p95; "
                              f"got {a.size!r}") from None
     n_samples = a.samples
     if a.smoke:
@@ -424,6 +442,7 @@ def cmd_corpus(a: argparse.Namespace) -> None:
     art, _rows = synthesize(a.corpus, n_samples=n_samples, size=size, seed=a.seed,
                             n_components=ks, mode=a.winsorize, winsor_p=a.winsor_p,
                             source=a.source, species=a.species, n_jobs=a.jobs,
+                            depth_spread=a.depth_spread,
                             progress=lambda loc, d, t: print(
                                 f"  {loc:4s} {d}/{t}  {time.time() - t0:5.0f}s",
                                 file=sys.stderr, flush=True), **kw)
@@ -552,6 +571,7 @@ def build_parser() -> argparse.ArgumentParser:
             "installs the library.\n"),
         epilog=(
             "  mir corpus --corpus naive  -o naive.npz\n"
+            "  mir corpus --corpus synthetic-blood  -o synthetic-blood.npz\n"
             "  mir corpus --corpus memory --size n_eff --components 0.95 -o memory.npz\n"
             "  mir corpus --smoke -o /tmp/smoke.npz          # minutes, not hours\n"
             "\n"
@@ -562,12 +582,24 @@ def build_parser() -> argparse.ArgumentParser:
             "Use the SAME name and seed as `vdjtools corpus` so the two halves describe the\n"
             "same repertoires; that is what makes joining them meaningful.\n"),
     )
-    c2.add_argument("--corpus", default="naive", choices=("naive", "memory"),
-                    help="naive: every clone size 1; memory: Zipf rank-abundance clone sizes")
-    c2.add_argument("-o", "--output", required=True, help="artifact path; writes .npz and .json")
+    c2.add_argument("--corpus", default="naive",
+                    choices=("naive", "memory", "synthetic-blood", "synthetic-tissue"),
+                    help="naive: every clone size 1; memory: Zipf rank-abundance clone sizes; "
+                         "synthetic-blood / synthetic-tissue: the mixture of the two, drawn across "
+                         "that real cohort's measured per-locus richness, reads per clonotype and "
+                         "singleton fraction")
+    c2.add_argument("-o", "--output", help="artifact path; writes .npz and .json. Required "
+                                          "unless --fetch, which downloads into the cache instead")
+    c2.add_argument("--fetch", metavar="NAME|all",
+                    help="download a published corpus instead of building one, into the cache "
+                         "($VDJTOOLS_CORPUS_DIR or ~/.cache/vdjtools/signature); `all` pre-warms "
+                         "every corpus, which is the install-time step since an artifact is "
+                         "otherwise fetched on first use")
     c2.add_argument("--samples", type=int, default=10_000, help="repertoires in the corpus")
-    c2.add_argument("--size", default="10000",
-                    help="receptors per repertoire: an integer, or n_eff / p05 / p95")
+    c2.add_argument("--size", default="auto",
+                    help="receptors per repertoire: an integer, or n_eff / p05 / p95. Default auto "
+                         "is the corpus's own -- 10000 for naive/memory, the centre of the cohort's "
+                         "measured richness band for a synthetic-* one")
     c2.add_argument("--components", default="128",
                     help="components per locus: an integer count, or a variance fraction")
     c2.add_argument("--winsorize", default="features", choices=("features", "pcs", "none"))
@@ -576,6 +608,12 @@ def build_parser() -> argparse.ArgumentParser:
     c2.add_argument("--loci", default=None, help="comma-separated subset (default: all seven)")
     c2.add_argument("--source", default="olga", choices=("olga", "learned", "arda"))
     c2.add_argument("--species", default="human")
+    c2.add_argument("--depth-spread", type=float, default=None,
+                    help="multiplicative depth range each repertoire's size is drawn log-uniformly "
+                         "across, around --size; default is the corpus's own (2.4x-11.0x for "
+                         "naive/memory, 43x on blood TRB and 259x on tissue IGH for the "
+                         "synthetic-* ones). --size 3162 --depth-spread 1000 spans 100 to 100000 "
+                         "receptors. Must match the vsig half to describe the same repertoires")
     c2.add_argument("--smoke", action="store_true",
                     help="reduced build (200 samples of 1000) for tests and the cmp check")
     c2.add_argument("-j", "--jobs", type=int, default=0,

mirpy_lib-4.2.0/src/mir/resources/signature/corpora.json

@@ -0,0 +1,92 @@
+{
+ "blood": {
+  "json": {
+   "bytes": 2522,
+   "sha256": "366d788ec0ad0866eaf29ab9f9595daf33699b0db0b8e2a6e38a25f72b3caeeb"
+  },
+  "npz": {
+   "bytes": 3106113,
+   "sha256": "eed16130f1a49a3adce5d06cd58f94908ad872834c652aabd1ef52230cca1dc1"
+  }
+ },
+ "blood-uncapped": {
+  "json": {
+   "bytes": 2542,
+   "sha256": "527dc2f0a5bd659ea6ce4a545be6629300d0a0f4c8247e8910e30393900c1c51"
+  },
+  "npz": {
+   "bytes": 3106878,
+   "sha256": "7c647d147d82a3bf1d4ac1545014976367fb2b6848e1dfda48c62266f5a3cbd0"
+  }
+ },
+ "deep-tcr": {
+  "json": {
+   "bytes": 1662,
+   "sha256": "dfe85f918778f1d4dcc0702bbb225aba9fc8418aa44874ab6e7db4bb2162c9af"
+  },
+  "npz": {
+   "bytes": 1008863,
+   "sha256": "68e102627f2d9db454520321fa3b8c253bd2909bfbec8d6395959003f9535760"
+  }
+ },
+ "memory": {
+  "json": {
+   "bytes": 2247,
+   "sha256": "2aea36575627e83dd991cbace08efbccd72f27ff8d65d32a952ec2bbc03d102c"
+  },
+  "npz": {
+   "bytes": 3103450,
+   "sha256": "45c77bdf918b55e4a21044246dfbb205a4e65e3ab7564a68de16216f9b175df3"
+  }
+ },
+ "naive": {
+  "json": {
+   "bytes": 2241,
+   "sha256": "8127ff977fd5ede5ba78471ac4ae305f3fe22852960c6ebd2da233b1e2558f33"
+  },
+  "npz": {
+   "bytes": 3101749,
+   "sha256": "007fbc2fc1c9f4228ef88aec2bd690a0294218e74dfff93fc472ee6caa5613e5"
+  }
+ },
+ "synthetic-blood": {
+  "json": {
+   "bytes": 3812,
+   "sha256": "9560ddd0d6fff1a3fcb345153f1e0cf17b99a45a44681124481c508f164845f6"
+  },
+  "npz": {
+   "bytes": 3102697,
+   "sha256": "fd3722027de7957b69dc8a9e0a35e548c94de9aff5e441ccc10ccd28083fad68"
+  }
+ },
+ "synthetic-tissue": {
+  "json": {
+   "bytes": 3805,
+   "sha256": "4c7f12a1313c9f52aec2f61e11cde0efaf91e25e61304aab353b0542d9e270e9"
+  },
+  "npz": {
+   "bytes": 3102745,
+   "sha256": "bf66da96d8a778d9a626d1dfa1eb738b50869034fa248404d270dd54ddf3ab8d"
+  }
+ },
+ "tissue": {
+  "json": {
+   "bytes": 2520,
+   "sha256": "8936971ddf6d12bb39f9a4bcd9def6b2c9e075811fc044636760102effcacfd5"
+  },
+  "npz": {
+   "bytes": 3105251,
+   "sha256": "531e814ecdd053327adc3c4baf9cf81e5e73b80deadc77b89dd0098d82dd8eee"
+  }
+ },
+ "tissue-uncapped": {
+  "json": {
+   "bytes": 2538,
+   "sha256": "983d38cd3e597e3698528ded9a15ca6665199fee9122da7a11c0926e9ba7644b"
+  },
+  "npz": {
+   "bytes": 3105365,
+   "sha256": "aa82dae5dcf149292061caad4d1744f2665c3cf482f454fe4ac1e72fa4f4e636"
+  }
+ }
+}

{mirpy_lib-4.0.0 → mirpy_lib-4.2.0}/src/mir/signature/signature.py

@@ -63,24 +63,33 @@ _register()
 _RES = __import__("pathlib").Path(__file__).resolve().parent.parent / "resources" / "signature"
 
 
+#: The repo whose release assets carry the rsig artifacts. The vsig half lives in vdjtools' releases;
+#: each half is published by the library that owns it, so a corpus name resolves to two downloads from
+#: two repos rather than one repo having to know about the other's layout.
+CORPUS_REPO = "antigenomics/mirpy"
+
+
 def bundled_names() -> list[str]:
-    """Corpus names with an installed rsig artifact."""
-    if not _RES.is_dir():
-        return []
-    return sorted(p.stem.removeprefix("rsig_") for p in _RES.glob("rsig_*.npz"))
+    """Every corpus name this version knows -- installed, cached, or downloadable."""
+    from vdjtools.signature.corpus import corpora_index, corpus_cache_dir
+
+    got = {p.stem.removeprefix("rsig_") for p in _RES.glob("rsig_*.npz")} if _RES.is_dir() else set()
+    cache = corpus_cache_dir()
+    if cache.is_dir():
+        got |= {p.stem.removeprefix("rsig_") for p in cache.glob("rsig_*.npz")}
+    return sorted(got | set(corpora_index(_RES)))
 
 
 def bundled_path(name):
-    """Resolve a bundled corpus name or a filesystem path to an artifact, else ``None``."""
-    from pathlib import Path
+    """Resolve a corpus name or a filesystem path to an ``rsig`` artifact, else ``None``.
+
+    Downloads on first use if the name is in the shipped index and not yet cached. One resolver,
+    shared with the vsig half, so the two cannot disagree about precedence -- a local path always
+    wins over a download.
+    """
+    from vdjtools.signature.corpus import resolve_artifact
 
-    direct = Path(name)
-    if direct.suffix == ".npz" and direct.exists():
-        return direct
-    if direct.with_suffix(".npz").exists():
-        return direct.with_suffix(".npz")
-    cand = _RES / f"rsig_{name}.npz"
-    return cand if cand.exists() else None
+    return resolve_artifact(name, sig="rsig", res_dir=_RES, repo=CORPUS_REPO)
 
 
 def _model(species: str, locus: str):
@@ -261,11 +270,11 @@ def rsig_cohort(samples, corpus: C.Corpus, *, n_jobs: int = 1,
     return pl.DataFrame(rows).select([c for c in want if any(c in r for r in rows)])
 
 
-def synthesize(regime: str, *, loci: "tuple[str, ...]" = L.LOCI, n_samples: int = 10_000,
-               size: "int | str" = C.DEFAULT_SIZE, seed: int = C.SEED,
+def synthesize(corpus_name: str, *, loci: "tuple[str, ...]" = L.LOCI, n_samples: int = 10_000,
+               size: "int | str | None" = None, seed: int = C.SEED,
                n_components: "int | float" = C.DEFAULT_COMPONENTS, mode: str = "features",
                winsor_p: float = 0.01, source: str = "olga", species: str = "human",
-               progress=None, n_jobs: int = 1):
+               progress=None, n_jobs: int = 1, depth_spread: "float | str | None" = None):
     """Build and fit an ``rsig`` corpus on the same synthetic repertoires ``vsig`` uses.
 
     The receptors, the seeds and the drawn depths are all
@@ -274,8 +283,17 @@ def synthesize(regime: str, *, loci: "tuple[str, ...]" = L.LOCI, n_samples: int
     ``sample_id`` meaningful rather than merely type-correct.
 
     Args:
+        corpus_name: One of :data:`vdjtools.signature.corpus.SYNTHETIC` -- ``"naive"`` / ``"memory"``
+            for the pure regimes, ``"synthetic-blood"`` / ``"synthetic-tissue"`` for the naive/memory
+            mixture drawn across that cohort's measured per-locus richness, read-depth and
+            singleton-fraction bands.
         n_jobs: Worker **processes** (not kernel threads). ``0`` means every available core; ``1``,
             the default, runs in-process. The artifact is bit-identical at every value.
+        size: ``None`` is the corpus's own -- 10,000 for a pure regime, the geometric centre of the
+            cohort's measured richness band for a ``synthetic-*`` one.
+        depth_spread: Multiplicative depth range each repertoire's size is drawn log-uniformly
+            across, around ``size``; ``None`` is the corpus's own. Must match the ``vsig`` half's
+            value for the two to describe the same repertoires.
 
     Returns:
         ``(corpus, mats)`` -- ``mats`` being ``{locus: (matrix, columns)}``, the corpus matrix itself.
@@ -284,23 +302,24 @@ def synthesize(regime: str, *, loci: "tuple[str, ...]" = L.LOCI, n_samples: int
 
     import mir
 
+    regime, cohort, size, depth_spread = C.corpus_plan(corpus_name, size=size,
+                                                      depth_spread=depth_spread)
     vocab = {loc: {} for loc in loci}
     # Parallel across samples, in the one shared builder: an rsig row is a pure function of its
     # sample, so a worker draws its own repertoires from the memory-mapped pools and only the row of
     # numbers comes back. ``n_jobs`` does not change a single value.
     mats = C.build_matrices(
         regime, sig="rsig", vocab=vocab, loci=loci, n_samples=n_samples, size=size, seed=seed,
-        source=source, n_jobs=n_jobs, progress=progress,
+        source=source, n_jobs=n_jobs, progress=progress, depth_spread=depth_spread, cohort=cohort,
         featurise=partial(raw_and_channels, vocab=vocab, species=species))
     return C.fit_matrices(
-        mats, vocab, sig="rsig", name=regime, mode=mode, n_components=n_components,
+        mats, vocab, sig="rsig", name=corpus_name, mode=mode, n_components=n_components,
         winsor_p=winsor_p,
-        meta={"regime": regime, "n_samples": n_samples, "seed": seed, "source": source,
-              "size": size, "species": species, "K": F.K,
-              "size_per_locus": {k: C.resolved_size(k, size) for k in loci},
-              "mir_version": mir.__version__, "loci": list(loci),
-              # The pools come out of these models; retraining one moves its locus. Gated on load.
-              "models": C.model_fingerprint(loci, source)}), mats
+        # One manifest builder for both halves: a `vsig_<name>`/`rsig_<name>` pair that disagreed
+        # about the depths or the singleton fractions would be a joinability claim nobody can check.
+        meta=C.corpus_meta(regime, cohort, loci, n_samples=n_samples, size=size, seed=seed,
+                           source=source, depth_spread=depth_spread,
+                           mir_version=mir.__version__, species=species, K=F.K)), mats
 
 
 def _demo() -> None:

mirpy_lib-4.0.0/src/mir/resources/signature/rsig_memory.json

@@ -1,94 +0,0 @@
-{
- "K": 256,
- "content_sha256": "02be6824a511fca836f59eeaf51fcdd1dfe98d6f8d36cf80cfeb8731f28c3d22",
- "k": {
-  "IGH": 128,
-  "IGK": 128,
-  "IGL": 128,
-  "TRA": 128,
-  "TRB": 128,
-  "TRD": 128,
-  "TRG": 128
- },
- "loci": [
-  "TRA",
-  "TRB",
-  "TRG",
-  "TRD",
-  "IGH",
-  "IGK",
-  "IGL"
- ],
- "mir_version": "3.20.2",
- "mode": "features",
- "models": {
-  "IGH": "olga:human_B_heavy@e21ec62f2139",
-  "IGK": "olga:human_B_kappa@f160ed8ce718",
-  "IGL": "olga:human_B_lambda@4756d868be49",
-  "TRA": "olga:human_T_alpha@2a4e83d16fdf",
-  "TRB": "olga:human_T_beta@2fccd0006de8",
-  "TRD": "olga:human_T_delta@def2922b705f",
-  "TRG": "olga:human_T_gamma@d25719222561"
- },
- "n_components_requested": 128,
- "n_rows": {
-  "IGH": 10000,
-  "IGK": 10000,
-  "IGL": 10000,
-  "TRA": 10000,
-  "TRB": 10000,
-  "TRD": 10000,
-  "TRG": 10000
- },
- "n_samples": 10000,
- "name": "memory",
- "numpy": "2.5.2",
- "platform": "Linux-5.4.0-215-generic-x86_64-with-glibc2.31",
- "regime": "memory",
- "seed": 20260927,
- "sig": "rsig",
- "size": 10000,
- "size_per_locus": {
-  "IGH": 10000,
-  "IGK": 10000,
-  "IGL": 10000,
-  "TRA": 10000,
-  "TRB": 10000,
-  "TRD": 10000,
-  "TRG": 10000
- },
- "source": "olga",
- "species": "human",
- "trimmed_frac": {
-  "IGH": 0.010038860103626942,
-  "IGK": 0.010038860103626942,
-  "IGL": 0.010038860103626942,
-  "TRA": 0.010038860103626942,
-  "TRB": 0.010038860103626942,
-  "TRD": 0.010038860103626942,
-  "TRG": 0.010038860103626942
- },
- "variance_at_k": {
-  "IGH": 0.9910758445764348,
-  "IGK": 0.9993485868815669,
-  "IGL": 0.9989373382451864,
-  "TRA": 0.996276863840755,
-  "TRB": 0.9956540910199058,
-  "TRD": 0.9987458060164907,
-  "TRG": 0.9992160798179918
- },
- "vocab": {
-  "IGH": {},
-  "IGK": {},
-  "IGL": {},
-  "TRA": {},
-  "TRB": {},
-  "TRD": {},
-  "TRG": {}
- },
- "winsor_p": 0.01,
- "winsor_ps": [
-  0.01,
-  0.05
- ]
-}

mirpy_lib-4.0.0/src/mir/resources/signature/rsig_naive.json

@@ -1,94 +0,0 @@
-{
- "K": 256,
- "content_sha256": "6cc52f9da4a790b4553a978327d9ed41e7036856861322648c0483c6b15519d1",
- "k": {
-  "IGH": 128,
-  "IGK": 128,
-  "IGL": 128,
-  "TRA": 128,
-  "TRB": 128,
-  "TRD": 128,
-  "TRG": 128
- },
- "loci": [
-  "TRA",
-  "TRB",
-  "TRG",
-  "TRD",
-  "IGH",
-  "IGK",
-  "IGL"
- ],
- "mir_version": "3.20.2",
- "mode": "features",
- "models": {
-  "IGH": "olga:human_B_heavy@e21ec62f2139",
-  "IGK": "olga:human_B_kappa@f160ed8ce718",
-  "IGL": "olga:human_B_lambda@4756d868be49",
-  "TRA": "olga:human_T_alpha@2a4e83d16fdf",
-  "TRB": "olga:human_T_beta@2fccd0006de8",
-  "TRD": "olga:human_T_delta@def2922b705f",
-  "TRG": "olga:human_T_gamma@d25719222561"
- },
- "n_components_requested": 128,
- "n_rows": {
-  "IGH": 10000,
-  "IGK": 10000,
-  "IGL": 10000,
-  "TRA": 10000,
-  "TRB": 10000,
-  "TRD": 10000,
-  "TRG": 10000
- },
- "n_samples": 10000,
- "name": "naive",
- "numpy": "2.5.2",
- "platform": "Linux-5.4.0-215-generic-x86_64-with-glibc2.31",
- "regime": "naive",
- "seed": 20260927,
- "sig": "rsig",
- "size": 10000,
- "size_per_locus": {
-  "IGH": 10000,
-  "IGK": 10000,
-  "IGL": 10000,
-  "TRA": 10000,
-  "TRB": 10000,
-  "TRD": 10000,
-  "TRG": 10000
- },
- "source": "olga",
- "species": "human",
- "trimmed_frac": {
-  "IGH": 0.010012970168612191,
-  "IGK": 0.01001284046692607,
-  "IGL": 0.01001284046692607,
-  "TRA": 0.010012710765239949,
-  "TRB": 0.010012970168612191,
-  "TRD": 0.010012970168612191,
-  "TRG": 0.010012710765239949
- },
- "variance_at_k": {
-  "IGH": 0.9887366548085227,
-  "IGK": 0.9991668470828621,
-  "IGL": 0.9986028566065589,
-  "TRA": 0.9917447530288632,
-  "TRB": 0.9923344290339433,
-  "TRD": 0.9966133463827523,
-  "TRG": 0.9986828452151979
- },
- "vocab": {
-  "IGH": {},
-  "IGK": {},
-  "IGL": {},
-  "TRA": {},
-  "TRB": {},
-  "TRD": {},
-  "TRG": {}
- },
- "winsor_p": 0.01,
- "winsor_ps": [
-  0.01,
-  0.05
- ]
-}