tcri 0.9.0__tar.gz

tcri-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 Memorial Sloan Kettering Cancer Center
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tcri-0.9.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: tcri
+Version: 0.9.0
+Summary: Information theoretic metrics for single cell RNA and TCR sequencing.
+Author-email: Nicholas Ceglia <nickceglia@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nceglia/tcri
+Project-URL: Repository, https://github.com/nceglia/tcri
+Project-URL: Issues, https://github.com/nceglia/tcri/issues
+Project-URL: Documentation, https://tcri.readthedocs.io
+Keywords: single-cell,TCR,scRNA-seq,immunology,information-theory,bayesian
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.1
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: scipy>=1.14.1
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: anndata>=0.11.3
+Requires-Dist: scanpy>=1.9.5
+Requires-Dist: torch>=2.4.1
+Requires-Dist: pyro-ppl>=1.9.1
+Requires-Dist: scvi-tools>=1.3.0
+Requires-Dist: umap-learn>=0.5.6
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: tqdm>=4.66.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: notebook
+Requires-Dist: jupytext>=1.16; extra == "notebook"
+Requires-Dist: nbclient>=0.10; extra == "notebook"
+Requires-Dist: nbformat>=5.10; extra == "notebook"
+Requires-Dist: ipykernel>=6; extra == "notebook"
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://tcri.readthedocs.io">
+    <img src="https://raw.githubusercontent.com/nceglia/tcri/main/docs/images/tcri_logo_hero.png" alt="TCRi" width="420">
+  </a>
+</p>
+
+<p align="center">
+  <b>Information-theoretic analysis of paired single-cell RNA + TCR sequencing.</b>
+</p>
+
+<p align="center">
+  <a href="https://tcri.readthedocs.io">Documentation</a> ·
+  <a href="https://tcri.readthedocs.io/en/latest/tutorials/index.html">Tutorials</a> ·
+  <a href="https://www.biorxiv.org/content/10.1101/2022.10.01.510457v1">Paper</a> ·
+  <a href="https://github.com/nceglia/tcri/issues">Issues</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/nceglia/tcri/actions/workflows/tests.yml"><img src="https://github.com/nceglia/tcri/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <a href="https://tcri.readthedocs.io"><img src="https://readthedocs.org/projects/tcri/badge/?version=latest" alt="docs"></a>
+  <a href="https://github.com/nceglia/tcri/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="python 3.10+">
+  <img src="https://img.shields.io/badge/built%20on-scverse-%231f9e16.svg" alt="built on scverse">
+</p>
+
+---
+
+TCRi quantifies how **T-cell clonotypes** relate to **transcriptional phenotypes** in
+paired single-cell data. It fits a hierarchical Bayesian model (on top of
+[scvi-tools](https://scvi-tools.org) / [Pyro](https://pyro.ai)) that ties each clone's
+phenotype distribution to gene expression, then reads out **information-theoretic
+summaries** — clonotypic and phenotypic entropy, clone↔phenotype mutual information, and
+phenotypic flux across conditions — over the learned clone × phenotype joint distribution.
+
+It is built on the [scverse](https://scverse.org) stack
+([AnnData](https://anndata.readthedocs.io), [scanpy](https://scanpy.readthedocs.io),
+scvi-tools) and works on a standard `AnnData` carrying both a clonotype label and a
+gene-expression matrix.
+
+## Key capabilities
+
+- **Joint model of expression + repertoire** — a hierarchical VAE (`TCRIModel`) that
+  learns each clone's phenotype distribution while reconstructing counts with a ZINB
+  decoder.
+- **Information-theoretic metrics** — clonotypic entropy `H(c|φ)`, phenotypic entropy
+  `H(φ|c)`, normalized mutual information `I(c;φ)`, and phenotypic flux between conditions,
+  all in bits over the posterior joint.
+- **Uncertainty-aware** — every metric can be reported as a posterior mean ± HDI by
+  drawing from the fitted Dirichlet posterior (`n_samples > 0`).
+- **Group comparisons** — paired/unpaired contrasts across cohorts (e.g. responders vs
+  non-responders) with direction probabilities.
+- **Diagnostics** — posterior-predictive checks, phenotype calibration, and permutation
+  nulls for the metrics.
+- **Contract-governed** — the public API, the generative model, the metric definitions,
+  and the training plan are each frozen by a machine-checked contract.
+
+## Installation
+
+TCRi targets **Python ≥ 3.10**. Install from source:
+
+```bash
+git clone https://github.com/nceglia/tcri.git
+cd tcri
+pip install .
+```
+
+The heavy scientific stack (PyTorch, Pyro, scvi-tools, scanpy) is pulled in
+automatically. A GPU is optional but speeds up model fitting. See the
+[installation guide](https://tcri.readthedocs.io/en/latest/usage/installation.html) for
+details.
+
+## Quickstart
+
+```python
+import tcri
+
+# 1. register clonotype / phenotype / covariate / batch columns on your AnnData
+tcri.ml.TCRIModel.setup_anndata(
+    adata,
+    layer="counts",
+    clonotype_key="clone_id",
+    phenotype_key="phenotype",
+    covariate_key="timepoint",
+    batch_key="patient",
+)
+
+# 2. fit the model and write learned quantities back onto the AnnData
+model = tcri.ml.TCRIModel(adata)
+model.train(max_epochs=200, batch_size=512)
+model.to_anndata(adata)
+
+# 3. read out information-theoretic metrics (bits)
+mi = tcri.tl.mutual_information(adata, covariate="pre", normalize_mode="average")
+ce = tcri.tl.clonotypic_entropy(adata, covariate="pre")
+flux = tcri.tl.phenotypic_flux(adata, cov_from="pre", cov_to="post")
+```
+
+No paired data yet? `tcri.datasets.simulate_tcri()` returns a synthetic AnnData whose
+true mutual information is known in closed form — the basis for the
+[tutorials](https://tcri.readthedocs.io/en/latest/tutorials/index.html).
+
+## Framework
+
+TCRi models the joint distribution of clonotype and phenotype hierarchically: a
+clonotype-level prior `p_c` over phenotypes, a covariate-specific `p_ct` anchored to it,
+and a per-cell phenotype that fuses a classifier on the latent embedding `z` with the
+clone's local prior. The metrics are then pure functions of the learned clone × phenotype
+joint. The full generative model and its plate diagram are documented under
+[Concepts](https://tcri.readthedocs.io/en/latest/concepts/index.html).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nceglia/tcri/main/docs/images/framework.png" alt="TCRi framework" width="760">
+</p>
+
+## Governance
+
+The public interface, the generative mathematics, the metric definitions and the training
+plan are each frozen by a machine-checked contract. A published number only means something
+if the definition behind it is stable, so a metric cannot be silently redefined and the model
+the package claims to implement is the model it does implement.
+
+A failing conformance test means *stop and decide* — never loosen a contract to make it pass.
+See [Governance](https://tcri.readthedocs.io/en/latest/contracts/index.html) for what each
+contract covers, and `governance/` in the repository for the contracts themselves.
+
+## Related tools
+
+| Tool | Relationship |
+|------|-------------|
+| [scirpy](https://scirpy.readthedocs.io) | AIRR/TCR repertoire handling and analysis |
+| [scvi-tools](https://scvi-tools.org) | probabilistic modelling backbone TCRi builds on |
+| [scanpy](https://scanpy.readthedocs.io) / [AnnData](https://anndata.readthedocs.io) | single-cell data structures and workflows |
+
+## Citation
+
+If you use TCRi in your research, please cite:
+
+> **TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing**
+>
+> Nicholas Ceglia, Sohrab Salehi, et al.
+>
+> _bioRxiv_ 2022. doi: [10.1101/2022.10.01.510457](https://doi.org/10.1101/2022.10.01.510457)
+
+<details>
+<summary>BibTeX</summary>
+
+```bibtex
+@article{ceglia2022tcri,
+  title   = {TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing},
+  author  = {Ceglia, Nicholas and Salehi, Sohrab and others},
+  journal = {bioRxiv},
+  year    = {2022},
+  doi     = {10.1101/2022.10.01.510457}
+}
+```
+
+</details>
+
+## License
+
+TCRi is released under the [MIT License](LICENSE).

tcri-0.9.0/README.md

@@ -0,0 +1,161 @@
+<p align="center">
+  <a href="https://tcri.readthedocs.io">
+    <img src="https://raw.githubusercontent.com/nceglia/tcri/main/docs/images/tcri_logo_hero.png" alt="TCRi" width="420">
+  </a>
+</p>
+
+<p align="center">
+  <b>Information-theoretic analysis of paired single-cell RNA + TCR sequencing.</b>
+</p>
+
+<p align="center">
+  <a href="https://tcri.readthedocs.io">Documentation</a> ·
+  <a href="https://tcri.readthedocs.io/en/latest/tutorials/index.html">Tutorials</a> ·
+  <a href="https://www.biorxiv.org/content/10.1101/2022.10.01.510457v1">Paper</a> ·
+  <a href="https://github.com/nceglia/tcri/issues">Issues</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/nceglia/tcri/actions/workflows/tests.yml"><img src="https://github.com/nceglia/tcri/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <a href="https://tcri.readthedocs.io"><img src="https://readthedocs.org/projects/tcri/badge/?version=latest" alt="docs"></a>
+  <a href="https://github.com/nceglia/tcri/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="python 3.10+">
+  <img src="https://img.shields.io/badge/built%20on-scverse-%231f9e16.svg" alt="built on scverse">
+</p>
+
+---
+
+TCRi quantifies how **T-cell clonotypes** relate to **transcriptional phenotypes** in
+paired single-cell data. It fits a hierarchical Bayesian model (on top of
+[scvi-tools](https://scvi-tools.org) / [Pyro](https://pyro.ai)) that ties each clone's
+phenotype distribution to gene expression, then reads out **information-theoretic
+summaries** — clonotypic and phenotypic entropy, clone↔phenotype mutual information, and
+phenotypic flux across conditions — over the learned clone × phenotype joint distribution.
+
+It is built on the [scverse](https://scverse.org) stack
+([AnnData](https://anndata.readthedocs.io), [scanpy](https://scanpy.readthedocs.io),
+scvi-tools) and works on a standard `AnnData` carrying both a clonotype label and a
+gene-expression matrix.
+
+## Key capabilities
+
+- **Joint model of expression + repertoire** — a hierarchical VAE (`TCRIModel`) that
+  learns each clone's phenotype distribution while reconstructing counts with a ZINB
+  decoder.
+- **Information-theoretic metrics** — clonotypic entropy `H(c|φ)`, phenotypic entropy
+  `H(φ|c)`, normalized mutual information `I(c;φ)`, and phenotypic flux between conditions,
+  all in bits over the posterior joint.
+- **Uncertainty-aware** — every metric can be reported as a posterior mean ± HDI by
+  drawing from the fitted Dirichlet posterior (`n_samples > 0`).
+- **Group comparisons** — paired/unpaired contrasts across cohorts (e.g. responders vs
+  non-responders) with direction probabilities.
+- **Diagnostics** — posterior-predictive checks, phenotype calibration, and permutation
+  nulls for the metrics.
+- **Contract-governed** — the public API, the generative model, the metric definitions,
+  and the training plan are each frozen by a machine-checked contract.
+
+## Installation
+
+TCRi targets **Python ≥ 3.10**. Install from source:
+
+```bash
+git clone https://github.com/nceglia/tcri.git
+cd tcri
+pip install .
+```
+
+The heavy scientific stack (PyTorch, Pyro, scvi-tools, scanpy) is pulled in
+automatically. A GPU is optional but speeds up model fitting. See the
+[installation guide](https://tcri.readthedocs.io/en/latest/usage/installation.html) for
+details.
+
+## Quickstart
+
+```python
+import tcri
+
+# 1. register clonotype / phenotype / covariate / batch columns on your AnnData
+tcri.ml.TCRIModel.setup_anndata(
+    adata,
+    layer="counts",
+    clonotype_key="clone_id",
+    phenotype_key="phenotype",
+    covariate_key="timepoint",
+    batch_key="patient",
+)
+
+# 2. fit the model and write learned quantities back onto the AnnData
+model = tcri.ml.TCRIModel(adata)
+model.train(max_epochs=200, batch_size=512)
+model.to_anndata(adata)
+
+# 3. read out information-theoretic metrics (bits)
+mi = tcri.tl.mutual_information(adata, covariate="pre", normalize_mode="average")
+ce = tcri.tl.clonotypic_entropy(adata, covariate="pre")
+flux = tcri.tl.phenotypic_flux(adata, cov_from="pre", cov_to="post")
+```
+
+No paired data yet? `tcri.datasets.simulate_tcri()` returns a synthetic AnnData whose
+true mutual information is known in closed form — the basis for the
+[tutorials](https://tcri.readthedocs.io/en/latest/tutorials/index.html).
+
+## Framework
+
+TCRi models the joint distribution of clonotype and phenotype hierarchically: a
+clonotype-level prior `p_c` over phenotypes, a covariate-specific `p_ct` anchored to it,
+and a per-cell phenotype that fuses a classifier on the latent embedding `z` with the
+clone's local prior. The metrics are then pure functions of the learned clone × phenotype
+joint. The full generative model and its plate diagram are documented under
+[Concepts](https://tcri.readthedocs.io/en/latest/concepts/index.html).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nceglia/tcri/main/docs/images/framework.png" alt="TCRi framework" width="760">
+</p>
+
+## Governance
+
+The public interface, the generative mathematics, the metric definitions and the training
+plan are each frozen by a machine-checked contract. A published number only means something
+if the definition behind it is stable, so a metric cannot be silently redefined and the model
+the package claims to implement is the model it does implement.
+
+A failing conformance test means *stop and decide* — never loosen a contract to make it pass.
+See [Governance](https://tcri.readthedocs.io/en/latest/contracts/index.html) for what each
+contract covers, and `governance/` in the repository for the contracts themselves.
+
+## Related tools
+
+| Tool | Relationship |
+|------|-------------|
+| [scirpy](https://scirpy.readthedocs.io) | AIRR/TCR repertoire handling and analysis |
+| [scvi-tools](https://scvi-tools.org) | probabilistic modelling backbone TCRi builds on |
+| [scanpy](https://scanpy.readthedocs.io) / [AnnData](https://anndata.readthedocs.io) | single-cell data structures and workflows |
+
+## Citation
+
+If you use TCRi in your research, please cite:
+
+> **TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing**
+>
+> Nicholas Ceglia, Sohrab Salehi, et al.
+>
+> _bioRxiv_ 2022. doi: [10.1101/2022.10.01.510457](https://doi.org/10.1101/2022.10.01.510457)
+
+<details>
+<summary>BibTeX</summary>
+
+```bibtex
+@article{ceglia2022tcri,
+  title   = {TCRi: An Information Theoretic Framework for Paired Single Cell Gene Expression and TCR Sequencing},
+  author  = {Ceglia, Nicholas and Salehi, Sohrab and others},
+  journal = {bioRxiv},
+  year    = {2022},
+  doi     = {10.1101/2022.10.01.510457}
+}
+```
+
+</details>
+
+## License
+
+TCRi is released under the [MIT License](LICENSE).

tcri-0.9.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tcri"
+version = "0.9.0"
+description = "Information theoretic metrics for single cell RNA and TCR sequencing."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Nicholas Ceglia", email = "nickceglia@gmail.com" },
+]
+keywords = [
+    "single-cell",
+    "TCR",
+    "scRNA-seq",
+    "immunology",
+    "information-theory",
+    "bayesian",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "numpy>=1.26.1",
+    "pandas>=2.2.2",
+    "scipy>=1.14.1",
+    "scikit-learn>=1.1",
+    "anndata>=0.11.3",
+    "scanpy>=1.9.5",
+    "torch>=2.4.1",
+    "pyro-ppl>=1.9.1",
+    "scvi-tools>=1.3.0",
+    "umap-learn>=0.5.6",
+    "matplotlib>=3.9.2",
+    "seaborn>=0.13.2",
+    "tqdm>=4.66.5",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7",
+    "pytest-cov",
+]
+# Building examples/example.ipynb with its outputs embedded. Not needed to use tcri.
+notebook = [
+    "jupytext>=1.16",
+    "nbclient>=0.10",
+    "nbformat>=5.10",
+    "ipykernel>=6",
+]
+
+[project.urls]
+Homepage = "https://github.com/nceglia/tcri"
+Repository = "https://github.com/nceglia/tcri"
+Issues = "https://github.com/nceglia/tcri/issues"
+Documentation = "https://tcri.readthedocs.io"
+
+[tool.setuptools.packages.find]
+include = ["tcri*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

tcri-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tcri-0.9.0/tcri/__init__.py

@@ -0,0 +1,33 @@
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("tcri")
+except _PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+from . import tools as tl          # PR6: tl repointed metrics -> tools (engine-backed metrics)
+from . import preprocessing as pp
+from . import plotting as pl
+from . import utils as ut
+from . import model as ml
+from . import diagnostics as diag  # PR8
+from . import datasets        # synthetic cohorts, incl. one with a known-MI oracle
+from . import get             # accessors for cached tl results
+
+# The unified engine, re-exported top-level for prominence.
+from .tools import joint_distribution
+
+import sys as _sys
+
+_sys.modules.update({f'{__name__}.{m}': globals()[m] for m in ['tl', 'pp', 'pl', 'ut', 'ml', 'diag']})
+
+#: The top-level surface. Without this, ``dir(tcri)`` also advertised ``sys`` and
+#: ``PackageNotFoundError`` -- module-machinery names that leaked purely because they were
+#: imported at module scope, and which a user could reasonably have mistaken for API. The
+#: private aliases (``_sys``, ``_PackageNotFoundError``) keep them out of ``dir`` regardless;
+#: this makes the intended surface explicit rather than incidental.
+__all__ = [
+    "tl", "pp", "pl", "ut", "ml", "diag", "datasets", "get",
+    "tools", "preprocessing", "plotting", "utils", "model", "diagnostics",
+    "joint_distribution", "__version__",
+]

tcri-0.9.0/tcri/_compute/__init__.py

@@ -0,0 +1,15 @@
+"""Private numeric + device seam for the engine (grafiti ``_compute`` parity).
+
+- :mod:`._xp`       — device dispatch (torch-first; CPU / torch-CUDA), ``asnumpy`` boundary.
+- :mod:`._joint`    — ``_joint_draws``: the batched ``[S, n_clones, P]`` engine core.
+- :mod:`._distance` — kl / l1 / jsd kernels over phenotype distributions (was ``tcri/_distance.py``).
+- :mod:`._tables`   — the metric-table plumbing every ``tools`` metric reduces through
+  (``metric_table``, ``build_result``, ``build_stats``, ``collapse_to_replicates``); was
+  ``tcri/tools/_common.py``, which put shared machinery inside one of its own consumers.
+
+This is the LOWER layer: ``tools``/``plotting``/``diagnostics`` import down into it and it must
+not import back up. ``_tables`` needs one symbol from ``tools._joint`` and takes it lazily inside
+the function, never at module scope.
+
+Nothing here is public API; GPU libs are imported lazily inside functions.
+"""

tcri-0.9.0/tcri/_compute/_distance.py

@@ -0,0 +1,60 @@
+"""Distance / divergence kernels for phenotype distributions.
+
+Single home for the KL kernel (was `metrics.dkl` + `flux.dkl_func`, two copies)
+plus L1 and a symmetric Jensen–Shannon option. All operate on 1-D probability
+vectors, use log base 2 (bits), and share one eps floor. ``phenotype_distance``
+is the string→callable dispatcher used by ``phenotypic_flux(distance_metric=)``.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+EPS = 1e-12
+
+
+def _normalize(p):
+    p = np.clip(np.asarray(p, float), EPS, None)
+    return p / p.sum()
+
+
+def kl_divergence(p, q, *, base: float = 2.0, eps: float = EPS) -> float:
+    """KL(p ‖ q) in bits (base 2). Asymmetric."""
+    p = np.clip(np.asarray(p, float), eps, None); p = p / p.sum()
+    q = np.clip(np.asarray(q, float), eps, None); q = q / q.sum()
+    return float(np.sum(p * (np.log(p / q) / np.log(base))))
+
+
+def l1_distance(p, q) -> float:
+    """L1 (Manhattan) distance between two normalized distributions, in [0, 2]."""
+    return float(np.abs(_normalize(p) - _normalize(q)).sum())
+
+
+def jensen_shannon(p, q, *, base: float = 2.0, eps: float = EPS) -> float:
+    """Jensen–Shannon divergence: symmetric, bounded [0, 1] bit — the recommended
+    symmetric shift measure."""
+    p = _normalize(p)
+    q = _normalize(q)
+    m = 0.5 * (p + q)
+    return float(0.5 * kl_divergence(p, m, base=base, eps=eps)
+                 + 0.5 * kl_divergence(q, m, base=base, eps=eps))
+
+
+_REGISTRY = {
+    "l1": l1_distance,
+    "kl": kl_divergence,
+    "dkl": kl_divergence,
+    "js": jensen_shannon,
+    "jsd": jensen_shannon,
+}
+
+
+def phenotype_distance(metric):
+    """Resolve ``distance_metric`` (a name or a callable ``f(p, q) -> float``)."""
+    if callable(metric):
+        return metric
+    key = str(metric).lower()
+    if key not in _REGISTRY:
+        raise ValueError(
+            f"distance_metric must be a callable or one of {sorted(_REGISTRY)}; got {metric!r}"
+        )
+    return _REGISTRY[key]