rafinat 0.2.0__tar.gz

rafinat-0.2.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: rafinat
+Version: 0.2.0
+Summary: Bayesian normalizations for RNA-seq
+Author-email: Georgy Meshcheryakov <iam@georgy.top>
+License: BSD-2-Clause
+Keywords: single-cell,scRNA-seq,RNA-seq,normalization,bioinformatics,Dirichlet-multinomial,compositional data,CLR,Fisher-Rao,scikit-learn
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+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
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: rafinat
+Requires-Dist: liudist>=0.1; extra == "rafinat"
+Provides-Extra: gpu
+Requires-Dist: liudist>=0.1; extra == "gpu"
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn; extra == "sklearn"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: scikit-learn; extra == "test"
+
+# rafinat
+
+Dirichlet-Multinomial posterior normalizations for single-cell RNA-seq count data.
+
+Three count normalizations derived from a Dirichlet-Multinomial (Liouville) posterior view of the
+latent expression rates. 
+
+Each is a scikit-learn-style transformer: you instantiate it with its operating point, then
+`.fit` / `.transform` / `.fit_transform` a count matrix — so it drops into a preprocessing pipeline.
+
+| transformer | what it is | default operating point |
+|----------|-----------|--------------------------|
+| `compost`  | the DM-posterior generalisation of CLR | `p=0` digamma log-corner, top-2/3-trimmed per-cell centering |
+| `hellnorm` | the Hellinger / Fisher-Rao spherical (sqrt-CLR) normalization | top-2/3-trimmed per-cell sqrt reference |
+| `rafinat`  | the complete Fisher-Rao Liouville embedding | composition arc length (sharp `r_snr`) + radial cell-size coordinate, `beta="total"` |
+
+All take a dense `(genes, cells)` array of raw counts (genes = features/rows, cells =
+samples/columns) and return `(genes, cells)` (`rafinat` returns `(genes + 1, cells)` — the extra
+row is the cell-size scale coordinate). `compost` and `hellnorm` are pure `numpy`/`scipy` (CPU).
+`rafinat` uses the optional [`liudist`](liudist/) package (Fisher-Rao geometry of Liouville laws;
+pulls in JAX, and benefits from a GPU JAX build) — installed via the `[rafinat]` extra.
+
+```python
+import numpy as np, rafinat
+X = np.random.poisson(0.5, size=(2000, 500)).astype(float)   # genes x cells
+
+Z = rafinat.compost().fit_transform(X)      # CLR-dominating default (compost p=0, trimmed)
+H = rafinat.hellnorm().fit_transform(X)     # Hellnorm, trimmed reference
+R = rafinat.rafinat().fit_transform(X)      # rafinat (complete); (genes + 1) x cells
+```
+
+### fit / transform
+
+`fit` estimates and **freezes** the two data-driven pieces — the concentration `r` and the per-cell
+reference level `beta` — and `transform` re-applies that frozen normalization. Because `beta` is
+per-cell, `transform` expects a matrix of the same `(genes, cells)` shape it was fitted on (re-fit
+for a different gene/cell set). `fit_transform(X)` is the one-shot form.
+
+```python
+tr = rafinat.compost(p=0.5).fit(X)     # estimate & freeze tr.r_ and tr.beta_
+Z  = tr.transform(X)                    # apply; == tr.fit_transform(X)
+
+from sklearn.pipeline import Pipeline   # optional — also works without scikit-learn installed
+pipe = Pipeline([("normalize", rafinat.compost())])
+Z = pipe.fit_transform(X)
+```
+
+scikit-learn is an **optional** extra: if installed, the transformers inherit
+`BaseEstimator` / `TransformerMixin` (full `Pipeline` / `clone` / `get_params` support); otherwise a
+light built-in shim provides the same `fit` / `transform` / `fit_transform` / `get_params` API.
+
+## Choosing the operating point
+
+The benchmark-winning defaults are baked in, but every knob is a constructor argument:
+
+```python
+rafinat.compost(p=0.0)               # default: digamma log-corner, trimmed centering
+rafinat.compost(p=0.5)               # posterior sqrt mean (order-1/2 power-mean cell size)
+rafinat.compost(trim=0.0)            # ordinary (non-trimmed) per-cell centering
+rafinat.compost(r="mle")             # pooled DM-MLE concentration instead of the CLR-matched r
+rafinat.compost(zscore=True)         # + per-gene z-score (the optional '->Z' standardization)
+
+rafinat.hellnorm(reference="uniform")     # classic log-map references: uniform / extrinsic / frechet
+rafinat.hellnorm(trim=0.5)                # lighter top-trim
+
+rafinat.rafinat(beta="atop10")       # simulation-leaning cell-size estimator
+rafinat.rafinat(r_comp="mle")        # smoother directional concentration
+rafinat.rafinat(zcomp=True)          # + per-gene z-score of the composition rows ('-> coordZ')
+```
+
+Each of these returns a transformer; call `.fit_transform(X)` (or `.fit(X)` then `.transform(X)`)
+on it. After fitting, the estimated values are exposed as fitted attributes (trailing underscore):
+`compost.r_` / `compost.beta_`, `rafinat.r_comp_` / `rafinat.ref_` / `rafinat.C_` /
+`rafinat.beta_`.
+
+**The optional per-gene standardization (`compost(zscore=True)`, `rafinat(zcomp=True)`) is disabled
+by default**, matching the benchmark's shipped defaults.
+
+## Install
+
+```bash
+pip install rafinat                # compost / hellnorm (numpy + scipy only)
+pip install "rafinat[rafinat]"     # + the rafinat() method — adds the liudist backend (pulls in JAX)
+```
+
+`compost` and `hellnorm` need only `numpy`/`scipy`; the heavy `liudist` + JAX stack is pulled in
+**only** by the `[rafinat]` extra, i.e. only if you use the `rafinat()` method. 
+
+
+
+## Method provenance
+
+- **compost** — `digamma(r + x)` with `r = 1/(4·alpha) + 1/2` (so `digamma(r+x) ≈ log(x + 1/(4·alpha))`), minus a per-cell location estimated on the **low-expression bulk**
+  (the top high-expression genes — the biologically variable ones — are dropped from the cell-size
+  estimate). 
+- **hellnorm** — `sqrt(x / sum x)` minus a top-trimmed per-cell mean (the sqrt-geometry analog of
+  compost's trimmed centering). Dominates the classic uniform/extrinsic/Frechet references.
+- **rafinat** — the Fisher-Rao Liouville distance factors as
+  `d² = d_composition² + C·(d ln β)²`; rafinat realises it as the stack
+  `[ composition arc length (depth-normalized, sharp r_snr) ; sqrt(C)·ln(β_c) ]`, with the radial
+  weight `C = genes · r_mle` decoupled from the (sharp) directional concentration so the cell-size
+  axis stays alive at a parameter-free weight.

rafinat-0.2.0/README.md

@@ -0,0 +1,102 @@
+# rafinat
+
+Dirichlet-Multinomial posterior normalizations for single-cell RNA-seq count data.
+
+Three count normalizations derived from a Dirichlet-Multinomial (Liouville) posterior view of the
+latent expression rates. 
+
+Each is a scikit-learn-style transformer: you instantiate it with its operating point, then
+`.fit` / `.transform` / `.fit_transform` a count matrix — so it drops into a preprocessing pipeline.
+
+| transformer | what it is | default operating point |
+|----------|-----------|--------------------------|
+| `compost`  | the DM-posterior generalisation of CLR | `p=0` digamma log-corner, top-2/3-trimmed per-cell centering |
+| `hellnorm` | the Hellinger / Fisher-Rao spherical (sqrt-CLR) normalization | top-2/3-trimmed per-cell sqrt reference |
+| `rafinat`  | the complete Fisher-Rao Liouville embedding | composition arc length (sharp `r_snr`) + radial cell-size coordinate, `beta="total"` |
+
+All take a dense `(genes, cells)` array of raw counts (genes = features/rows, cells =
+samples/columns) and return `(genes, cells)` (`rafinat` returns `(genes + 1, cells)` — the extra
+row is the cell-size scale coordinate). `compost` and `hellnorm` are pure `numpy`/`scipy` (CPU).
+`rafinat` uses the optional [`liudist`](liudist/) package (Fisher-Rao geometry of Liouville laws;
+pulls in JAX, and benefits from a GPU JAX build) — installed via the `[rafinat]` extra.
+
+```python
+import numpy as np, rafinat
+X = np.random.poisson(0.5, size=(2000, 500)).astype(float)   # genes x cells
+
+Z = rafinat.compost().fit_transform(X)      # CLR-dominating default (compost p=0, trimmed)
+H = rafinat.hellnorm().fit_transform(X)     # Hellnorm, trimmed reference
+R = rafinat.rafinat().fit_transform(X)      # rafinat (complete); (genes + 1) x cells
+```
+
+### fit / transform
+
+`fit` estimates and **freezes** the two data-driven pieces — the concentration `r` and the per-cell
+reference level `beta` — and `transform` re-applies that frozen normalization. Because `beta` is
+per-cell, `transform` expects a matrix of the same `(genes, cells)` shape it was fitted on (re-fit
+for a different gene/cell set). `fit_transform(X)` is the one-shot form.
+
+```python
+tr = rafinat.compost(p=0.5).fit(X)     # estimate & freeze tr.r_ and tr.beta_
+Z  = tr.transform(X)                    # apply; == tr.fit_transform(X)
+
+from sklearn.pipeline import Pipeline   # optional — also works without scikit-learn installed
+pipe = Pipeline([("normalize", rafinat.compost())])
+Z = pipe.fit_transform(X)
+```
+
+scikit-learn is an **optional** extra: if installed, the transformers inherit
+`BaseEstimator` / `TransformerMixin` (full `Pipeline` / `clone` / `get_params` support); otherwise a
+light built-in shim provides the same `fit` / `transform` / `fit_transform` / `get_params` API.
+
+## Choosing the operating point
+
+The benchmark-winning defaults are baked in, but every knob is a constructor argument:
+
+```python
+rafinat.compost(p=0.0)               # default: digamma log-corner, trimmed centering
+rafinat.compost(p=0.5)               # posterior sqrt mean (order-1/2 power-mean cell size)
+rafinat.compost(trim=0.0)            # ordinary (non-trimmed) per-cell centering
+rafinat.compost(r="mle")             # pooled DM-MLE concentration instead of the CLR-matched r
+rafinat.compost(zscore=True)         # + per-gene z-score (the optional '->Z' standardization)
+
+rafinat.hellnorm(reference="uniform")     # classic log-map references: uniform / extrinsic / frechet
+rafinat.hellnorm(trim=0.5)                # lighter top-trim
+
+rafinat.rafinat(beta="atop10")       # simulation-leaning cell-size estimator
+rafinat.rafinat(r_comp="mle")        # smoother directional concentration
+rafinat.rafinat(zcomp=True)          # + per-gene z-score of the composition rows ('-> coordZ')
+```
+
+Each of these returns a transformer; call `.fit_transform(X)` (or `.fit(X)` then `.transform(X)`)
+on it. After fitting, the estimated values are exposed as fitted attributes (trailing underscore):
+`compost.r_` / `compost.beta_`, `rafinat.r_comp_` / `rafinat.ref_` / `rafinat.C_` /
+`rafinat.beta_`.
+
+**The optional per-gene standardization (`compost(zscore=True)`, `rafinat(zcomp=True)`) is disabled
+by default**, matching the benchmark's shipped defaults.
+
+## Install
+
+```bash
+pip install rafinat                # compost / hellnorm (numpy + scipy only)
+pip install "rafinat[rafinat]"     # + the rafinat() method — adds the liudist backend (pulls in JAX)
+```
+
+`compost` and `hellnorm` need only `numpy`/`scipy`; the heavy `liudist` + JAX stack is pulled in
+**only** by the `[rafinat]` extra, i.e. only if you use the `rafinat()` method. 
+
+
+
+## Method provenance
+
+- **compost** — `digamma(r + x)` with `r = 1/(4·alpha) + 1/2` (so `digamma(r+x) ≈ log(x + 1/(4·alpha))`), minus a per-cell location estimated on the **low-expression bulk**
+  (the top high-expression genes — the biologically variable ones — are dropped from the cell-size
+  estimate). 
+- **hellnorm** — `sqrt(x / sum x)` minus a top-trimmed per-cell mean (the sqrt-geometry analog of
+  compost's trimmed centering). Dominates the classic uniform/extrinsic/Frechet references.
+- **rafinat** — the Fisher-Rao Liouville distance factors as
+  `d² = d_composition² + C·(d ln β)²`; rafinat realises it as the stack
+  `[ composition arc length (depth-normalized, sharp r_snr) ; sqrt(C)·ln(β_c) ]`, with the radial
+  weight `C = genes · r_mle` decoupled from the (sharp) directional concentration so the cell-size
+  axis stays alive at a parameter-free weight.

rafinat-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rafinat"
+version = "0.2.0"
+description = "Bayesian normalizations for RNA-seq"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-2-Clause" }
+authors = [{ name = "Georgy Meshcheryakov", email = "iam@georgy.top" }]
+keywords = [
+    "single-cell", "scRNA-seq", "RNA-seq", "normalization", "bioinformatics",
+    "Dirichlet-multinomial", "compositional data", "CLR", "Fisher-Rao", "scikit-learn",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "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",
+    "scipy",
+]
+
+[project.optional-dependencies]
+# The rafinat() Fisher-Rao Liouville embedding needs the `liudist` backend, which pulls in JAX.
+# compost() / hellnorm() are pure numpy+scipy -- installing plain `rafinat` needs none of this.
+#   pip install "rafinat[rafinat]"     # adds liudist (+ JAX) for the rafinat() method
+# For GPU acceleration, additionally install a CUDA JAX build yourself, e.g. `pip install jax-cuda12`.
+rafinat = ["liudist>=0.1"]
+gpu = ["liudist>=0.1"]                  # alias for the above
+# Optional: inherit sklearn's BaseEstimator/TransformerMixin for full Pipeline/clone support.
+# The transformers work without it (a light built-in shim provides the same fit/transform API).
+sklearn = ["scikit-learn"]
+test = ["pytest", "scikit-learn"]
+
+# [project.urls]                        # fill in before uploading, if you have a repo/homepage
+# Homepage = "https://github.com/<you>/rafinat"
+# Repository = "https://github.com/<you>/rafinat"
+
+[tool.setuptools]
+packages = ["rafinat"]
+license-files = ["LICENSE"]

rafinat-0.2.0/rafinat/__init__.py

@@ -0,0 +1,49 @@
+"""rafinat -- Dirichlet-Multinomial posterior normalizations for single-cell RNA-seq.
+
+Three single-cell count normalizations derived from a Dirichlet-Multinomial (Liouville)
+posterior view, with defaults set to the top performers of the Ahlmann-Eltze & Huber kNN
+benchmark.  Each is a scikit-learn-style transformer (``fit`` / ``transform`` / ``fit_transform``)
+so it slots straight into data-transformation / preprocessing pipelines:
+
+    compost   -- the DM-posterior generalisation of CLR (digamma log-corner with a top-trimmed
+                 per-cell centering).  ``p`` slides toward the sqrt/Hellinger end.
+    hellnorm  -- the Hellinger / Fisher-Rao spherical (sqrt-CLR) normalization with a top-trimmed
+                 per-cell reference.
+    rafinat   -- the complete Fisher-Rao Liouville embedding (composition arc length + radial
+                 cell-size coordinate).  Needs the ``liudist`` GPU submodule.
+
+``compost`` and ``hellnorm`` are pure numpy/scipy (CPU).  ``rafinat`` uses the bundled ``liudist``
+git submodule, which requires a GPU JAX build.
+
+You instantiate a transformer with its operating point, then ``fit`` it (which estimates and
+FREEZES the two data-driven pieces -- the concentration ``r`` and the per-cell reference level
+``beta``) and ``transform`` with it.  Because ``beta`` is per-cell, ``transform`` re-applies the
+frozen normalization to a matrix of the same ``(genes, cells)`` shape.  ``fit_transform(X)``
+reproduces the one-shot output of the original functional API.  scikit-learn is optional: if it is
+installed the transformers inherit ``BaseEstimator`` / ``TransformerMixin`` (full ``Pipeline`` /
+``clone`` support), otherwise a light built-in shim provides the same API.
+
+The optional per-gene standardization (``compost(..., zscore=True)`` and
+``rafinat(..., zcomp=True)``) is DISABLED by default, matching the benchmark's shipped defaults.
+
+    >>> import numpy as np, rafinat
+    >>> X = np.random.poisson(0.5, size=(2000, 500)).astype(float)   # genes x cells
+    >>> Z = rafinat.compost().fit_transform(X)     # = compost (p=0) trimmed  (CLR-dominating default)
+    >>> H = rafinat.hellnorm().fit_transform(X)    # = Hellnorm trimmed
+    >>> R = rafinat.rafinat().fit_transform(X)     # = rafinat (complete); (genes + 1) x cells
+    >>>
+    >>> tr = rafinat.compost(p=0.5).fit(X)         # estimate & freeze r_ and beta_ once
+    >>> Z2 = tr.transform(X)                        # re-apply the frozen normalization
+"""
+from ._dm import dm_power, estimate_r_pooled, estimate_r_percell, posterior_power_moments, alpha_global
+from ._base import BaseNormalizer
+from .compost import compost, hellnorm, z_score_rows   # compost_bend stays in rafinat.compost (experimental)
+from .liou import rafinat, fisher_rao_arclength, resolve_r, depthnorm
+
+__all__ = [
+    "compost", "hellnorm", "rafinat",
+    "BaseNormalizer",
+    "fisher_rao_arclength", "z_score_rows", "resolve_r", "depthnorm",
+    "dm_power", "estimate_r_pooled", "estimate_r_percell", "posterior_power_moments", "alpha_global",
+]
+__version__ = "0.2.0"

rafinat-0.2.0/rafinat/_base.py

@@ -0,0 +1,104 @@
+"""Scikit-learn-compatible transformer base for the rafinat normalizers.
+
+If scikit-learn is installed, the transformers inherit its ``BaseEstimator`` /
+``TransformerMixin`` -- so they drop straight into ``sklearn.pipeline.Pipeline`` and support
+``clone`` / ``get_params`` / ``set_params``.  Otherwise a light shim provides the same
+``get_params`` / ``set_params`` / ``fit_transform`` protocol, keeping the package's numpy +
+scipy-only footprint intact (scikit-learn is an optional extra, never a hard dependency).
+
+Data convention (unchanged from the old functional API): every transformer operates on a dense
+``(genes, cells)`` matrix -- genes are the features (rows), cells the samples (columns).
+``fit`` estimates and FREEZES the two data-driven pieces (the concentration ``r`` and the
+per-cell reference level ``beta``); ``transform`` re-applies that exact frozen normalization and
+therefore expects an array of the same ``(genes, cells)`` shape it was fitted on.  The one-shot
+``fit_transform(X)`` reproduces the output of the original module-level functions.
+"""
+from __future__ import annotations
+
+import inspect
+
+import numpy as np
+
+try:                                       # optional: full sklearn integration when available
+    from sklearn.base import BaseEstimator as _SkBase, TransformerMixin as _SkMixin
+    _HAS_SKLEARN = True
+except Exception:                          # pragma: no cover - sklearn is an optional extra
+    _HAS_SKLEARN = False
+
+
+class _ShimBase:
+    """Minimal ``BaseEstimator`` / ``TransformerMixin`` stand-in used when sklearn is absent.
+
+    Implements the same duck-typed protocol sklearn pipelines rely on: parameters are read off
+    the ``__init__`` signature (so every constructor argument must be stored verbatim on the
+    instance), and ``fit_transform`` is ``fit(...).transform(...)``.
+    """
+
+    @classmethod
+    def _param_names(cls):
+        init = cls.__init__
+        if init is object.__init__:
+            return []
+        names = []
+        for name, p in inspect.signature(init).parameters.items():
+            if name == "self":
+                continue
+            if p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+                raise RuntimeError(
+                    f"{cls.__name__}.__init__ may not use *args/**kwargs (scikit-learn convention)")
+            names.append(name)
+        return sorted(names)
+
+    def get_params(self, deep=True):
+        return {k: getattr(self, k) for k in self._param_names()}
+
+    def set_params(self, **params):
+        valid = self._param_names()
+        for k, v in params.items():
+            if k not in valid:
+                raise ValueError(
+                    f"invalid parameter {k!r} for estimator {type(self).__name__}; "
+                    f"valid parameters are {valid}")
+            setattr(self, k, v)
+        return self
+
+    def fit_transform(self, X, y=None, **fit_params):
+        return self.fit(X, y, **fit_params).transform(X)
+
+    def __repr__(self):
+        args = ", ".join(f"{k}={getattr(self, k, None)!r}" for k in self._param_names())
+        return f"{type(self).__name__}({args})"
+
+
+if _HAS_SKLEARN:
+    _Base, _Mixin = _SkBase, _SkMixin
+else:
+    _Base, _Mixin = _ShimBase, object
+
+
+class BaseNormalizer(_Base, _Mixin):
+    """Common fit/transform plumbing shared by :class:`compost`, :class:`hellnorm`, :class:`rafinat`."""
+
+    def _check_2d(self, X):
+        X = np.asarray(X, dtype=np.float64)
+        if X.ndim != 2:
+            raise ValueError(
+                f"{type(self).__name__} expects a 2-D (genes, cells) array, got ndim={X.ndim}")
+        return X
+
+    def _record_shape(self, X):
+        self.n_genes_, self.n_cells_ = X.shape
+
+    def _check_fitted(self):
+        if not hasattr(self, "n_cells_"):
+            raise RuntimeError(
+                f"This {type(self).__name__} instance is not fitted yet; call .fit(X) "
+                f"(or .fit_transform(X)) before .transform(X).")
+
+    def _check_transform_shape(self, X):
+        exp = (self.n_genes_, self.n_cells_)
+        if X.shape != exp:
+            raise ValueError(
+                f"{type(self).__name__}.transform received an array of shape {X.shape}, but the "
+                f"transformer was fitted on {exp} (genes, cells).  The frozen concentration and "
+                f"per-cell reference require the same shape; re-fit for a different gene/cell set.")