destriper 0.1.0__tar.gz

destriper-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# macOS
+.DS_Store
+
+# Python build / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.pixi/
+
+# Results are experiment outputs, not part of the package
+results/
+
+# Downloaded tutorial datasets (multi-GB, fetched on demand)
+data/

destriper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paola Malsot
+
+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.

destriper-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: destriper
+Version: 0.1.0
+Summary: Estimate and correct row/column multiplicative stripe artifacts in high-resolution spatial transcriptomics count data.
+Project-URL: Homepage, https://github.com/paolamalsot/destriper
+Project-URL: Source, https://github.com/paolamalsot/destriper
+Author: Paola Malsot
+License: MIT
+License-File: LICENSE
+Keywords: destriping,glm,negative-binomial,spatial-transcriptomics,visium-hd
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: glum==3.1.2
+Requires-Dist: joblib
+Requires-Dist: numpy<2
+Requires-Dist: pandas<3
+Requires-Dist: scikit-learn
+Requires-Dist: scipy<1.15,>=1.9
+Requires-Dist: tabmat==4.2.1
+Requires-Dist: xxhash<4,>=3.6
+Provides-Extra: anndata
+Requires-Dist: anndata; extra == 'anndata'
+Provides-Extra: dev
+Requires-Dist: anndata; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1><img src="docs/icon/icon.png" alt="D" width="45" align="bottom">estriper</h1>
+
+**Destriper** corrects striping artefacts in
+high-resolution spatial transcriptomics count data (e.g. Visium HD 2 µm bins).
+
+Under the hood, the method fits a negative binomial model to each nucleic bin $ij$ total counts $k_{ij}$: $k_{ij} \sim NB(\text{mean} = c_p h_i w_j, \text{dispersion} = \theta)$, where $h_i$, $w_j$ are row/column stripe
+factors, and $c_p$ a per-nucleus concentration [counts/bin]. The fitted stripe factors are then
+applied to **all** bins to produce destriped counts.
+
+<p align="center">
+  <img src="docs/method_scheme.png" alt="Method overview" width="700">
+</p>
+
+* The underlying mean-variance relationship reads $\text{var} = \mu + \theta\mu^2$.
+* Fitted stripe factors $h_i$ and $w_j$ equal 1 on average.
+
+## Cite
+
+To learn more about the method, or to cite, use:
+
+> Paola Malsot, Malte Londschien, Valentina Boeva, Gunnar Rätsch, Striping artifact removal in VisiumHD data through nuclear counts modeling, *Bioinformatics*, Volume 42, Issue Supplement_1, July 2026, btag306, https://doi.org/10.1093/bioinformatics/btag306
+
+## Install
+
+```bash
+pip install destriper            # low-level interface
+pip install "destriper[anndata]" # + AnnData interface
+```
+
+## Tutorial
+
+See the [tutorial notebook](docs/tutorial.ipynb) for an example on Visium HD mouse brain data.
+
+## Usage
+
+### Low-level interface
+
+```python
+import destriper as ds
+
+# nucleus bins only; counts are per-bin TOTAL counts
+result = ds.fit(
+    counts,          # 1-D int array
+    row_indices,     # 1-D int array (array-grid row)
+    column_indices,  # 1-D int array (array-grid col)
+    nucl_labels,     # 1-D array of nucleus ids (non-null)
+    cv="spatial",    # "spatial" | "default" | int (KFold) | per-bin group array
+    max_iter_theta=5,
+    max_iter=100_000,
+)
+
+result.row_factors        # pandas Series h_i
+result.col_factors        # pandas Series w_j
+result.nucl_concentration # pandas Series c_p
+result.dispersion         # fitted NB theta
+
+# apply to ALL bins (nucleus bins -> quantile matching, others -> division)
+corrected_totals = ds.destripe_tot_counts(
+    tot_counts, row_indices, column_indices, nucl_labels, result
+)
+
+# rescale the sparse count matrix to the corrected totals
+corrected_matrix, achieved_totals = ds.rescale(count_matrix, corrected_totals)
+```
+
+`achieved_totals` can differ from `corrected_totals` on **originally-empty bins**:
+a zero row cannot be rescaled to a positive target, so it stays zero. Both are
+returned so the discrepancy is explicit.
+
+### Anndata interface
+
+```python
+import destriper as ds
+
+result = ds.fit_adata(
+    adata,
+    nucl_key="nucleus_id",
+    count_key="total_counts",   # None -> compute from adata.X
+    row_key="array_row",
+    col_key="array_col",
+)
+
+ds.destripe_adata(adata, result, source_layer=None, target_layer="destriped")
+# writes adata.layers["destriped"], adata.obs["ds_destripe_factor"], adata.obs["ds_corrected_counts"]
+# and adata.uns["destriper"]["result"]
+```
+
+Fitting uses only bins with a non-null `nucl_key`; unlabelled (cytoplasm) bins
+are ignored during fitting and corrected by division at destriping time.
+
+## Notes
+
+- `glum==3.1.2` and `tabmat==4.2.1` are pinned exactly — the coordinate-descent
+  solver relies on private internals of those versions.
+- This package is derived from the [destriping-GLM](https://github.com/paolamalsot/destriping-glm)
+  repo.

destriper-0.1.0/README.md

@@ -0,0 +1,96 @@
+<h1><img src="docs/icon/icon.png" alt="D" width="45" align="bottom">estriper</h1>
+
+**Destriper** corrects striping artefacts in
+high-resolution spatial transcriptomics count data (e.g. Visium HD 2 µm bins).
+
+Under the hood, the method fits a negative binomial model to each nucleic bin $ij$ total counts $k_{ij}$: $k_{ij} \sim NB(\text{mean} = c_p h_i w_j, \text{dispersion} = \theta)$, where $h_i$, $w_j$ are row/column stripe
+factors, and $c_p$ a per-nucleus concentration [counts/bin]. The fitted stripe factors are then
+applied to **all** bins to produce destriped counts.
+
+<p align="center">
+  <img src="docs/method_scheme.png" alt="Method overview" width="700">
+</p>
+
+* The underlying mean-variance relationship reads $\text{var} = \mu + \theta\mu^2$.
+* Fitted stripe factors $h_i$ and $w_j$ equal 1 on average.
+
+## Cite
+
+To learn more about the method, or to cite, use:
+
+> Paola Malsot, Malte Londschien, Valentina Boeva, Gunnar Rätsch, Striping artifact removal in VisiumHD data through nuclear counts modeling, *Bioinformatics*, Volume 42, Issue Supplement_1, July 2026, btag306, https://doi.org/10.1093/bioinformatics/btag306
+
+## Install
+
+```bash
+pip install destriper            # low-level interface
+pip install "destriper[anndata]" # + AnnData interface
+```
+
+## Tutorial
+
+See the [tutorial notebook](docs/tutorial.ipynb) for an example on Visium HD mouse brain data.
+
+## Usage
+
+### Low-level interface
+
+```python
+import destriper as ds
+
+# nucleus bins only; counts are per-bin TOTAL counts
+result = ds.fit(
+    counts,          # 1-D int array
+    row_indices,     # 1-D int array (array-grid row)
+    column_indices,  # 1-D int array (array-grid col)
+    nucl_labels,     # 1-D array of nucleus ids (non-null)
+    cv="spatial",    # "spatial" | "default" | int (KFold) | per-bin group array
+    max_iter_theta=5,
+    max_iter=100_000,
+)
+
+result.row_factors        # pandas Series h_i
+result.col_factors        # pandas Series w_j
+result.nucl_concentration # pandas Series c_p
+result.dispersion         # fitted NB theta
+
+# apply to ALL bins (nucleus bins -> quantile matching, others -> division)
+corrected_totals = ds.destripe_tot_counts(
+    tot_counts, row_indices, column_indices, nucl_labels, result
+)
+
+# rescale the sparse count matrix to the corrected totals
+corrected_matrix, achieved_totals = ds.rescale(count_matrix, corrected_totals)
+```
+
+`achieved_totals` can differ from `corrected_totals` on **originally-empty bins**:
+a zero row cannot be rescaled to a positive target, so it stays zero. Both are
+returned so the discrepancy is explicit.
+
+### Anndata interface
+
+```python
+import destriper as ds
+
+result = ds.fit_adata(
+    adata,
+    nucl_key="nucleus_id",
+    count_key="total_counts",   # None -> compute from adata.X
+    row_key="array_row",
+    col_key="array_col",
+)
+
+ds.destripe_adata(adata, result, source_layer=None, target_layer="destriped")
+# writes adata.layers["destriped"], adata.obs["ds_destripe_factor"], adata.obs["ds_corrected_counts"]
+# and adata.uns["destriper"]["result"]
+```
+
+Fitting uses only bins with a non-null `nucl_key`; unlabelled (cytoplasm) bins
+are ignored during fitting and corrected by division at destriping time.
+
+## Notes
+
+- `glum==3.1.2` and `tabmat==4.2.1` are pinned exactly — the coordinate-descent
+  solver relies on private internals of those versions.
+- This package is derived from the [destriping-GLM](https://github.com/paolamalsot/destriping-glm)
+  repo.

destriper-0.1.0/destriper/__init__.py

@@ -0,0 +1,45 @@
+"""destriper — estimate and correct row/column multiplicative stripe
+artifacts in high-resolution spatial transcriptomics count data.
+
+Numerical core::
+
+    import destriper as ds
+    result = ds.fit(counts, row_indices, column_indices, nucl_labels)
+    corrected_totals = ds.destripe_tot_counts(tot_counts, rows, cols, labels, result)
+    corrected_matrix, achieved = ds.rescale(count_matrix, corrected_totals)
+
+Optional AnnData layer (``pip install destriper[anndata]``)::
+
+    result = ds.fit_adata(adata, nucl_key="nucleus_id")
+    ds.destripe_adata(adata, result, target_layer="destriped")
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from destriper._core import fit
+from destriper._destripe import destripe_tot_counts, rescale
+from destriper._result import FitResult
+
+if TYPE_CHECKING:
+    from destriper._adata import destripe_adata, fit_adata
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "fit",
+    "destripe_tot_counts",
+    "rescale",
+    "FitResult",
+    "fit_adata",
+    "destripe_adata",
+]
+
+
+def __getattr__(name):
+    # Lazy AnnData layer: import (and require) anndata only on first use.
+    if name in ("fit_adata", "destripe_adata"):
+        from destriper import _adata
+
+        return getattr(_adata, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

destriper-0.1.0/destriper/_adata.py

@@ -0,0 +1,141 @@
+"""Optional AnnData convenience layer.
+
+Requires ``anndata`` (``pip install destriper[anndata]``). Imported lazily
+by ``destriper.__getattr__`` so the numerical core has no hard dependency
+on anndata.
+"""
+import logging
+
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+
+from destriper._core import fit as _fit
+from destriper._destripe import (
+    destripe_factors,
+    destripe_tot_counts as _destripe_tot_counts,
+    rescale as _rescale,
+)
+from destriper._result import FitResult
+
+logger = logging.getLogger("destriper")
+
+
+def _require_anndata():
+    try:
+        import anndata  # noqa: F401
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "The AnnData layer requires `anndata`. "
+            "Install it with `pip install destriper[anndata]`."
+        ) from e
+
+
+def _totals(adata, count_key):
+    if count_key is not None:
+        return np.asarray(adata.obs[count_key].to_numpy(), dtype=float)
+    return np.asarray(adata.X.sum(axis=1)).ravel().astype(float)
+
+
+def fit_adata(
+    adata,
+    *,
+    nucl_key: str = "nucleus_id",
+    count_key: str | None = "total_counts",
+    row_key: str = "array_row",
+    col_key: str = "array_col",
+    cv_group_key: str | None = None,
+    max_iter_theta: int = 5,
+    max_iter: int = 100_000,
+    cv="spatial",
+) -> FitResult:
+    """Fit the stripe GLM from an AnnData.
+
+    Uses only nuclear bins (rows with a non-null ``obs[nucl_key]``); unlabelled
+    bins are ignored. ``count_key`` supplies per-bin totals from ``.obs``; if
+    ``None`` they are computed from ``adata.X``. See :func:`destriper.fit`
+    for the other parameters. ``cv_group_key`` names an ``.obs`` column of CV
+    group ids (overrides ``cv``).
+    """
+    _require_anndata()
+    obs = adata.obs
+    labels = obs[nucl_key].to_numpy()
+    is_nucl = ~pd.isna(labels)
+    n_total = len(labels)
+    n_nucl = int(is_nucl.sum())
+    if n_nucl == 0:
+        raise ValueError(f"No nuclear bins: all values in obs[{nucl_key!r}] are null.")
+    if n_nucl < n_total:
+        logger.info(
+            "Fitting on %d nuclear bins (of %d total); %d unlabelled bins ignored.",
+            n_nucl,
+            n_total,
+            n_total - n_nucl,
+        )
+
+    counts = _totals(adata, count_key)[is_nucl]
+    rows = np.asarray(obs[row_key].to_numpy())[is_nucl]
+    cols = np.asarray(obs[col_key].to_numpy())[is_nucl]
+    nucl_labels = labels[is_nucl]
+
+    cv_arg = cv
+    if cv_group_key is not None:
+        cv_arg = np.asarray(obs[cv_group_key].to_numpy())[is_nucl]
+
+    return _fit(
+        counts,
+        rows,
+        cols,
+        nucl_labels,
+        max_iter_theta=max_iter_theta,
+        max_iter=max_iter,
+        cv=cv_arg,
+    )
+
+
+def destripe_adata(
+    adata,
+    result: FitResult,
+    *,
+    source_layer: str | None = None,
+    target_layer: str = "destriped",
+    nucl_key: str = "nucleus_id",
+    row_key: str = "array_row",
+    col_key: str = "array_col",
+) -> None:
+    """Apply a fitted :class:`FitResult` to an AnnData in place.
+
+    Writes:
+
+    - ``adata.layers[target_layer]`` — the destriped count matrix
+    - ``adata.obs["ds_destripe_factor"]`` — the per-bin stripe factor
+    - ``adata.obs["ds_corrected_counts"]`` — the target corrected totals from
+      :func:`destriper.destripe_tot_counts`. Note this is the *target*, not
+      the rescaled-matrix row-sums (``layers[target_layer].sum(1)``); the two
+      differ on originally-empty bins (see :func:`destriper.rescale`).
+    - ``adata.uns["destriper"]["result"]`` — the serialized fit
+      (:meth:`FitResult.to_uns`): ``row_factors``, ``col_factors`` and
+      ``nucl_concentration`` as one-column DataFrames plus the scalar fit
+      parameters. Rebuild it with :meth:`FitResult.from_uns`.
+    """
+    _require_anndata()
+    obs = adata.obs
+    rows = np.asarray(obs[row_key].to_numpy())
+    cols = np.asarray(obs[col_key].to_numpy())
+    labels = obs[nucl_key].to_numpy()
+
+    X = adata.X if source_layer is None else adata.layers[source_layer]
+    if not sp.issparse(X):
+        X = sp.csr_matrix(X)
+
+    tot = np.asarray(X.sum(axis=1)).ravel().astype(float)
+    corrected = _destripe_tot_counts(tot, rows, cols, labels, result)
+    X_corr, _achieved = _rescale(X, corrected)
+
+    adata.layers[target_layer] = X_corr
+    adata.obs["ds_destripe_factor"] = destripe_factors(
+        result.row_factors, result.col_factors, rows, cols
+    )
+    adata.obs["ds_corrected_counts"] = corrected
+    uns = adata.uns.setdefault("destriper", {})
+    uns["result"] = result.to_uns()

destriper-0.1.0/destriper/_core.py

@@ -0,0 +1,167 @@
+import logging
+import warnings
+from contextlib import contextmanager
+
+import numpy as np
+import pandas as pd
+
+from destriper._df import build_fit_df, strip_id_prefix, warn_large_regions
+from destriper._result import FitResult
+
+logger = logging.getLogger("destriper")
+
+_V6_MODEL_ARGS = dict(
+    init_method="ones",
+    init_method_args={"c_mean": True},
+    family="nbinom",
+    family_params={"theta": 1.0},
+    n_alphas=10,
+    alphas=None,
+    P2="hw_only",
+    P1="hw_only",
+    freeze_c=False,
+    sklearnCV=True,
+    sklearnCV_one_SE_rule=False,
+    warm_start_alpha=True,
+    fit_theta_iter=True,
+    fit_theta_iter_loc="out",
+    selection="random",
+    solver="coordinate_descent",
+    parallel=True,
+    reestimate_c_on_val=True,
+)
+
+
+@contextmanager
+def _quiet_fit_warnings():
+    """Silence a few known-benign warnings from the vendored CV code.
+
+    The cross-validation ``c`` re-estimation divides by per-group sums that can
+    be zero on some folds (result discarded via ``np.where``), and a pandas
+    groupby-apply triggers a deprecation warning. Neither affects results; we
+    scope the filters by message so genuine warnings still surface.
+    """
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore", message=".*divide by zero encountered.*", category=RuntimeWarning
+        )
+        warnings.filterwarnings(
+            "ignore", message=".*invalid value encountered.*", category=RuntimeWarning
+        )
+        warnings.filterwarnings(
+            "ignore",
+            message=".*DataFrameGroupBy.apply operated on the grouping columns.*",
+            category=FutureWarning,
+        )
+        yield
+
+
+def _groups_to_splits(groups):
+    """Leave-one-group-out CV splits (positional) from a per-bin group array."""
+    groups = np.asarray(groups)
+    all_pos = np.arange(len(groups))
+    splits = [
+        (np.setdiff1d(all_pos, test, assume_unique=False), test)
+        for g in pd.unique(groups)
+        if len((test := all_pos[groups == g])) > 0
+    ]
+    if len(splits) < 2:
+        raise ValueError("cv group array must define at least 2 non-empty groups.")
+    return splits
+
+
+def _resolve_cv(cv, n_bins):
+    if isinstance(cv, str):
+        if cv not in ("spatial", "default"):
+            raise ValueError(
+                f"cv string must be 'spatial' or 'default', got {cv!r}."
+            )
+        return cv
+    if isinstance(cv, (int, np.integer, bool)) and not isinstance(cv, bool):
+        n = int(cv)
+        if n < 2:
+            raise ValueError("integer cv (number of KFold folds) must be >= 2.")
+        return n
+    # per-bin group-id array -> leave-one-group-out
+    groups = np.asarray(cv)
+    if groups.ndim != 1 or len(groups) != n_bins:
+        raise ValueError(
+            "cv group array must be 1-D with one entry per bin "
+            f"(expected length {n_bins}, got {groups.shape})."
+        )
+    return _groups_to_splits(groups)
+
+
+def fit(
+    counts,
+    row_indices,
+    column_indices,
+    nucl_labels,
+    *,
+    max_iter_theta: int = 5,
+    max_iter: int = 100_000,
+    cv="spatial",
+) -> FitResult:
+    """Fit the row/column stripe GLM on per-bin total counts of nucleus bins.
+
+    Fits ``k_ij ~ NB(mean = c_p * h_i * w_j)`` (log link) with the tuned v6
+    recipe. Only nucleus (labelled) bins are used; the returned factors are
+    later applied to all bins via :func:`destripe_tot_counts`.
+
+    Parameters
+    ----------
+    counts : 1-D int array
+        Per-bin total counts (nucleus bins only).
+    row_indices, column_indices : 1-D int arrays
+        Array-grid row / column index per bin.
+    nucl_labels : 1-D array
+        Nucleus id per bin; must be non-null.
+    max_iter_theta : int, default 5
+        Cap on the dispersion (theta) iteration.
+    max_iter : int, default 100000
+        Cap on the GLM solver iterations per fit.
+    cv : "spatial" | "default" | int | 1-D array, default "spatial"
+        Cross-validation folds for regularization selection: ``"spatial"``
+        (4 grid quadrants, leave-one-quadrant-out), ``"default"`` (5-fold
+        KFold), an int (KFold with that many folds), or a per-bin group-id
+        array (leave-one-group-out).
+
+    Returns
+    -------
+    FitResult
+    """
+    df = build_fit_df(counts, row_indices, column_indices, nucl_labels)
+    warn_large_regions(df, threshold=100)
+    cv_split_method = _resolve_cv(cv, n_bins=len(df))
+
+    # Lazy import: pulls in glum/tabmat only when actually fitting.
+    from destriper._fit.glum_wrapper import GlumWrapper
+
+    model = GlumWrapper(
+        data_df=df,
+        cv_split_method=cv_split_method,
+        fit_theta_max_iter=int(max_iter_theta),
+        max_iter=int(max_iter),
+        **_V6_MODEL_ARGS,
+    )
+    with _quiet_fit_warnings():
+        model.fit()
+
+    sol = model.sol_
+    status = model.status_dict
+
+    concentration = sol.c.copy()
+    concentration.index = pd.Index(
+        [strip_id_prefix(x) for x in concentration.index], name="nucleus"
+    )
+
+    return FitResult(
+        row_factors=sol.h,
+        col_factors=sol.w,
+        nucl_concentration=concentration,
+        dispersion=float(model.theta),
+        converged=bool(status["converged"]),
+        theta_converged=bool(status["theta_iter_converged_"]),
+        theta_iterations=int(status["theta_iter_"]),
+        alpha=float(model.alpha),
+    )