mirpy-lib 3.6.0__tar.gz → 3.7.0__tar.gz

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/CHANGELOG.md

@@ -3,6 +3,38 @@
 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`).
 
+## 3.7.0 — 2026-07-30
+
+Four new modules: a PhenoPath-style exposure trajectory, the generative loop's mechanical and
+research halves, and the digital twin that glues them to the digital donor — plus a repertoire-level
+exposure channel. No public API removed; a minor bump.
+
+### Added
+
+- **`mir.track.fit_exposure_trajectory`** — a covariate-disentangled latent trajectory over any
+  per-sample channel matrix (PhenoPath, Campbell & Yau 2018, *Nat. Commun.* 9:2442,
+  doi:10.1038/s41467-018-04696-6, adapted from genes×cells to repertoire-channels×samples): infers a
+  shared exposure/progression pseudotime `tau` while separating out which channels respond to it
+  differently by a known covariate (`TrajectoryFit.top_interactions`). A simplified closed-form
+  alternating fit (per-channel ridge + GLS trajectory update + iteratively-reweighted ARD shrinkage
+  on the interaction term), not a literal reimplementation of PhenoPath's CAVI engine. Torch-free.
+- **`mir.generate`** — the generative loop's mechanical half: `DescriptorDensity` (optionally
+  class-conditional Gaussian, Ledoit-Wolf shrinkage) over `RepertoireDescriptor` vectors;
+  `sample`/`evolve` (perturb one coordinate, propagate the coupled shift via the fitted covariance's
+  conditional mean) promote the ad-hoc `benchmark_repertoire_tcga_insilico.py` `np.cov`-slope pattern
+  into a reusable library object. Torch-free.
+- **`mir.ml.diffusion`** (needs `[ml]`) — the generative loop's research half: a compact conditional
+  DDPM/DDIM generator (classifier-free guidance) over a compact descriptor/code space, sharing
+  `DescriptorDensity`'s `sample(n, condition=, seed=)` call shape so either generator drops in
+  unchanged. `DiffusionModel.save`/`load` mirrors `CodecBundle`'s shape.
+- **`mir.twin.DonorTwin`/`make_twins`** — the digital twin: glue one donor's `RepertoireDescriptor` +
+  an optional `mir.track` trajectory position + covariate into one object; `.perturb()` and
+  `.simulate()` accept either generator.
+- **`mir.density.exposure_score`/`exposure_channel`** — aggregate a per-clonotype
+  `neighbor_enrichment` result into repertoire-level exposure scalars (breadth, abundance-weighted
+  mass fraction, mean log2 fold), ready for `ChannelBuilder`/`DonorCohort extra_channels` — exposure
+  detection promoted from clone-level to a first-class cohort channel.
+
 ## 3.6.0 — 2026-07-30
 
 Default-on functional filtering, a new default clone-size weight for repertoire embedding, and a

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/CLAUDE.md

@@ -114,8 +114,28 @@ fix were added to `vdjtools` under the owner's direction (this is that owner's e
   high `delta` + `delta_out≈0` is the **redundancy** signature. `channel_drivers` hops channel→clonotypes
   via `class_witness`, but **only** for a channel declared `attributable` (a kernel mean); a Hill number
   has no clonotype pre-image and it raises. Depends one-way on `repertoire.py`; nothing there changed.
+- `track.py` — **exposure trajectory** (repertoire-level exposure detection, complementing
+  `density.py`'s clone-level TCRNET/ALICE): `fit_exposure_trajectory(X, covariates, ...)`, a
+  PhenoPath-style (Campbell & Yau 2018) covariate-disentangled latent factor model —
+  `Y[n,g] = c_g + alpha_g.x_n + (kappa_g + gamma_g.x_n)*tau_n + eps` — fit by alternating closed-form
+  per-channel ridge regression and a GLS trajectory update (a simplified, non-CAVI approximation to
+  PhenoPath's inference; ARD-style iteratively-reweighted shrinkage on `gamma`, the covariate x
+  trajectory interaction). `TrajectoryFit.top_interactions()` ranks channels. Fills the
+  analysis-repo ROADMAP's Phase 5 (embedding trajectory). Torch-free.
+- `generate.py` — the **generative loop, mechanical half** (ROADMAP Phase 2): `DescriptorDensity`
+  (optionally class-conditional Gaussian, Ledoit-Wolf shrinkage) over `RepertoireDescriptor` vectors;
+  `sample` draws new synthetic donor states, `evolve` perturbs one coordinate and propagates the
+  coupled shift via the fitted covariance's conditional mean — promotes the ad-hoc
+  `benchmark_repertoire_tcga_insilico.py` `np.cov`-slope pattern into a reusable library object.
+  Torch-free.
+- `twin.py` — the **digital twin**: `DonorTwin`/`make_twins` glue one donor's `RepertoireDescriptor`
+  + an optional `track.py` trajectory position + covariate into one object; `.perturb()` (via
+  `generate.evolve`) and `.simulate()` (via `generate.DescriptorDensity` or `ml.diffusion.DiffusionModel`
+  — both share the `sample(n, condition=, seed=)` shape, so either drops in). Torch-free itself.
 - `ml/` — Part 2 (torch), neural codecs + `set_encoder.py` (learned repertoire track: Set-Transformer/DeepRC
-  attention pooling + `SetEncoderBundle`).
+  attention pooling + `SetEncoderBundle`) + `diffusion.py` (**generative loop, research half**: compact
+  conditional DDPM/DDIM with classifier-free guidance over a compact descriptor/code space, standardized
+  internally with `x0`-clipping for DDIM stability; `DiffusionModel.save`/`load` mirrors `CodecBundle`).
 - `cli.py` — the `mir` console script (argparse, stdlib): `embed clonotypes` (TCREmp table) /
   `embed repertoires` (per-locus `fit_repertoire_space`→`sample_embedding` Φ(S), optional `--mmd`).
   Reads via `vdjtools.io.read`; writes TSV/parquet.
@@ -155,9 +175,18 @@ fix were added to `vdjtools` under the owner's direction (this is that owner's e
   cleanup) — the "vdjtools at the embedding level" audit +
   plan (three verbs: make / measure / generate-decode). **Phase 0** (robustness + optimization quick wins)
   and **Phase 1** (cohort tier: `bench/eval.py`, `repertoire.{fit_repertoire_spaces,centroid_atypicality}`,
-  `cohort.py` digital donor) are **DONE**. Next: **Phase 2** generative loop (`generate.py` `DescriptorDensity`
-  + `evolve`/`sample`, `CodecBundle.from_unified/from_decoder`), then multimodal encoders + embedding
-  trajectory. **Analysis-repo follow-up:** refactor `_tcga_embedding.build_embedding` onto
+  `cohort.py` digital donor) are **DONE**. **Phase 2 (generative loop, mechanical half) — DONE**:
+  `generate.py` `DescriptorDensity` (`sample`/`evolve`) ships, promoting the ad-hoc
+  `benchmark_repertoire_tcga_insilico.py` `np.cov`-slope pattern; `CodecBundle.from_unified/from_decoder`
+  is still open. **Phase 5 (embedding trajectory) — partially addressed**: `track.py`
+  `fit_exposure_trajectory` (a PhenoPath-style covariate-disentangled latent trajectory, Campbell &
+  Yau 2018) fills this rather than the originally-sketched `track.repertoire_trajectory`
+  Φ-velocity idea — a different, arguably more principled approach to the same phase; `clonotype_flux`
+  (differential enrichment) is still open. Also new: `mir.ml.diffusion` (generative loop, **research
+  half** — conditional DDPM/DDIM, complementing the linear `DescriptorDensity`) and `twin.py`
+  (`DonorTwin`/`make_twins` — glues descriptor + trajectory + generator into one perturb/simulate
+  object). Next: Phase 3 (embedding inversion / generation), Phase 4 (multimodal encoders).
+  **Analysis-repo follow-up:** refactor `_tcga_embedding.build_embedding` onto
   `cohort.fit_donor_embeddings` (+ `extra_channels` for isotype/composition/atypicality) and re-verify the
   pan-cancer ΔC numbers. NB Phase 0 flipped the density default to `backend="kdtree"` — re-verify any
   recorded balloon-mode baselines (±1 boundary counts).

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirpy-lib
-Version: 3.6.0
+Version: 3.7.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
@@ -228,7 +228,10 @@ Provenance and the regenerate command are in [`SOURCES.md`](SOURCES.md).
 | `mir.repertoire` | sample-level (repertoire) embedding — RFF kernel mean ‖ Hill diversity ‖ second moment; MMD / HLA-stratified distance; motif witness; `centroid_atypicality`, multi-locus `fit_repertoire_spaces` (Theory §T.7) |
 | `mir.explain` | named-channel fusion (`ChannelBuilder`) + scorer-agnostic ablation (`channel_report`/`channel_drivers`) — which part of Φ carries the signal (§T.7) |
 | `mir.cohort` | the **digital donor** — multi-chain `fit_donor_embeddings`/`DonorCohort` (+ `transform`/`save`/`load`) + `residualize` / `cluster_samples` / `incidence_biomarkers` (§T.7) |
-| `mir.ml` | neural codecs (forward/inverse/Pgen/unified) + learned repertoire `set_encoder` (Set-Transformer/DeepRC) — Part 2, experimental; `[ml]` extra |
+| `mir.track` | **exposure trajectory** — PhenoPath-style covariate-disentangled latent progression axis (`fit_exposure_trajectory`) over any channel matrix; repertoire-level exposure detection |
+| `mir.generate` | the **generative loop** (mechanical half) — `DescriptorDensity`: sample new synthetic donor states / `evolve` one along a coordinate, over `RepertoireDescriptor` |
+| `mir.twin` | the **digital twin** — `DonorTwin`/`make_twins`: perturb or resample one donor's state through a `mir.generate`/`mir.ml.diffusion` generator |
+| `mir.ml` | neural codecs (forward/inverse/Pgen/unified) + learned repertoire `set_encoder` (Set-Transformer/DeepRC) + conditional **diffusion generator** (`mir.ml.diffusion`, the generative loop's research half) — Part 2, experimental; `[ml]` extra |
 
 ## Background subtraction & clustering (`mir.density`)
 
@@ -306,6 +309,47 @@ TRA and class II) lives in the second moment / witness. A learned co-equal set e
 (T7) live in the companion [`2026-mirpy-analysis`](https://github.com/antigenomics) repo
 (`benchmarks/{BENCHMARKS,THEORY}.md`) alongside the benchmark scripts.
 
+## Exposure trajectory, generative loop, digital twin
+
+A repertoire cohort often has a **known covariate** (HLA, batch, vaccine arm) but an **unknown or
+noisy progression axis** (days since exposure, response severity). `mir.track.fit_exposure_trajectory`
+recovers that latent trajectory `tau` while disentangling it from the covariate — a PhenoPath-style
+model (Campbell & Yau 2018, *Nat. Commun.*
+[10.1038/s41467-018-04696-6](https://doi.org/10.1038/s41467-018-04696-6), adapted from genes×cells to
+repertoire-channels×samples) over *any* per-sample channel matrix (a stacked `Φ`, a `ChannelBuilder`
+build, or a raw embedding block):
+
+```python
+from mir.explain import stack_embeddings
+from mir.track import fit_exposure_trajectory
+
+X, spec = stack_embeddings(embs)                 # channels: mean ‖ diversity ‖ second
+fit = fit_exposure_trajectory(X, hla_indicator, channel_names=spec.names)
+fit.tau                    # inferred exposure/progression pseudotime, one per sample
+fit.top_interactions(5)    # which channels respond to progression differently by covariate
+```
+
+Complementing that, `mir.generate.DescriptorDensity` fits a (optionally class-conditional) density
+over `RepertoireDescriptor` vectors — `sample` draws brand-new synthetic donor states, `evolve`
+perturbs one donor along a coordinate ("what if hotter") and propagates the coupled shift through
+every other coordinate via the fitted covariance's conditional mean. `mir.ml.diffusion` (`[ml]`
+extra) is the non-linear alternative — a compact conditional DDPM/DDIM generator with
+classifier-free guidance, sharing the same `sample(n, condition=…)` call shape so it drops in
+unchanged. `mir.twin.DonorTwin` glues a donor's descriptor + trajectory position + covariate into
+one object you perturb or resample through, instead of threading the three APIs together by hand:
+
+```python
+from mir.generate import fit_descriptor_density
+from mir.twin import make_twins
+
+density = fit_descriptor_density(descriptors, labels=tumor_type)
+twins = make_twins(descriptors, conditions=tumor_type, donor_ids=sample_ids)
+hotter = twins[0].perturb(density, coordinate="infiltration", delta=2.0)
+synthetic = twins[0].simulate(density, n=20)     # 20 new synthetic peers of donor 0
+```
+
+See `examples/trajectory_and_twin.py` for a runnable end-to-end demo.
+
 ## Reproduce the paper
 
 The self-contained theory notebooks run on bundled data:

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/README.md

@@ -173,7 +173,10 @@ Provenance and the regenerate command are in [`SOURCES.md`](SOURCES.md).
 | `mir.repertoire` | sample-level (repertoire) embedding — RFF kernel mean ‖ Hill diversity ‖ second moment; MMD / HLA-stratified distance; motif witness; `centroid_atypicality`, multi-locus `fit_repertoire_spaces` (Theory §T.7) |
 | `mir.explain` | named-channel fusion (`ChannelBuilder`) + scorer-agnostic ablation (`channel_report`/`channel_drivers`) — which part of Φ carries the signal (§T.7) |
 | `mir.cohort` | the **digital donor** — multi-chain `fit_donor_embeddings`/`DonorCohort` (+ `transform`/`save`/`load`) + `residualize` / `cluster_samples` / `incidence_biomarkers` (§T.7) |
-| `mir.ml` | neural codecs (forward/inverse/Pgen/unified) + learned repertoire `set_encoder` (Set-Transformer/DeepRC) — Part 2, experimental; `[ml]` extra |
+| `mir.track` | **exposure trajectory** — PhenoPath-style covariate-disentangled latent progression axis (`fit_exposure_trajectory`) over any channel matrix; repertoire-level exposure detection |
+| `mir.generate` | the **generative loop** (mechanical half) — `DescriptorDensity`: sample new synthetic donor states / `evolve` one along a coordinate, over `RepertoireDescriptor` |
+| `mir.twin` | the **digital twin** — `DonorTwin`/`make_twins`: perturb or resample one donor's state through a `mir.generate`/`mir.ml.diffusion` generator |
+| `mir.ml` | neural codecs (forward/inverse/Pgen/unified) + learned repertoire `set_encoder` (Set-Transformer/DeepRC) + conditional **diffusion generator** (`mir.ml.diffusion`, the generative loop's research half) — Part 2, experimental; `[ml]` extra |
 
 ## Background subtraction & clustering (`mir.density`)
 
@@ -251,6 +254,47 @@ TRA and class II) lives in the second moment / witness. A learned co-equal set e
 (T7) live in the companion [`2026-mirpy-analysis`](https://github.com/antigenomics) repo
 (`benchmarks/{BENCHMARKS,THEORY}.md`) alongside the benchmark scripts.
 
+## Exposure trajectory, generative loop, digital twin
+
+A repertoire cohort often has a **known covariate** (HLA, batch, vaccine arm) but an **unknown or
+noisy progression axis** (days since exposure, response severity). `mir.track.fit_exposure_trajectory`
+recovers that latent trajectory `tau` while disentangling it from the covariate — a PhenoPath-style
+model (Campbell & Yau 2018, *Nat. Commun.*
+[10.1038/s41467-018-04696-6](https://doi.org/10.1038/s41467-018-04696-6), adapted from genes×cells to
+repertoire-channels×samples) over *any* per-sample channel matrix (a stacked `Φ`, a `ChannelBuilder`
+build, or a raw embedding block):
+
+```python
+from mir.explain import stack_embeddings
+from mir.track import fit_exposure_trajectory
+
+X, spec = stack_embeddings(embs)                 # channels: mean ‖ diversity ‖ second
+fit = fit_exposure_trajectory(X, hla_indicator, channel_names=spec.names)
+fit.tau                    # inferred exposure/progression pseudotime, one per sample
+fit.top_interactions(5)    # which channels respond to progression differently by covariate
+```
+
+Complementing that, `mir.generate.DescriptorDensity` fits a (optionally class-conditional) density
+over `RepertoireDescriptor` vectors — `sample` draws brand-new synthetic donor states, `evolve`
+perturbs one donor along a coordinate ("what if hotter") and propagates the coupled shift through
+every other coordinate via the fitted covariance's conditional mean. `mir.ml.diffusion` (`[ml]`
+extra) is the non-linear alternative — a compact conditional DDPM/DDIM generator with
+classifier-free guidance, sharing the same `sample(n, condition=…)` call shape so it drops in
+unchanged. `mir.twin.DonorTwin` glues a donor's descriptor + trajectory position + covariate into
+one object you perturb or resample through, instead of threading the three APIs together by hand:
+
+```python
+from mir.generate import fit_descriptor_density
+from mir.twin import make_twins
+
+density = fit_descriptor_density(descriptors, labels=tumor_type)
+twins = make_twins(descriptors, conditions=tumor_type, donor_ids=sample_ids)
+hotter = twins[0].perturb(density, coordinate="infiltration", delta=2.0)
+synthetic = twins[0].simulate(density, n=20)     # 20 new synthetic peers of donor 0
+```
+
+See `examples/trajectory_and_twin.py` for a runnable end-to-end demo.
+
 ## Reproduce the paper
 
 The self-contained theory notebooks run on bundled data:

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/docs/api.rst

@@ -123,6 +123,41 @@ residualisation, sample clustering, and incidence biomarkers (Theory T7).
    :undoc-members:
    :show-inheritance:
 
+Exposure trajectory (``mir.track``)
+-----------------------------------
+
+A PhenoPath-style (Campbell & Yau 2018) covariate-disentangled latent trajectory over a per-sample
+channel matrix — repertoire-level exposure detection, complementing ``mir.density``'s clone-level
+TCRNET/ALICE enrichment.
+
+.. automodule:: mir.track
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Generative loop (``mir.generate``)
+----------------------------------
+
+A fitted (optionally class-conditional) density over ``RepertoireDescriptor`` vectors: sample new
+synthetic donor states, or evolve one along a coordinate via the fitted covariance's conditional
+mean — the mechanical half of the generative loop (ROADMAP Phase 2).
+
+.. automodule:: mir.generate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Digital twin (``mir.twin``)
+---------------------------
+
+One donor's perturbable, simulatable state — glues ``RepertoireDescriptor`` + an optional
+``mir.track`` trajectory position + a ``mir.generate``/``mir.ml.diffusion`` generator into one object.
+
+.. automodule:: mir.twin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Benchmark harness (``mir.bench``)
 ---------------------------------
 
@@ -239,6 +274,17 @@ Learned repertoire track (Set-Transformer / DeepRC attention pooling).
    :undoc-members:
    :show-inheritance:
 
+``mir.ml.diffusion``
+~~~~~~~~~~~~~~~~~~~~
+
+Conditional diffusion generator (DDPM/DDIM + classifier-free guidance) over a compact descriptor/code
+space — the research half of the generative loop, complementing ``mir.generate``'s linear Gaussian.
+
+.. automodule:: mir.ml.diffusion
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Utilities
 ---------
 

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/docs/examples.rst

@@ -1,7 +1,7 @@
 Examples
 ========
 
-mirpy ships three runnable `marimo <https://marimo.io>`_ notebooks under ``examples/``. They are
+mirpy ships four runnable `marimo <https://marimo.io>`_ notebooks under ``examples/``. They are
 self-contained (they run on the bundled prototypes / test assets — no downloads) and double as
 living documentation for the three tiers. Install the extra and open one:
 
@@ -28,6 +28,12 @@ living documentation for the three tiers. Install the extra and open one:
    * - ``examples/theory.py``
      - Reproduces the supplementary results S1–S3 on bundled data — the distance laws
        (Gamma / extreme-value), the D↔d correlation, and prototype-source robustness.
+   * - ``examples/trajectory_and_twin.py``
+     - Exposure trajectory, generative loop, digital twin: fit a PhenoPath-style covariate-
+       disentangled trajectory (``mir.track``) on a synthetic cohort with a known covariate and a
+       planted severity axis, fit a generative density over ``RepertoireDescriptor`` vectors
+       (``mir.generate``), perturb one donor ("what if hotter") and draw new synthetic donor states
+       via the digital-twin glue (``mir.twin``).
 
 The full benchmark suite (VDJdb Table S1, density, repertoire / TCGA cohorts) and its result docs
 live in the companion `2026-mirpy-analysis <https://github.com/antigenomics>`_ repository; this repo

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/src/mir/__init__.py

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

{mirpy_lib-3.6.0 → mirpy_lib-3.7.0}/src/mir/density.py

@@ -622,6 +622,69 @@ def enriched_mask(
     )
 
 
+def exposure_score(
+    res: EnrichmentResult, *, abundance: np.ndarray | None = None,
+    alpha: float = 0.05, min_fold: float = 1.0, min_neighbors: int = 2,
+) -> np.ndarray:
+    """Aggregate one repertoire's per-clonotype :class:`EnrichmentResult` into 3 exposure scalars.
+
+    :func:`neighbor_enrichment` answers "which clones are enriched" (a per-clonotype hit list, the
+    TCRNET/ALICE readout); this answers "how exposed does the whole repertoire look" — a sample-level
+    summary suitable as an explainable channel (:mod:`mir.explain`) alongside identity/diversity/
+    coverage, rather than a clonotype list. Exposure detection moves from clone-level (density.py's
+    core job) to repertoire-level (a scalar a cohort model can score) with no new statistics: it is a
+    read-off of the enrichment already computed.
+
+    Args:
+        res: One donor's enrichment result (``obs_emb`` = that donor's repertoire, ``bg_emb`` shared
+            across the cohort so results are comparable).
+        abundance: Optional clone sizes (``duplicate_count``), row-aligned to ``res`` — enables the
+            mass-weighted column. ``None`` falls back to unweighted (distinct-count) breadth.
+        alpha, min_fold, min_neighbors: Forwarded to :func:`enriched_mask`.
+
+    Returns:
+        ``[breadth, mass_fraction, mean_log2_fold]``:
+
+        * ``breadth`` — fraction of distinct clonotypes flagged enriched.
+        * ``mass_fraction`` — abundance-weighted fraction of repertoire mass flagged (equals
+          ``breadth`` when ``abundance`` is ``None``).
+        * ``mean_log2_fold`` — mean ``log2(fold)`` among flagged clones (``0.0`` if none flagged).
+    """
+    mask = enriched_mask(res, alpha=alpha, min_fold=min_fold, min_neighbors=min_neighbors)
+    breadth = float(mask.mean()) if mask.size else 0.0
+    if abundance is not None:
+        a = np.asarray(abundance, dtype=np.float64)
+        mass_fraction = float(a[mask].sum() / a.sum()) if a.sum() > 0 else 0.0
+    else:
+        mass_fraction = breadth
+    if mask.any():
+        mean_log2_fold = float(np.mean(np.log2(np.clip(res.fold[mask], 1e-12, None))))
+    else:
+        mean_log2_fold = 0.0
+    return np.array([breadth, mass_fraction, mean_log2_fold], dtype=np.float64)
+
+
+def exposure_channel(
+    results: list[EnrichmentResult], *, abundances: list[np.ndarray | None] | None = None, **kwargs,
+) -> np.ndarray:
+    """Stack :func:`exposure_score` across a cohort into one ready-to-fuse channel matrix.
+
+    Args:
+        results: One :class:`EnrichmentResult` per donor (same shared background embedding).
+        abundances: Optional per-donor clone-size arrays, row-aligned to ``results`` (``None`` per
+            donor falls back to unweighted breadth for that donor).
+        **kwargs: Forwarded to :func:`exposure_score` (``alpha``, ``min_fold``, ``min_neighbors``).
+
+    Returns:
+        ``(n_donors, 3)`` array — columns ``[breadth, mass_fraction, mean_log2_fold]`` — pass
+        directly to :meth:`mir.explain.ChannelBuilder.add` (e.g.
+        ``builder.add("exposure", exposure_channel(results))``) or return it from a
+        :func:`mir.cohort.fit_donor_embeddings` ``extra_channels`` closure.
+    """
+    abundances = abundances or [None] * len(results)
+    return np.stack([exposure_score(r, abundance=a, **kwargs) for r, a in zip(results, abundances)])
+
+
 def denoise_and_cluster(
     obs_emb: np.ndarray,
     res: EnrichmentResult,

mirpy_lib-3.7.0/src/mir/generate.py

@@ -0,0 +1,233 @@
+"""The generative loop: a fitted density over repertoire descriptors, sample from it, evolve one.
+
+Promotes the ad-hoc "in-silico evolution" pattern (a bare ``np.cov`` + a hardcoded conditional-mean
+slope over a hand-picked metric list, prototyped analysis-side over TCGA) into a real, reusable
+library object built on :class:`mir.repertoire.RepertoireDescriptor` — the mass-preserving,
+decodable, smooth coordinate system :mod:`mir.repertoire` already ships (``[infiltration, log n_eff,
+clonality] ‖ identity mean``). :class:`DescriptorDensity` is the (optionally class-conditional)
+Gaussian fit over that coordinate; :meth:`~DescriptorDensity.sample` draws brand-new synthetic donor
+states from it (a *digital twin* generator — see :mod:`mir.track` for the complementary trajectory
+axis), and :meth:`~DescriptorDensity.evolve` perturbs one coordinate of a real descriptor and
+propagates the coupled shift through every other coordinate via the fitted covariance's multivariate-
+normal conditional mean — the same move as "hotter ⇒ diversity ↑ / switch ↑ / T-vs-B ↓" but as a
+library primitive instead of a one-off script.
+
+This is the *mechanical* half of the generative loop (ROADMAP Phase 2): a linear-Gaussian density is
+what the shipped in-silico-evolution numbers were fit with, so it stays the default here. The
+*research* half — a genuinely non-linear, learned generative model over the full embedding (not just
+the compact descriptor) — is :mod:`mir.ml.diffusion`, which this module's ``sample``/``evolve`` API
+deliberately mirrors so the two are drop-in alternatives.
+
+What stays analysis-local (ROADMAP non-goals): fitting a survival/classification model on the
+perturbed metrics (e.g. "does hotter predict better survival") is the study's scorer, not this
+module's job — :mod:`mir.explain`'s ``channel_report``/the analysis's own CoxPH fit consume the
+*output* of :meth:`~DescriptorDensity.evolve`, this module never sees an outcome ``y``.
+
+Torch-free (numpy / sklearn).
+
+Typical usage::
+
+    from mir.repertoire import sample_descriptor
+    from mir.generate import fit_descriptor_density, evolve
+
+    descriptors = [sample_descriptor(space, s) for s in samples]
+    density = fit_descriptor_density(descriptors, labels=tumor_type)   # one Gaussian per label
+
+    synthetic = density.sample(50, condition="SKCM")                   # 50 new synthetic donor states
+    hotter = evolve(density, descriptors[0], coordinate="infiltration", delta=2.0, condition="SKCM")
+    hotter.metrics()                                                   # named metrics after the move
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from mir.repertoire import RepertoireDescriptor
+
+_COORD_INDEX = {"infiltration": 0, "log_neff": 1, "clonality": 2}
+
+
+def _shrunk_cov(X: np.ndarray) -> np.ndarray:
+    """Ledoit-Wolf shrinkage covariance — stable with modest cohort sizes vs. the raw sample covariance."""
+    from sklearn.covariance import LedoitWolf
+
+    if X.shape[0] < 2:
+        return np.eye(X.shape[1])
+    return LedoitWolf().fit(X).covariance_
+
+
+@dataclass
+class DescriptorDensity:
+    """A fitted (optionally class-conditional) Gaussian density over descriptor vectors.
+
+    Attributes:
+        mean: ``{label: (dim,) mean}`` — a single key ``None`` when unconditional.
+        cov: ``{label: (dim, dim) shrinkage covariance}``.
+        dim: Vector width (``len(RepertoireDescriptor.vector)``).
+    """
+
+    mean: dict = field(default_factory=dict)
+    cov: dict = field(default_factory=dict)
+    dim: int = 0
+
+    @classmethod
+    def fit(cls, X: np.ndarray, labels: list | None = None) -> "DescriptorDensity":
+        """Fit a Gaussian (or, with ``labels``, one Gaussian per label) over descriptor vectors.
+
+        Args:
+            X: ``(n_samples, dim)`` stacked descriptor vectors (e.g.
+                ``np.stack([d.vector for d in descriptors])``).
+            labels: Optional length-``n_samples`` group labels (tumor type, batch, condition, …) —
+                fits one mean/covariance per distinct label instead of a single pooled Gaussian.
+
+        Returns:
+            A fitted :class:`DescriptorDensity`.
+
+        Raises:
+            ValueError: If ``X`` has fewer than 2 rows.
+        """
+        X = np.asarray(X, dtype=np.float64)
+        if X.shape[0] < 2:
+            raise ValueError(f"need >= 2 samples to fit a density, got {X.shape[0]}")
+        groups = {None: np.arange(X.shape[0])} if labels is None else {
+            lab: np.where(np.asarray(labels) == lab)[0] for lab in sorted(set(labels), key=str)
+        }
+        mean, cov = {}, {}
+        for lab, idx in groups.items():
+            Xg = X[idx]
+            mean[lab] = Xg.mean(axis=0)
+            cov[lab] = _shrunk_cov(Xg) if Xg.shape[0] >= 2 else np.eye(X.shape[1])
+        return cls(mean=mean, cov=cov, dim=X.shape[1])
+
+    def _resolve(self, condition):
+        if condition in self.mean:
+            return self.mean[condition], self.cov[condition]
+        if condition is None and len(self.mean) == 1:
+            return next(iter(self.mean.values())), next(iter(self.cov.values()))
+        raise ValueError(f"condition {condition!r} not in fitted labels {sorted(self.mean, key=str)}")
+
+    def sample(self, n: int = 1, *, condition=None, seed: int = 0) -> np.ndarray:
+        """Draw ``n`` synthetic descriptor vectors from the fitted (conditional) Gaussian.
+
+        Args:
+            n: Number of synthetic vectors to draw.
+            condition: Label to condition on (must be one of the labels ``fit`` saw); ``None`` for an
+                unconditional density, or the sole label when only one was fit.
+            seed: RNG seed.
+
+        Returns:
+            ``(n, dim)`` array — decode with :func:`mir.repertoire.decode_metrics` per row.
+        """
+        mu, sigma = self._resolve(condition)
+        rng = np.random.default_rng(seed)
+        return rng.multivariate_normal(mu, sigma, size=n)
+
+    def evolve(self, vector: np.ndarray, *, coordinate: int | str, delta: float, condition=None) -> np.ndarray:
+        """Shift ``vector`` by ``delta`` along one coordinate, propagating the coupled response.
+
+        The multivariate-normal conditional mean: fixing coordinate ``d`` to move by ``delta``
+        shifts every other coordinate ``j`` by ``Sigma[j,d]/Sigma[d,d] * delta`` in expectation —
+        this is the "hotter -> diversity up / switch up / T-vs-B down" move, generalized from a
+        hand-picked metric list to the full descriptor (and, via :attr:`RepertoireDescriptor.mean`,
+        the identity block too).
+
+        Args:
+            vector: A ``(dim,)`` descriptor vector to perturb (e.g. one real donor's).
+            coordinate: Vector index, or one of ``"infiltration"`` / ``"log_neff"`` / ``"clonality"``
+                for the named scalar coordinates.
+            delta: Amount to shift ``coordinate`` by (in the descriptor's own units — e.g. log-mass).
+            condition: Which fitted Gaussian's covariance defines the coupling (see :meth:`sample`).
+
+        Returns:
+            The perturbed ``(dim,)`` vector — decode with :func:`mir.repertoire.decode_metrics`.
+        """
+        d = _COORD_INDEX.get(coordinate, coordinate) if isinstance(coordinate, str) else coordinate
+        _, sigma = self._resolve(condition)
+        slope = sigma[:, d] / sigma[d, d]
+        out = np.asarray(vector, dtype=np.float64) + delta * slope
+        out[d] = vector[d] + delta   # the perturbed coordinate itself moves by exactly delta
+        return out
+
+
+def fit_descriptor_density(descriptors: list[RepertoireDescriptor], labels: list | None = None) -> DescriptorDensity:
+    """Fit a :class:`DescriptorDensity` directly from :class:`~mir.repertoire.RepertoireDescriptor` objects.
+
+    Args:
+        descriptors: One :class:`~mir.repertoire.RepertoireDescriptor` per sample
+            (:func:`mir.repertoire.sample_descriptor`).
+        labels: Optional per-sample group labels — see :meth:`DescriptorDensity.fit`.
+
+    Returns:
+        A fitted :class:`DescriptorDensity`.
+    """
+    X = np.stack([d.vector for d in descriptors])
+    return DescriptorDensity.fit(X, labels=labels)
+
+
+def evolve(
+    density: DescriptorDensity, descriptor: RepertoireDescriptor, *,
+    coordinate: int | str, delta: float, condition=None,
+) -> RepertoireDescriptor:
+    """Perturb one :class:`~mir.repertoire.RepertoireDescriptor` and rebuild the result as one.
+
+    Thin wrapper around :meth:`DescriptorDensity.evolve` that unpacks/repacks
+    :class:`~mir.repertoire.RepertoireDescriptor` instead of a bare vector, so the result's
+    ``.metrics()`` reads off directly.
+
+    Args:
+        density: A fitted :class:`DescriptorDensity` (the coupling comes from its covariance).
+        descriptor: The descriptor to perturb.
+        coordinate, delta, condition: See :meth:`DescriptorDensity.evolve`.
+
+    Returns:
+        The perturbed :class:`~mir.repertoire.RepertoireDescriptor`.
+    """
+    v = density.evolve(descriptor.vector, coordinate=coordinate, delta=delta, condition=condition)
+    return RepertoireDescriptor(log_mass=float(v[0]), log_neff=float(v[1]), simpson=float(v[2]), mean=v[3:])
+
+
+def _demo() -> None:
+    """Self-check on synthetic descriptors: sampling matches the fit moments; evolve moves the target
+    coordinate by exactly delta and couples a correlated coordinate in the expected direction."""
+    rng = np.random.default_rng(0)
+    n, dim = 300, 6
+    # a correlated synthetic cohort: coordinate 0 ("infiltration") positively drives coordinate 1
+    base = rng.standard_normal((n, dim))
+    base[:, 1] = 0.8 * base[:, 0] + 0.2 * rng.standard_normal(n)   # coord 1 tracks coord 0
+    descriptors = [
+        RepertoireDescriptor(log_mass=float(r[0]), log_neff=float(r[1]), simpson=float(r[2]), mean=r[3:])
+        for r in base
+    ]
+    density = fit_descriptor_density(descriptors)
+
+    synth = density.sample(2000, seed=1)
+    assert synth.shape == (2000, dim)
+    assert np.allclose(synth.mean(axis=0), base.mean(axis=0), atol=0.15)
+
+    d0 = descriptors[0]
+    moved = evolve(density, d0, coordinate="infiltration", delta=2.0)
+    assert abs(moved.log_mass - (d0.log_mass + 2.0)) < 1e-9          # exact move on the target coord
+    assert moved.log_neff > d0.log_neff                                # positive coupling recovered
+
+    # class-conditional fit: two well-separated labels sample from their own moments
+    labels = ["hot"] * (n // 2) + ["cold"] * (n - n // 2)
+    base2 = base.copy()
+    base2[n // 2:, 0] -= 5.0
+    descriptors2 = [
+        RepertoireDescriptor(log_mass=float(r[0]), log_neff=float(r[1]), simpson=float(r[2]), mean=r[3:])
+        for r in base2
+    ]
+    cond_density = fit_descriptor_density(descriptors2, labels=labels)
+    hot_synth = cond_density.sample(500, condition="hot", seed=2)
+    cold_synth = cond_density.sample(500, condition="cold", seed=2)
+    assert hot_synth[:, 0].mean() - cold_synth[:, 0].mean() > 3.0
+
+    print(f"[ok] sample moments match (atol=0.15); evolve moved infiltration by exactly 2.0, "
+          f"coupled log_neff {d0.log_neff:.3f}->{moved.log_neff:.3f}; conditional sampling separates "
+          f"hot/cold by {hot_synth[:,0].mean()-cold_synth[:,0].mean():.2f}")
+
+
+if __name__ == "__main__":
+    _demo()