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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/CHANGELOG.md +104 -0
  2. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/PKG-INFO +35 -45
  3. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/README.md +32 -42
  4. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/api.rst +35 -33
  5. mirpy_lib-4.0.0/docs/channels.rst +80 -0
  6. mirpy_lib-4.0.0/docs/signature.rst +249 -0
  7. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/pyproject.toml +6 -2
  8. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/skills/mirpy/SKILL.md +57 -63
  9. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/__init__.py +1 -1
  10. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/cli.py +180 -243
  11. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/tcremp.py +2 -2
  12. mirpy_lib-4.0.0/src/mir/resources/signature/rsig_memory.json +94 -0
  13. mirpy_lib-4.0.0/src/mir/resources/signature/rsig_memory.npz +0 -0
  14. mirpy_lib-4.0.0/src/mir/resources/signature/rsig_naive.json +94 -0
  15. mirpy_lib-4.0.0/src/mir/resources/signature/rsig_naive.npz +0 -0
  16. mirpy_lib-4.0.0/src/mir/signature/__init__.py +44 -0
  17. mirpy_lib-4.0.0/src/mir/signature/features.py +222 -0
  18. mirpy_lib-4.0.0/src/mir/signature/signature.py +327 -0
  19. mirpy_lib-3.20.2/docs/channels.rst +0 -218
  20. mirpy_lib-3.20.2/docs/signature.rst +0 -1051
  21. mirpy_lib-3.20.2/src/mir/resources/signature/build_rsig.py +0 -201
  22. mirpy_lib-3.20.2/src/mir/resources/signature/kmer_spaces_v1.npz +0 -0
  23. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_u_v4.json +0 -42
  24. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_u_v4.npz +0 -0
  25. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_w_v4.json +0 -42
  26. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_w_v4.npz +0 -0
  27. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_u_v4.json +0 -42
  28. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_u_v4.npz +0 -0
  29. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_w_v4.json +0 -42
  30. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_w_v4.npz +0 -0
  31. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v2.json +0 -50
  32. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v2.npz +0 -0
  33. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v3.json +0 -38
  34. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v3.npz +0 -0
  35. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_v2.json +0 -25
  36. mirpy_lib-3.20.2/src/mir/resources/signature/rsig_v2.npz +0 -0
  37. mirpy_lib-3.20.2/src/mir/signature/__init__.py +0 -136
  38. mirpy_lib-3.20.2/src/mir/signature/assemble.py +0 -523
  39. mirpy_lib-3.20.2/src/mir/signature/blocks.py +0 -270
  40. mirpy_lib-3.20.2/src/mir/signature/reference.py +0 -313
  41. mirpy_lib-3.20.2/src/mir/signature/scale.py +0 -1009
  42. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/.gitignore +0 -0
  43. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/LICENSE +0 -0
  44. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark.png +0 -0
  45. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark.svg +0 -0
  46. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark_bg.svg +0 -0
  47. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light.png +0 -0
  48. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light.svg +0 -0
  49. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light_bg.svg +0 -0
  50. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/data/signature_reference_studies.tsv +0 -0
  51. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/Makefile +0 -0
  52. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_ext/themed_graphviz.py +0 -0
  53. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/custom.css +0 -0
  54. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/depth_robustness.png +0 -0
  55. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_dark.png +0 -0
  56. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_dark.svg +0 -0
  57. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_light.png +0 -0
  58. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_light.svg +0 -0
  59. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/sample_embedding_diagram.png +0 -0
  60. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_templates/site-nav.html +0 -0
  61. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/conf.py +0 -0
  62. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/examples.rst +0 -0
  63. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/index.rst +0 -0
  64. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/math.rst +0 -0
  65. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/notebooks.rst +0 -0
  66. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/preprocessing.rst +0 -0
  67. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/usage.rst +0 -0
  68. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/setup.sh +0 -0
  69. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/aliases.py +0 -0
  70. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/alleles.py +0 -0
  71. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/__init__.py +0 -0
  72. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/eval.py +0 -0
  73. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/metrics.py +0 -0
  74. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/theory.py +0 -0
  75. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/vdjdb.py +0 -0
  76. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/cohort.py +0 -0
  77. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/density.py +0 -0
  78. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/__init__.py +0 -0
  79. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/germline.py +0 -0
  80. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/junction.py +0 -0
  81. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/shm.py +0 -0
  82. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/__init__.py +0 -0
  83. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/pca.py +0 -0
  84. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/presets.py +0 -0
  85. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/prototypes.py +0 -0
  86. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/explain.py +0 -0
  87. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/generate.py +0 -0
  88. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/__init__.py +0 -0
  89. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/bundle.py +0 -0
  90. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/codec.py +0 -0
  91. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/decoder.py +0 -0
  92. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/diffusion.py +0 -0
  93. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/encoder.py +0 -0
  94. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/set_encoder.py +0 -0
  95. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/tokenize.py +0 -0
  96. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/train.py +0 -0
  97. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/py.typed +0 -0
  98. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/repertoire.py +0 -0
  99. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/__init__.py +0 -0
  100. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/README.md +0 -0
  101. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/__init__.py +0 -0
  102. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/build_gene_library.py +0 -0
  103. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/build_region_annotations.py +0 -0
  104. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/imgt_gene_library.txt +0 -0
  105. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/olga_gene_library.txt +0 -0
  106. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/region_annotations.txt +0 -0
  107. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/build_germline_dist.py +0 -0
  108. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGH.npz +0 -0
  109. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGK.npz +0 -0
  110. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGL.npz +0 -0
  111. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRA.npz +0 -0
  112. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRB.npz +0 -0
  113. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRD.npz +0 -0
  114. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRG.npz +0 -0
  115. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGH.npz +0 -0
  116. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGK.npz +0 -0
  117. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGL.npz +0 -0
  118. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRA.npz +0 -0
  119. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRB.npz +0 -0
  120. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRD.npz +0 -0
  121. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRG.npz +0 -0
  122. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/.gitkeep +0 -0
  123. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/generate_prototypes.py +0 -0
  124. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGH.tsv +0 -0
  125. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGK.tsv +0 -0
  126. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGL.tsv +0 -0
  127. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRA.tsv +0 -0
  128. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRB.tsv +0 -0
  129. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRD.tsv +0 -0
  130. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRG.tsv +0 -0
  131. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/manifest.json +0 -0
  132. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/mouse_TRA.tsv +0 -0
  133. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/mouse_TRB.tsv +0 -0
  134. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/track.py +0 -0
  135. {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/twin.py +0 -0
@@ -3,6 +3,110 @@
3
3
  All notable changes to `mirpy-lib` (import `mir`). This project follows semantic versioning; the v3 line is a
4
4
  greenfield ML/embedding rewrite (the classical v1.x/v2 toolkit is frozen on branch `legacy-v2`).
5
5
 
6
+ ## 4.0.0 — 2026-09-27
7
+
8
+ **Signatures rewritten from scratch.** The geometry half; the statistics half is vdjtools, which
9
+ this release requires at **>=4.0.1** -- the rsig fit and artifact I/O live in
10
+ `vdjtools.signature.corpus`, which does not exist before 4.0.0, and 4.0.0 never reached PyPI.
11
+ No legacy path, no backward compatibility, no artifact carried over.
12
+
13
+ ### Performance
14
+
15
+ `synthesize` now runs on the shared `vdjtools.signature.corpus.build_matrices`, so the rsig corpus
16
+ is built **across samples** in worker processes: each worker draws its own repertoires from
17
+ memory-mapped pools and returns one row of numbers. The artifact is bit-identical at every `n_jobs`,
18
+ because a sample is a pure function of its index. `mir corpus -j/--jobs` exposes it -- worker
19
+ **processes**, `0` = the whole allocation; the help text says which layer it reaches.
20
+
21
+ Measured on a 16-core M-series laptop, one seven-locus sample of 10,000 clonotypes per locus:
22
+ `raw_and_channels` is **0.136 s**, so the rsig row was never the expensive part of a build. What was
23
+ expensive is receptor generation, which is shared with vdjtools and is now parallel there.
24
+
25
+ ### The defect this fixes
26
+
27
+ `build_rsig.py` fitted `R_V`, `R_J` and `R_C` on `(10_000, 768)` — one row per **clonotype**, from
28
+ the bundled prototype panel — while every one of the 399 PC columns it produced was a **repertoire**
29
+ statistic, obtained by projecting a clone-weighted *mean* through those axes. PCA over 10,000
30
+ receptors evaluated at a mean is not PCA of repertoires: the two maximise variance in different units
31
+ and give different axes. A sample's coordinate averages ~400 effective clones, so variance between
32
+ samples along those axes is of order 1/sqrt(400) of the variance being maximised.
33
+
34
+ The artifact's `centre` and `scale` were fitted on **zero rows** and arrived from a separate corpus of
35
+ real samples. Two independent fits, stitched — which is how `blood` came to pair a centre of exactly
36
+ `0.0` with a scale plainly fitted from data on 64 `rsig:contrast` columns, putting a corpus-typical
37
+ sample **81 robust deviations** out with 885 of 885 samples of an independent cohort outside the
38
+ bound; and how `tissue` came to carry `blood`'s coverage constants for all seven loci to 17
39
+ significant digits while its own location and scale had genuinely been refitted.
40
+
41
+ Rotation, bounds, centre and scale now all come out of **one pass over one matrix of repertoires**,
42
+ per locus, using the same `vdjtools.signature.corpus` module that fits the statistics half — so the
43
+ two cannot drift into different notions of "standardised".
44
+
45
+ ### Added
46
+
47
+ - `mir.signature.features` — `Phi` and its functionals, a pure function of one sample plus the
48
+ bundled prototype panel.
49
+ - `mir.signature.signature` — `rsig`, `rsig_cohort`, `raw_and_channels`, `synthesize`. It also
50
+ **declares** the rsig half of the column contract, registering into vdjtools' layout at import.
51
+ - `mir corpus` — build and fit a corpus. Draws the same synthetic repertoires from the same seeds as
52
+ `vdjtools corpus`, so the two halves of a corpus name describe the same repertoires.
53
+ - `rsig:qc:-:winsor_frac` — what fraction of a row the corpus's bounds clamped. Never silent.
54
+
55
+ ### Removed
56
+
57
+ - `signature/assemble.py`, `blocks.py`, `reference.py`, `scale.py`,
58
+ `resources/signature/build_rsig.py`, and all 16 bundled artifacts (**8.4 MB**: six scale
59
+ references, `rsig_v2.npz`, `kmer_spaces_v1.npz`).
60
+ - **The `contrast` group — 231 columns — and nothing was lost.** It was `Psi = mass*(Phi - naive)`
61
+ with `naive` a separately drawn 20,000-sequence reference, because the rotation was fit-free and
62
+ needed an explicit subtraction point. The corpus centre now *is* that point: rotating through the
63
+ `naive` corpus subtracts the median `Phi` of unselected repertoires. One frozen vector and one
64
+ whole failure mode — a `naive` drawn against a different release of the recombination models, which
65
+ moved every contrast column by 0.1–1.6% per locus — replaced by choosing a corpus. `mass` remains a
66
+ feature, so the rotation still sees it.
67
+ - **`signature` / `signature_cohort`.** Each half has its own artifact now, so the wrapper's only real
68
+ job — one scale reference over both — no longer exists. Two calls and a polars join, and the halves
69
+ are disjoint by construction so the join cannot collide.
70
+ - **Tiers**, and the `mir presets` command. `--components` replaces both.
71
+ - CLI flags `--tier`, `--preset`, `--channels`, `--standardize`, `--scale`, `--clip`, `--squash`,
72
+ `--on-unscaled`, `--threads`. Each is pinned by a test asserting a non-zero exit.
73
+ - `examples/feature_vectors.py`, whose entire subject was presets.
74
+
75
+ ### Fixed
76
+
77
+ - **A one-part composition crashed rather than holing.** When every clone-size compartment falls
78
+ below `min_clonotypes`, only the closing residual is left — which is no composition at all, so
79
+ there are no ratios to take. `clr` raised on one part; the coordinates are now `nan`, and the
80
+ geometry itself is still measurable beside them.
81
+
82
+ ### Measured while building this
83
+
84
+ - **5 components reach 0.91–0.93 of the variance** on a small TRG/TRD corpus, against 0.34–0.48 for
85
+ the same count on the statistics half. The 256 `Phi` coordinates are correlated distances to one
86
+ panel, so this half is far more compressible — worth knowing before picking `--components`.
87
+ - **Rao agrees with `mir.repertoire.rao_dispersion` to 1e-9 relative**, cross-checked rather than
88
+ trusted: two spellings of one telescoping identity.
89
+ - **The corpus build is byte-identical across thread counts**, verified `cmp` on the npz.
90
+
91
+ ### Added: the shipped corpora, and a gate on the germline they were drawn from
92
+
93
+ `rsig_naive` and `rsig_memory` ship in `src/mir/resources/signature/` — 10,000 synthetic repertoires
94
+ each at 10,000 receptors, all seven human loci, `k = 128` per locus, 1.62 MB. Variance reached at 128
95
+ components runs from **0.9887** (IGH, `naive`) to **0.9992** (IGK), against 0.377–0.854 for the
96
+ statistics half, because the geometry half's raw features are a few hundred embedding coordinates
97
+ rather than a few thousand sparse usage shares.
98
+
99
+ The manifest records `models`, a per-locus hash of the **cut segments the generator drew from**, and
100
+ `Corpus.verify` refuses an artifact whose hash no longer matches the installed models. It replaces a
101
+ comparison against the library version, which was both too strict — a patch release invalidated every
102
+ corpus — and unable to see the thing that matters: repairing `TRBV4-3*02`'s anchor (vdjtools 4.0.0)
103
+ changed what every TRB pool contains while leaving the declared model version identical.
104
+
105
+ The `resources/signature/` directory is back, and `test_there_is_no_contrast_group_and_no_frozen_naive_vector`
106
+ now names what must stay gone — the prototype-cloud rotation, the frozen `naive` vector and the six
107
+ scale references — rather than asserting the directory does not exist. A corpus artifact is the
108
+ opposite of those: fitted on repertoires, named in every output, and gated on its germline.
109
+
6
110
  ## 3.20.2 — 2026-09-26
7
111
 
8
112
  ### Fixed — `unapply` accepted a `squash` it ignored
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: mirpy-lib
3
- Version: 3.20.2
3
+ Version: 4.0.0
4
4
  Summary: ML-oriented embeddings for immune receptor repertoires (TCR/BCR)
5
5
  Project-URL: Homepage, https://github.com/antigenomics/mirpy
6
6
  Project-URL: Repository, https://github.com/antigenomics/mirpy
@@ -24,7 +24,7 @@ Requires-Dist: polars
24
24
  Requires-Dist: scikit-learn
25
25
  Requires-Dist: scipy
26
26
  Requires-Dist: seqtree>=1.0.0
27
- Requires-Dist: vdjtools>=3.18.0
27
+ Requires-Dist: vdjtools>=4.0.1
28
28
  Provides-Extra: ann
29
29
  Requires-Dist: numba>=0.60; extra == 'ann'
30
30
  Requires-Dist: pynndescent; extra == 'ann'
@@ -38,7 +38,7 @@ Requires-Dist: matplotlib; extra == 'bench'
38
38
  Requires-Dist: seaborn; extra == 'bench'
39
39
  Provides-Extra: build
40
40
  Requires-Dist: biopython; extra == 'build'
41
- Requires-Dist: vdjtools[model]>=3.15.0; extra == 'build'
41
+ Requires-Dist: vdjtools[model]>=4.0.1; extra == 'build'
42
42
  Provides-Extra: dev
43
43
  Requires-Dist: psutil>=5; extra == 'dev'
44
44
  Requires-Dist: pytest-cov; extra == 'dev'
@@ -145,12 +145,9 @@ mir embed repertoires cohort/*.tsv.gz -o phi.tsv --mmd mmd.tsv
145
145
 
146
146
  # the portable signature -> one fixed, named, standardised feature vector per sample
147
147
  # One tool per half: mirpy emits the geometry, vdjtools the statistics. Join on sample_id.
148
- mir signature cohort/*.tsv.gz -o rsig.parquet # geometry; vdjtools emits vsig
149
- mir signature --preset classify --scale blood cohort/*.tsv.gz -o rsig.parquet
150
- mir signature --describe --preset classify # the column dictionary; reads no input
151
- mir signature --channels # the channel vocabulary; reads no input
152
- mir presets # the named feature sets, ranked
153
- mir presets classify # what one preset is, and when to use it
148
+ mir corpus --corpus naive --smoke -o rsig_naive.npz # fit a corpus; no cohort needed
149
+ mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet # geometry half
150
+ mir signature --corpus rsig_naive.npz --components 32 --describe # exactly what you get
154
151
  ```
155
152
 
156
153
  `mir embed clonotypes -h` / `mir embed repertoires -h` list every flag (species, locus,
@@ -506,52 +503,45 @@ regression, boosting or an MLP with no scaler of their own.
506
503
  Command line and library both, and they emit the same columns:
507
504
 
508
505
  ```bash
509
- mir signature --preset classify --scale blood cohort/*.tsv.gz -o sig.parquet
510
- mir signature --channels # what each group of columns measures; reads no input
506
+ mir corpus --corpus naive --smoke -o rsig_naive.npz
507
+ mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet
511
508
  ```
512
509
 
513
510
  ```python
514
- from mir.signature import signature, signature_cohort, channel_spec, describe, MODELS
511
+ from mir.signature import Corpus, rsig_cohort
515
512
 
516
- F = signature_cohort(samples, tier="standard") # one row per sample, 689 named columns
517
- describe("standard") # the column dictionary
513
+ corpus = Corpus.load("rsig_naive.npz") # REQUIRED -- there is no default
514
+ F = rsig_cohort(samples, corpus, n_jobs=0) # one row per sample
518
515
  ```
519
516
 
520
- Two halves, concatenated on `sample_id` and namespaced so they never collide: `vsig` (statistics of
521
- the clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig`
522
- (geometry — every column a linear functional, a norm, or a mixture coefficient of `Φ`). A column is
523
- `<sig>:<channel>:<locus>:<feature>`; the tiers `core` (153) ⊂ `standard` (689) ⊂ `full` (1404) are
524
- exact **index subsets** of one frozen order. The **channel** — the second field — is the level a
525
- finding is stated at: twenty names covering the whole vector, so "the classifier found something"
526
- becomes "IGH diversity and isotype composition carry it". See
527
- [**Channels**](https://docs.isalgo.dev/mirpy/channels.html).
528
-
529
- **The rotation is fit-free.** The map reducing `Φ` to coordinates is the PCA of the *bundled
530
- prototype panel* — zero samples enter it, so nobody's coordinates move when a reference is
531
- refreshed. Only location and scale come from data, and those are what `--scale` selects:
532
-
533
- | `--scale` | fitted on | scaled columns |
534
- |---|---|--:|
535
- | `deep-tcr` *(default)* | targeted deep TCR sequencing, 4,080 samples | 394 / 1403 |
536
- | `blood` | public SRA bulk RNA-seq, blood — 23,234 samples in 947 studies | 1377 / 1403 |
537
- | `tissue` | public SRA bulk RNA-seq, tissue — 13,577 samples in 1,024 studies | 1360 / 1403 |
538
-
539
- `deep-tcr` covers TRA and TRB only; the RNA-seq references cover all seven loci, which is what
540
- fills the B-cell columns. Each also ships an unweighted variant (`blood-unweighted`,
541
- `tissue-unweighted`): the default gives every **study** one vote, the unweighted variant every
542
- **sample**, so a single 3,000-sample submission would otherwise set the coordinates for everyone.
543
- Weighted is the default and it is not close — held-out-study agreement at 640 study groups passes
544
- **0.843–0.857** of columns against **0.533–0.551** unweighted. Take the unweighted fit only when
545
- your own cohort *is* one large study and you want its scale rather than a cross-study consensus.
517
+ Two halves, joined on `sample_id` and namespaced so they never collide: `vsig` (statistics of the
518
+ clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig` (geometry —
519
+ functionals of `Φ`). A column is `<sig>:<block>:<locus>:<feature>`. What comes out per locus is
520
+ `<sig>:pc:<locus>:PCnn` plus **channels**, which are carried in their own units and never rotated:
521
+ `rsig:div:*:rao` (sequence-aware diversity) and `rsig:qc:-:winsor_frac` (how much of the row the
522
+ corpus's bounds clamped). See [**Channels**](https://docs.isalgo.dev/mirpy/channels.html).
523
+
524
+ **A corpus is required, and it fixes everything that is fitted.** Bounds, centre, scale, rotation
525
+ and per-PC scaling all come out of one pass over one matrix of repertoires. There is no default: a
526
+ signature is comparable to another one only if both were rotated through the same corpus, and
527
+ nothing about the numbers would say otherwise.
528
+
529
+ Until 4.0 the rotation was *fit-free* — the PCA of the bundled prototype panel, 10,000 individual
530
+ **clonotypes** — while every one of the 399 PC columns it produced was a **repertoire** statistic,
531
+ and its centre and scale were fitted on zero rows of that artifact and arrived from a separate
532
+ corpus. Two independent fits, stitched; one shipped reference paired a centre of exactly `0.0` with
533
+ a scale plainly fitted from data and put a corpus-typical sample **81 robust deviations** out.
534
+
535
+ The two synthetic corpora need no cohort at all and are reproducible by anyone who installs the
536
+ library — `naive` (every clone size 1, what the recombination model emits) and `memory` (Zipf
537
+ rank-abundance clone sizes). `deep-tcr`, `blood` and `tissue` are fitted on real cohorts.
546
538
 
547
539
  **Holes are never zeros.** An unsequenced locus, a compartment below its clonotype floor, or a
548
540
  statistic the sample is too shallow to estimate is `nan` plus a `mask:` column, because a model that
549
- reads "absent" as "zero" reads an unsequenced chain as biology. What the signature does *not* fix is
550
- batch: the spread transfers across cohorts and the offset does not, so `fit_scale(..., group=...)`
551
- hands you the list of batch-sensitive columns rather than leaving you to find it.
541
+ reads "absent" as "zero" reads an unsequenced chain as biology.
552
542
 
553
- Full documentation — presets, transforms, what is fitted and what is not, and the end-to-end recipe
554
- for a folder of AIRR files: [**Signature**](https://docs.isalgo.dev/mirpy/signature.html).
543
+ Full documentation — the corpora, the supports that decide which tail is trimmed, what is fitted and
544
+ what is not: [**Signature**](https://docs.isalgo.dev/mirpy/signature.html).
555
545
 
556
546
  ## Exposure trajectory, generative loop, digital twin
557
547
 
@@ -89,12 +89,9 @@ mir embed repertoires cohort/*.tsv.gz -o phi.tsv --mmd mmd.tsv
89
89
 
90
90
  # the portable signature -> one fixed, named, standardised feature vector per sample
91
91
  # One tool per half: mirpy emits the geometry, vdjtools the statistics. Join on sample_id.
92
- mir signature cohort/*.tsv.gz -o rsig.parquet # geometry; vdjtools emits vsig
93
- mir signature --preset classify --scale blood cohort/*.tsv.gz -o rsig.parquet
94
- mir signature --describe --preset classify # the column dictionary; reads no input
95
- mir signature --channels # the channel vocabulary; reads no input
96
- mir presets # the named feature sets, ranked
97
- mir presets classify # what one preset is, and when to use it
92
+ mir corpus --corpus naive --smoke -o rsig_naive.npz # fit a corpus; no cohort needed
93
+ mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet # geometry half
94
+ mir signature --corpus rsig_naive.npz --components 32 --describe # exactly what you get
98
95
  ```
99
96
 
100
97
  `mir embed clonotypes -h` / `mir embed repertoires -h` list every flag (species, locus,
@@ -450,52 +447,45 @@ regression, boosting or an MLP with no scaler of their own.
450
447
  Command line and library both, and they emit the same columns:
451
448
 
452
449
  ```bash
453
- mir signature --preset classify --scale blood cohort/*.tsv.gz -o sig.parquet
454
- mir signature --channels # what each group of columns measures; reads no input
450
+ mir corpus --corpus naive --smoke -o rsig_naive.npz
451
+ mir signature --corpus rsig_naive.npz cohort/*.tsv.gz -o rsig.parquet
455
452
  ```
456
453
 
457
454
  ```python
458
- from mir.signature import signature, signature_cohort, channel_spec, describe, MODELS
455
+ from mir.signature import Corpus, rsig_cohort
459
456
 
460
- F = signature_cohort(samples, tier="standard") # one row per sample, 689 named columns
461
- describe("standard") # the column dictionary
457
+ corpus = Corpus.load("rsig_naive.npz") # REQUIRED -- there is no default
458
+ F = rsig_cohort(samples, corpus, n_jobs=0) # one row per sample
462
459
  ```
463
460
 
464
- Two halves, concatenated on `sample_id` and namespaced so they never collide: `vsig` (statistics of
465
- the clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig`
466
- (geometry — every column a linear functional, a norm, or a mixture coefficient of `Φ`). A column is
467
- `<sig>:<channel>:<locus>:<feature>`; the tiers `core` (153) ⊂ `standard` (689) ⊂ `full` (1404) are
468
- exact **index subsets** of one frozen order. The **channel** — the second field — is the level a
469
- finding is stated at: twenty names covering the whole vector, so "the classifier found something"
470
- becomes "IGH diversity and isotype composition carry it". See
471
- [**Channels**](https://docs.isalgo.dev/mirpy/channels.html).
472
-
473
- **The rotation is fit-free.** The map reducing `Φ` to coordinates is the PCA of the *bundled
474
- prototype panel* — zero samples enter it, so nobody's coordinates move when a reference is
475
- refreshed. Only location and scale come from data, and those are what `--scale` selects:
476
-
477
- | `--scale` | fitted on | scaled columns |
478
- |---|---|--:|
479
- | `deep-tcr` *(default)* | targeted deep TCR sequencing, 4,080 samples | 394 / 1403 |
480
- | `blood` | public SRA bulk RNA-seq, blood — 23,234 samples in 947 studies | 1377 / 1403 |
481
- | `tissue` | public SRA bulk RNA-seq, tissue — 13,577 samples in 1,024 studies | 1360 / 1403 |
482
-
483
- `deep-tcr` covers TRA and TRB only; the RNA-seq references cover all seven loci, which is what
484
- fills the B-cell columns. Each also ships an unweighted variant (`blood-unweighted`,
485
- `tissue-unweighted`): the default gives every **study** one vote, the unweighted variant every
486
- **sample**, so a single 3,000-sample submission would otherwise set the coordinates for everyone.
487
- Weighted is the default and it is not close — held-out-study agreement at 640 study groups passes
488
- **0.843–0.857** of columns against **0.533–0.551** unweighted. Take the unweighted fit only when
489
- your own cohort *is* one large study and you want its scale rather than a cross-study consensus.
461
+ Two halves, joined on `sample_id` and namespaced so they never collide: `vsig` (statistics of the
462
+ clone-size vector, from [vdjtools](https://github.com/antigenomics/vdjtools)) and `rsig` (geometry —
463
+ functionals of `Φ`). A column is `<sig>:<block>:<locus>:<feature>`. What comes out per locus is
464
+ `<sig>:pc:<locus>:PCnn` plus **channels**, which are carried in their own units and never rotated:
465
+ `rsig:div:*:rao` (sequence-aware diversity) and `rsig:qc:-:winsor_frac` (how much of the row the
466
+ corpus's bounds clamped). See [**Channels**](https://docs.isalgo.dev/mirpy/channels.html).
467
+
468
+ **A corpus is required, and it fixes everything that is fitted.** Bounds, centre, scale, rotation
469
+ and per-PC scaling all come out of one pass over one matrix of repertoires. There is no default: a
470
+ signature is comparable to another one only if both were rotated through the same corpus, and
471
+ nothing about the numbers would say otherwise.
472
+
473
+ Until 4.0 the rotation was *fit-free* — the PCA of the bundled prototype panel, 10,000 individual
474
+ **clonotypes** — while every one of the 399 PC columns it produced was a **repertoire** statistic,
475
+ and its centre and scale were fitted on zero rows of that artifact and arrived from a separate
476
+ corpus. Two independent fits, stitched; one shipped reference paired a centre of exactly `0.0` with
477
+ a scale plainly fitted from data and put a corpus-typical sample **81 robust deviations** out.
478
+
479
+ The two synthetic corpora need no cohort at all and are reproducible by anyone who installs the
480
+ library — `naive` (every clone size 1, what the recombination model emits) and `memory` (Zipf
481
+ rank-abundance clone sizes). `deep-tcr`, `blood` and `tissue` are fitted on real cohorts.
490
482
 
491
483
  **Holes are never zeros.** An unsequenced locus, a compartment below its clonotype floor, or a
492
484
  statistic the sample is too shallow to estimate is `nan` plus a `mask:` column, because a model that
493
- reads "absent" as "zero" reads an unsequenced chain as biology. What the signature does *not* fix is
494
- batch: the spread transfers across cohorts and the offset does not, so `fit_scale(..., group=...)`
495
- hands you the list of batch-sensitive columns rather than leaving you to find it.
485
+ reads "absent" as "zero" reads an unsequenced chain as biology.
496
486
 
497
- Full documentation — presets, transforms, what is fitted and what is not, and the end-to-end recipe
498
- for a folder of AIRR files: [**Signature**](https://docs.isalgo.dev/mirpy/signature.html).
487
+ Full documentation — the corpora, the supports that decide which tail is trimmed, what is fitted and
488
+ what is not: [**Signature**](https://docs.isalgo.dev/mirpy/signature.html).
499
489
 
500
490
  ## Exposure trajectory, generative loop, digital twin
501
491
 
@@ -127,23 +127,26 @@ Two halves, concatenated on ``sample_id`` and namespaced so they never collide:
127
127
  Geometry — every column a linear functional, a norm, or a mixture coefficient of the
128
128
  prototype-sum measure. Computed here.
129
129
 
130
- Both share one frozen column contract, imported from
131
- :mod:`vdjtools.signature.layout`: a column name is always ``<sig>:<block>:<locus>:<feature>``
132
- (``-`` for a cross-locus column), and the tiers ``core`` (153) ⊂ ``standard`` (689) ⊂ ``full``
133
- (1404) are exact **index subsets** of one column order.
130
+ Both share one column contract, imported from :mod:`vdjtools.signature.layout`: a column name is
131
+ always ``<sig>:<block>:<locus>:<feature>`` (``-`` for a cross-locus column). What a signature emits
132
+ per locus is ``<sig>:pc:<locus>:PCnn`` — rotated coordinates — plus **channels**, which are carried
133
+ in their own units and never rotated.
134
134
 
135
135
  **Holes are never zeros.** An unsequenced locus, a compartment below its clonotype floor, or a
136
136
  statistic the sample is too shallow to estimate is ``nan`` plus a ``mask:`` column — because a model
137
137
  that reads "absent" as "zero" reads an unsequenced chain as biology.
138
138
 
139
- **The rotation is fit-free.** It is the PCA of the bundled prototype panel embedded against itself —
140
- zero samples, so nobody's coordinates move when a reference is refreshed, and it covers all seven
141
- loci. Only location and scale come from data. See :doc:`signature` for which scale reference to use.
139
+ **The rotation comes from a corpus, and a corpus is required.** Bounds, centre, scale, rotation and
140
+ per-PC scaling all come out of one pass over one matrix of repertoires. There is no default corpus: a
141
+ signature is comparable to another one only if both were rotated through the same one, and nothing
142
+ about the numbers would say otherwise. Until 4.0 the rotation was fit-free — fitted on 10,000
143
+ individual clonotypes from the prototype panel — while every column it produced was a repertoire
144
+ statistic; :doc:`signature` records what that cost.
142
145
 
143
146
  **The full API for this package is on its own page** — see :doc:`signature`, which documents
144
- ``mir.signature``, ``mir.signature.assemble``, ``mir.signature.blocks``, ``mir.signature.reference``
145
- and ``mir.signature.scale`` alongside the measurements behind each design choice. It is not repeated
146
- here so that every symbol has one canonical entry.
147
+ ``mir.signature``, ``mir.signature.features`` and ``mir.signature.signature`` alongside the
148
+ measurements behind each design choice. It is not repeated here so that every symbol has one
149
+ canonical entry.
147
150
 
148
151
  Explainable readouts (``mir.explain``)
149
152
  --------------------------------------
@@ -360,7 +363,7 @@ Command-line interface (``mir``)
360
363
  --------------------------------
361
364
 
362
365
  ``pip install mirpy-lib`` installs a ``mir`` console script (also ``python -m mir.cli``) with four
363
- commands: two embedding scales, plus the portable signature and its column presets.
366
+ commands: two embedding scales, plus the portable signature and the corpus it is rotated through.
364
367
 
365
368
  Both ``embed`` commands drop non-coding clonotypes (stop codon / legacy out-of-frame
366
369
  ``junction_aa``) before embedding, and there is **no flag to disable it**: a stop codon is in
@@ -385,28 +388,27 @@ non-productive fraction is the thing you want.
385
388
  ``--threads``, ``--seed``, ``-o``.
386
389
 
387
390
  ``mir signature INPUT...``
388
- AIRR clonotype tables → **one fixed-width named feature vector per sample**, standardised
389
- against a frozen reference so a downstream model needs no scaler of its own. This is the command
390
- to send a collaborator. Flags: ``--tier {core,standard,full}``, ``--preset NAME``,
391
- ``--species``, ``--weight {log2p1,duplicate_count,distinct,log1p,anscombe}``,
392
- ``--standardize {reference,none}``, ``--scale NAME|PATH`` (which scale reference to
393
- standardise against — a bundled model name or a path; a named-but-missing one raises rather
394
- than silently producing an unstandardised matrix), ``--jobs`` / ``-j`` (0 = every core; renamed from ``--threads``),
395
- ``--describe`` (print the column dictionary and read no input), ``--channels`` (print the
396
- channel vocabulary and read no input), ``-o``.
397
-
398
- This emits the ``rsig`` half alone — 528 columns at the ``standard`` tier. ``vdjtools
399
- signature`` emits the ``vsig`` half and reports how many ``rsig`` columns it left to this
400
- command; the two concatenate on ``sample_id`` for the full 689.
401
- :doc:`signature` covers the scale references and :doc:`channels` the vocabulary the columns
402
- group into.
403
-
404
- ``mir presets [NAME]``
405
- The named column subsets and their ranking — ``compact`` (86), ``classify`` (615),
406
- ``transfer`` (550), ``geometry`` (514), ``statistics`` (101), ``bcell`` (271), ``full`` (1404),
407
- ``nuisance`` (74, ranked *avoid*). With no argument, the whole table; with a name, that preset's
408
- column list. A preset resolves from the frozen layout alone, so two people choosing the same
409
- name get the same columns in the same order.
391
+ AIRR clonotype tables → **one fixed-width named feature vector per sample**, rotated through a
392
+ named corpus so a downstream model needs no scaler of its own. This is the command to send a
393
+ collaborator. Flags: ``--corpus NAME|PATH`` (**required** — there is no default),
394
+ ``--winsorize {features,pcs,none}``, ``--winsor-p P``, ``--components N`` (an integer count or a
395
+ variance fraction), ``--species``,
396
+ ``--weight {log2p1,duplicate_count,distinct,log1p,anscombe}``, ``--columns FILE``,
397
+ ``--jobs`` / ``-j`` (0 = every core; worker **processes**), ``--on-duplicate {error,sum}``,
398
+ ``--describe`` (print the columns *this invocation* emits and read no input), ``-o``.
399
+
400
+ This emits the ``rsig`` half alone. ``vdjtools signature`` emits the ``vsig`` half; run both
401
+ against the **same corpus name and seed** and join on ``sample_id``. :doc:`signature` covers the
402
+ corpora and :doc:`channels` the columns that are carried rather than rotated.
403
+
404
+ ``mir corpus``
405
+ Build a synthetic corpus and fit its rotation, bounds and scaling. Uses **no samples from
406
+ anybody's cohort** — every receptor is drawn from vdjtools' bundled recombination models — so the
407
+ artifact is reproducible by anyone who installs the library, and the build is byte-identical
408
+ across processes and thread counts. Flags: ``--corpus {naive,memory}``, ``-o/--output``,
409
+ ``--samples N``, ``--size {N,n_eff,p05,p95}``, ``--components N``, ``--winsorize``,
410
+ ``--winsor-p``, ``--seed``, ``--loci``, ``--source {olga,learned,arda}``, ``--species``,
411
+ ``--smoke``.
410
412
 
411
413
  .. automodule:: mir.cli
412
414
  :members: main, build_parser
@@ -0,0 +1,80 @@
1
+ Channels
2
+ ========
3
+
4
+ A **channel** is a named family of columns emitted in its own units, never passed through the
5
+ rotation. The full vocabulary — including the thirteen ``vsig`` channels — is documented in
6
+ `vdjtools' channel reference <https://docs.isalgo.dev/vdjtools/channels.html>`_; this page covers
7
+ mirpy's two and the reason the split exists.
8
+
9
+ Why a channel is not rotated
10
+ ----------------------------
11
+
12
+ A provenance number that has been mixed with the measurements it was supposed to qualify is no longer
13
+ provenance. If ``winsor_frac`` went through a rotation, the coordinate carrying it would also carry
14
+ geometry, and a caller could no longer ask "is this row comparable to ours at all?" — which is the
15
+ only question that column exists to answer.
16
+
17
+ The split is by *role*, not by cost: a **measurement of the repertoire** is a raw feature, transformed
18
+ and winsorized and rotated and scaled; a **statement about the row itself** is a channel.
19
+
20
+ The two rsig channels
21
+ ---------------------
22
+
23
+ .. list-table::
24
+ :header-rows: 1
25
+ :widths: 30 10 60
26
+
27
+ * - channel
28
+ - loci
29
+ - what it says
30
+ * - ``rsig:div:<locus>:rao``
31
+ - 7
32
+ - Rao quadratic entropy in embedding coordinates, ``log1p``-stabilised and self-pair corrected.
33
+ A *sequence-aware* diversity: it sees that two clonotypes are one substitution apart, which no
34
+ Hill number can. Carried rather than rotated because the head-to-head against the statistics
35
+ half's coverage-standardised Hill numbers is the result, not a redundancy.
36
+ * - ``rsig:qc:-:winsor_frac``
37
+ - —
38
+ - What fraction of this row's finite values the corpus's bounds clamped. A value near 1.0 means
39
+ this sample does not belong to this corpus — not that it is unusual.
40
+
41
+ ``depth`` is **not** a channel
42
+ ------------------------------
43
+
44
+ ``rsig:depth:<locus>:n_eff`` and ``:mass`` are raw features and go through the rotation, even though
45
+ they look like provenance. They are measurements of the repertoire: ``n_eff`` is a Hill number of the
46
+ clone weights the geometry actually uses, and ``mass`` is the share of the repertoire ever drawn. The
47
+ compartment shares are depth-fragile on purpose and these two are the covariates that make that
48
+ adjustable, so a rotation that could not see them would be worse, not cleaner.
49
+
50
+ Reading a row
51
+ -------------
52
+
53
+ .. code-block:: python
54
+
55
+ from mir.signature import Corpus, rsig
56
+
57
+ corpus = Corpus.load("naive_rsig.npz")
58
+ row = rsig(sample, corpus)
59
+
60
+ row["rsig:qc:-:winsor_frac"] # did the corpus's bounds edit this sample?
61
+ row["rsig:div:TRB:rao"] # sequence-aware diversity, in its own units
62
+ row["rsig:depth:TRB:n_eff"] # how many clones are effectively behind this Phi?
63
+
64
+ Declaring a channel
65
+ -------------------
66
+
67
+ ``rsig`` registers its groups and channels into vdjtools' registry at import of
68
+ :mod:`mir.signature.signature`, with
69
+ :func:`~vdjtools.signature.layout.register_raw` and
70
+ :func:`~vdjtools.signature.layout.register_channel`. The contract lives in vdjtools because mirpy
71
+ depends on vdjtools and not the reverse; nothing in vdjtools imports ``mir``.
72
+
73
+ .. code-block:: python
74
+
75
+ from mir.signature import channel_columns, channels, raw_groups, support_of
76
+
77
+ [g.name for g in raw_groups("rsig")] # phiv, phij, phic, depth, band, band_igh
78
+ [c.name for c in channels("rsig")] # div, qc
79
+ support_of("rsig:phiv:TRB:P001") # 'nonneg' -- a mean of distances
80
+ support_of("rsig:band:TRB:top") # 'real' -- a clr coordinate