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.
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/CHANGELOG.md +104 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/PKG-INFO +35 -45
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/README.md +32 -42
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/api.rst +35 -33
- mirpy_lib-4.0.0/docs/channels.rst +80 -0
- mirpy_lib-4.0.0/docs/signature.rst +249 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/pyproject.toml +6 -2
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/skills/mirpy/SKILL.md +57 -63
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/__init__.py +1 -1
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/cli.py +180 -243
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/tcremp.py +2 -2
- mirpy_lib-4.0.0/src/mir/resources/signature/rsig_memory.json +94 -0
- mirpy_lib-4.0.0/src/mir/resources/signature/rsig_memory.npz +0 -0
- mirpy_lib-4.0.0/src/mir/resources/signature/rsig_naive.json +94 -0
- mirpy_lib-4.0.0/src/mir/resources/signature/rsig_naive.npz +0 -0
- mirpy_lib-4.0.0/src/mir/signature/__init__.py +44 -0
- mirpy_lib-4.0.0/src/mir/signature/features.py +222 -0
- mirpy_lib-4.0.0/src/mir/signature/signature.py +327 -0
- mirpy_lib-3.20.2/docs/channels.rst +0 -218
- mirpy_lib-3.20.2/docs/signature.rst +0 -1051
- mirpy_lib-3.20.2/src/mir/resources/signature/build_rsig.py +0 -201
- mirpy_lib-3.20.2/src/mir/resources/signature/kmer_spaces_v1.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_u_v4.json +0 -42
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_u_v4.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_w_v4.json +0 -42
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_blood_w_v4.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_u_v4.json +0 -42
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_u_v4.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_w_v4.json +0 -42
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_tissue_w_v4.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v2.json +0 -50
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v2.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v3.json +0 -38
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_scale_v3.npz +0 -0
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_v2.json +0 -25
- mirpy_lib-3.20.2/src/mir/resources/signature/rsig_v2.npz +0 -0
- mirpy_lib-3.20.2/src/mir/signature/__init__.py +0 -136
- mirpy_lib-3.20.2/src/mir/signature/assemble.py +0 -523
- mirpy_lib-3.20.2/src/mir/signature/blocks.py +0 -270
- mirpy_lib-3.20.2/src/mir/signature/reference.py +0 -313
- mirpy_lib-3.20.2/src/mir/signature/scale.py +0 -1009
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/.gitignore +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/LICENSE +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_dark_bg.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/assets/mirpy_light_bg.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/data/signature_reference_studies.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/Makefile +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_ext/themed_graphviz.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/custom.css +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/depth_robustness.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_dark.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_dark.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_light.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/mirpy_light.svg +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_static/sample_embedding_diagram.png +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/_templates/site-nav.html +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/conf.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/examples.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/index.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/math.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/notebooks.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/preprocessing.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/docs/usage.rst +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/setup.sh +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/aliases.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/alleles.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/eval.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/metrics.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/theory.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/bench/vdjdb.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/cohort.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/density.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/germline.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/junction.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/distances/shm.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/pca.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/presets.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/embedding/prototypes.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/explain.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/generate.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/bundle.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/codec.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/decoder.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/diffusion.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/encoder.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/set_encoder.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/tokenize.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/ml/train.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/py.typed +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/repertoire.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/README.md +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/__init__.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/build_gene_library.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/build_region_annotations.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/imgt_gene_library.txt +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/olga_gene_library.txt +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/gene_library/region_annotations.txt +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/build_germline_dist.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGH.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGK.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_IGL.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRA.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRB.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRD.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/human_TRG.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGH.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGK.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_IGL.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRA.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRB.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRD.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/germline_dist/mouse_TRG.npz +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/.gitkeep +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/generate_prototypes.py +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGH.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGK.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_IGL.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRA.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRB.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRD.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/human_TRG.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/manifest.json +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/mouse_TRA.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/resources/prototypes/mouse_TRB.tsv +0 -0
- {mirpy_lib-3.20.2 → mirpy_lib-4.0.0}/src/mir/track.py +0 -0
- {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
|
+
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>=
|
|
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]>=
|
|
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
|
|
149
|
-
mir signature --
|
|
150
|
-
mir signature --
|
|
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
|
|
510
|
-
mir signature --
|
|
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
|
|
511
|
+
from mir.signature import Corpus, rsig_cohort
|
|
515
512
|
|
|
516
|
-
|
|
517
|
-
|
|
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,
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
`<sig
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
`
|
|
540
|
-
|
|
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.
|
|
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 —
|
|
554
|
-
|
|
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
|
|
93
|
-
mir signature --
|
|
94
|
-
mir signature --
|
|
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
|
|
454
|
-
mir signature --
|
|
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
|
|
455
|
+
from mir.signature import Corpus, rsig_cohort
|
|
459
456
|
|
|
460
|
-
|
|
461
|
-
|
|
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,
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
`<sig
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
`
|
|
484
|
-
|
|
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.
|
|
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 —
|
|
498
|
-
|
|
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
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
|
140
|
-
|
|
141
|
-
|
|
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.
|
|
145
|
-
|
|
146
|
-
|
|
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
|
|
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**,
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
``--
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
``--describe`` (print the
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
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
|