diffsvg 0.1.0__py3-none-any.whl

diffsvg/tl/stability.py

@@ -0,0 +1,335 @@
+"""Grid search over preprocessing/model options, to see how stable the gene ranking is.
+
+`check_stability` re-runs the pipeline per parameter combination (re-binning once per binning signature,
+on a gene subsample), ranks on a statistic rather than the panel-dependent p-values, and re-runs the
+baseline under other seeds to get a noise floor for the agreement.
+"""
+
+import inspect
+import itertools
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from tqdm.auto import tqdm
+
+from diffsvg.pp.utils import bin_obs
+
+from . import _exact
+from .model import DiffSVGModelSetup, _resolve_priors, fit_model, setup_model
+
+#: Parameters that need `bin_obs` re-run; the others only need a refit.
+_BIN_PARAMS = ("n_bsplines", "degree", "n_bins", "window_radius", "layer")
+_MODEL_PARAMS = ("likelihood", "priors", "use_binned")
+
+
+def _stability_defaults():
+    """Default for every tunable, read off the real signatures so they cannot drift."""
+    bin_params = inspect.signature(bin_obs).parameters
+    setup_params = inspect.signature(setup_model).parameters
+    fit_params = inspect.signature(fit_model).parameters
+    return {
+        **{name: bin_params[name].default for name in _BIN_PARAMS},
+        "likelihood": setup_params["likelihood"].default,
+        "priors": setup_params["priors"].default,
+        "use_binned": fit_params["use_binned"].default,
+    }
+
+
+def _format_value(value):
+    """Compact, readable rendering of a parameter value for run labels."""
+    if isinstance(value, dict):  # a priors override
+        # The full spec, not just the distribution name: two overrides of the same prior with different
+        # parameters must get different run labels.
+        return "+".join(
+            f"{name}:{spec[0]}({','.join(str(v) for v in spec[1:])})" for name, spec in sorted(value.items())
+        )
+    return str(value)
+
+
+@dataclass
+class StabilityResult:
+    """What `check_stability` found; consumed by `diffsvg.pl.plot_stability`.
+
+    Attributes
+    ----------
+    stats, ranks
+        `genes x runs` tables of the ranking statistic and of the rank
+        derived from it (``1`` = strongest).
+    similarity
+        `runs x runs` Spearman correlation between rank columns.
+    top_overlap
+        `runs x runs` fraction of each run's top `top_k` genes that it
+        shares with the other run.
+    sensitivity
+        One row per configuration that differs from the baseline in exactly
+        one parameter, with its agreement against the baseline - i.e. the
+        one-factor-at-a-time view of which knob actually moves the ranking.
+    configs
+        `runs x parameters` table of what each run was.
+    noise_floor
+        Baseline-vs-reseeded-baseline agreement, as
+        ``{"spearman": ..., "top_overlap": ...}``. Agreement at or below
+        this is within MCMC noise.
+    baseline, rank_by, top_k, genes
+        The baseline run's label, and the settings the comparison used.
+    """
+
+    stats: pd.DataFrame
+    ranks: pd.DataFrame
+    similarity: pd.DataFrame
+    top_overlap: pd.DataFrame
+    sensitivity: pd.DataFrame
+    configs: pd.DataFrame
+    noise_floor: dict
+    baseline: str
+    rank_by: str
+    top_k: int
+    genes: list
+
+
+def _resolve_genes(adata, genes, random_state):
+    if genes is None:
+        selected = list(adata.var_names)
+    elif isinstance(genes, int):
+        rng = np.random.default_rng(random_state)
+        size = min(genes, adata.n_vars)
+        selected = sorted(rng.choice(np.asarray(adata.var_names), size=size, replace=False).tolist())
+    else:
+        selected = list(genes)
+        missing = set(selected) - set(adata.var_names)
+        if missing:
+            raise KeyError(f"Genes not found in adata.var_names: {sorted(missing)}")
+    if len(selected) < 3:
+        raise ValueError(f"need at least 3 genes to compare rankings, got {len(selected)}.")
+    return selected
+
+
+def check_stability(
+    adata,
+    anchor,
+    condition,
+    grid,
+    baseline=None,
+    genes=50,
+    rank_by=None,
+    higher_is_stronger=True,
+    top_k=10,
+    n_seeds=2,
+    n_workers=1,
+    progressbar=True,
+    random_state=0,
+    design_matrix="design_matrix",
+    sample_kwargs=None,
+    test="parallel",
+    tau=None,
+    sample=None,
+    inference="auto",
+):
+    """Re-rank genes under every combination in `grid` and measure how much the ranking moves.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix, with `anchor`/`condition` in
+        ``adata.obsm[design_matrix]``. Never modified: each run bins and
+        fits out-of-place.
+    anchor, condition, design_matrix
+        Passed to `diffsvg.pp.bin_obs`. `condition` is required - the
+        ranking being checked is the differential one, so the condition-free
+        models are out of scope here.
+    grid
+        ``{parameter: [values]}`` over any of
+        ``("n_bsplines", "degree", "n_bins", "window_radius", "layer")``
+        (these re-bin) and ``("likelihood", "priors", "use_binned")`` (these
+        only refit). Priors are varied by passing a list of override dicts,
+        e.g. ``{"priors": [{"beta": ("normal", 0.0, 0.5)},
+        {"beta": ("normal", 0.0, 2.0)}]}``; see
+        `diffsvg.tl.model.DEFAULT_PRIORS`.
+    baseline
+        The configuration everything is compared against, as a dict of
+        parameter values. Defaults to the first value of each `grid` axis.
+    genes
+        Number of genes to subsample (default 50), an explicit list, or
+        `None` for all of them. The same genes are used for every run - a
+        different subsample per run would confound the comparison.
+    rank_by, higher_is_stronger
+        Column of `fit_model`'s statistics table to rank on, and whether
+        larger means stronger. Rank on a statistic rather than a p-value:
+        the Wald test's p-values are computed against the panel, so
+        subsampling shifts them and they do not compare across runs. Defaults
+        to ``"parallel_stat"`` for ``test="parallel"`` and ``"wald_stat"`` for
+        ``test="wald"``.
+    top_k
+        Size of the "top genes" set used for the overlap metric.
+    n_seeds
+        How many times to run the baseline, each with a different
+        `random_seed`, to establish the noise floor. `1` skips it. Ignored
+        when every run uses exact inference: the statistics are then
+        deterministic and the noise floor is 1.
+    n_workers, progressbar, sample_kwargs
+        As in `fit_model`; `sample_kwargs` is where to make the sweep
+        cheaper (e.g. ``{"draws": 300, "tune": 300}``), since ranking needs
+        far less precision than a final fit. The per-run progress bars are
+        suppressed in favour of one bar over runs.
+    random_state
+        Seed for the gene subsample.
+    test, tau
+        Which condition test every run uses, as in `fit_model`.
+    inference
+        Passed to `fit_model`.
+    sample
+        Passed to `diffsvg.pp.bin_obs`: the slide column for data with several
+        slides per condition, so every run uses the model with slide effects
+        (needs ``window_radius=None`` and ``test="parallel"``). Without it,
+        multi-slide data is pooled and the rankings are over-confident.
+
+    Returns
+    -------
+    StabilityResult
+    """
+    unknown = set(grid) - set(_BIN_PARAMS) - set(_MODEL_PARAMS)
+    if unknown:
+        raise ValueError(
+            f"Unknown grid parameter(s) {sorted(unknown)}. Available: {sorted(_BIN_PARAMS + _MODEL_PARAMS)}"
+        )
+    if not grid:
+        raise ValueError("`grid` is empty - pass at least one parameter to vary.")
+
+    if rank_by is None:
+        rank_by = "parallel_stat" if test == "parallel" else "wald_stat"
+    defaults = _stability_defaults()
+    gene_list = _resolve_genes(adata, genes, random_state)
+    sample_kwargs = dict(sample_kwargs or {})
+    base_seed = sample_kwargs.pop("random_seed", 42)
+
+    axes = list(grid)
+    configs = [
+        dict(defaults, **dict(zip(axes, combo, strict=True))) for combo in itertools.product(*(grid[a] for a in axes))
+    ]
+
+    baseline_config = dict(defaults, **{a: grid[a][0] for a in axes})
+    if baseline is not None:
+        unknown_baseline = set(baseline) - set(defaults)
+        if unknown_baseline:
+            raise ValueError(f"Unknown baseline parameter(s) {sorted(unknown_baseline)}.")
+        baseline_config = dict(defaults, **baseline)
+        if baseline_config not in configs:
+            configs.insert(0, baseline_config)
+
+    # Label runs by every parameter that differs between them, including a `baseline` value that is not on
+    # the grid, so that no two runs share a label (they would overwrite each other's column).
+    varying = [a for a in defaults if len({_format_value(c[a]) for c in configs}) > 1]
+
+    def label_for(config):
+        if not varying:
+            return "default"
+        return ", ".join(f"{a}={_format_value(config[a])}" for a in varying)
+
+    baseline_label = label_for(baseline_config)
+    runs = [(label_for(config), config, base_seed) for config in configs]
+    # Exact inference has no Monte Carlo error, so reseeding would only repeat the same run.
+    all_exact = inference in ("auto", "exact") and all(
+        _exact.supported(_resolve_priors(c["priors"]), c["likelihood"], sample is not None) for c in configs
+    )
+    if not all_exact:
+        runs += [
+            (f"{baseline_label} (reseed {i})", baseline_config, base_seed + i) for i in range(1, max(1, int(n_seeds)))
+        ]
+    labels = [label for label, _, _ in runs]
+    if len(set(labels)) != len(labels):
+        raise ValueError(f"Two runs got the same label, which would merge their results: {labels}")
+
+    # Group by binning signature so each distinct binning is computed once.
+    grouped = {}
+    for run in runs:
+        grouped.setdefault(tuple(_format_value(run[1][p]) for p in _BIN_PARAMS), []).append(run)
+
+    iterator = tqdm(total=len(runs), desc="Checking DiffSVG stability") if progressbar else None
+    columns = {}
+    for group in grouped.values():
+        bin_config = group[0][1]
+        binned = bin_obs(
+            adata,
+            anchor,
+            condition,
+            genes=gene_list,
+            design_matrix=design_matrix,
+            inplace=False,
+            sample=sample,
+            **{p: bin_config[p] for p in _BIN_PARAMS},
+        )
+        for label, config, seed in group:
+            model_setup = DiffSVGModelSetup(binned=binned, likelihood=config["likelihood"], priors=config["priors"])
+            stats_df, _, _ = fit_model(
+                adata,
+                model_setup,
+                n_workers=n_workers,
+                progressbar=False,
+                inplace=False,
+                use_binned=config["use_binned"],
+                sample_kwargs={**sample_kwargs, "random_seed": seed},
+                test=test,
+                tau=tau,
+                inference=inference,
+            )
+            columns[label] = stats_df[rank_by]
+            if iterator is not None:
+                iterator.update(1)
+    if iterator is not None:
+        iterator.close()
+
+    stats = pd.DataFrame(columns).reindex(gene_list)
+    ranks = stats.rank(ascending=not higher_is_stronger, method="average")
+
+    similarity = ranks.corr(method="spearman")
+    tops = {label: set(ranks[label].nsmallest(top_k).index) for label in ranks}
+    top_overlap = pd.DataFrame(
+        [[len(tops[a] & tops[b]) / top_k for b in ranks] for a in ranks], index=list(ranks), columns=list(ranks)
+    )
+
+    reseed_labels = [label for label, _, _ in runs if label.endswith(")") and " (reseed " in label]
+    noise_floor = {
+        "spearman": 1.0
+        if all_exact
+        else (float(min(similarity.loc[baseline_label, reseed_labels])) if reseed_labels else float("nan")),
+        "top_overlap": 1.0
+        if all_exact
+        else (float(min(top_overlap.loc[baseline_label, reseed_labels])) if reseed_labels else float("nan")),
+    }
+
+    sensitivity_rows = []
+    for label, config, _ in runs:
+        if label == baseline_label or label in reseed_labels:
+            continue
+        changed = [a for a in varying if config[a] != baseline_config[a]]
+        if len(changed) == 1:
+            sensitivity_rows.append(
+                {
+                    "parameter": changed[0],
+                    "value": _format_value(config[changed[0]]),
+                    "run": label,
+                    "spearman": float(similarity.loc[baseline_label, label]),
+                    "top_overlap": float(top_overlap.loc[baseline_label, label]),
+                }
+            )
+    sensitivity = pd.DataFrame(sensitivity_rows, columns=["parameter", "value", "run", "spearman", "top_overlap"])
+
+    config_table = pd.DataFrame(
+        [{a: _format_value(config[a]) for a in axes} for _, config, _ in runs], index=[label for label, _, _ in runs]
+    )
+    config_table = config_table[~config_table.index.duplicated()]
+
+    return StabilityResult(
+        stats=stats,
+        ranks=ranks,
+        similarity=similarity,
+        top_overlap=top_overlap,
+        sensitivity=sensitivity,
+        configs=config_table,
+        noise_floor=noise_floor,
+        baseline=baseline_label,
+        rank_by=rank_by,
+        top_k=top_k,
+        genes=gene_list,
+    )

diffsvg-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: diffsvg
+Version: 0.1.0
+Summary: Differential spatially variable genes
+Project-URL: Documentation, https://diffsvg.readthedocs.io/
+Project-URL: Homepage, https://github.com/theislab/diffsvg
+Project-URL: Source, https://github.com/theislab/diffsvg
+Author: Tim Treis
+Maintainer-email: Tim Treis <tim.treis@helmholtz-munich.de>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Tim Treis
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anndata>=0.13
+Requires-Dist: colorcet
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: patsy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: session-info2
+Requires-Dist: tqdm
+Provides-Extra: pymc
+Requires-Dist: arviz; extra == 'pymc'
+Requires-Dist: nutpie; extra == 'pymc'
+Requires-Dist: pymc; extra == 'pymc'
+Description-Content-Type: text/markdown
+
+# diffsvg
+
+[![Tests][badge-tests]][tests]
+[![Documentation][badge-docs]][documentation]
+
+[badge-tests]: https://img.shields.io/github/actions/workflow/status/theislab/diffsvg/test.yaml?branch=main
+[badge-docs]: https://app.readthedocs.org/projects/diffsvg/badge/
+
+Differential spatially variable genes
+
+## Getting started
+
+Please refer to the [documentation][],
+in particular, the [API documentation][].
+
+## Installation
+
+You need to have Python 3.12 or newer installed on your system.
+If you don't have Python installed, we recommend installing [uv][].
+
+We recommend managing dependencies in project-specific virtual environments to avoid dependency conflicts.
+This is most convenient using package managers such as [uv][].
+Choose from the options below to install diffsvg:
+
+<!--
+1. Add the latest release of `diffsvg` from [PyPI][] to your `uv` project:
+
+   ```bash
+   uv add diffsvg
+   ```
+
+1. Install the latest release into a [standard virtual environment][venv]:
+
+   ```bash
+   (after activating your venv)
+   pip install diffsvg
+   ```
+
+-->
+
+1. Install the latest development version:
+
+   ```bash
+   pip install git+https://github.com/theislab/diffsvg.git  # (or `uv add`)
+   ```
+
+The default inference is exact and needs no sampler. To use NUTS (`inference="nuts"`, only needed for non-normal priors), install the optional extra: `pip install "diffsvg[pymc] @ git+https://github.com/theislab/diffsvg.git"`.
+
+## Release notes
+
+See the [changelog][].
+
+## Contact
+
+For questions and help requests, you can reach out in the [scverse discourse][].
+If you found a bug, please use the [issue tracker][].
+
+## Citation
+
+> t.b.a
+
+[uv]: https://github.com/astral-sh/uv
+[scverse discourse]: https://discourse.scverse.org/
+[issue tracker]: https://github.com/theislab/diffsvg/issues
+[tests]: https://github.com/theislab/diffsvg/actions/workflows/test.yaml
+[documentation]: https://diffsvg.readthedocs.io
+[changelog]: https://diffsvg.readthedocs.io/page/changelog.html
+[api documentation]: https://diffsvg.readthedocs.io/page/api.html
+[pypi]: https://pypi.org/project/diffsvg
+[venv]: https://docs.python.org/3/tutorial/venv.html

diffsvg-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+diffsvg/__init__.py,sha256=27tffAL8AnPIPAA9qmTpK63xhWzXn6iy6g9IbmiNxsk,55
+diffsvg/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+diffsvg/pl/__init__.py,sha256=cQ9h7e9S0TjaqwOrCnk3CFsf917P3v-C9A3Yxr7MnEA,294
+diffsvg/pl/plot_clusters.py,sha256=GNigoKu4-s3fZrE5Hcg5Yu91ThIOG5D8hbKXRVqVFVk,9721
+diffsvg/pl/plot_results.py,sha256=WW-To73N9DKJw9NyQaQTgIL2ZLm9qsf2e223Y0yduZ0,18592
+diffsvg/pl/plot_stability.py,sha256=NrXzxMwVyR5Mf8Qb-AzjsdwXHO8h0mY3_6gEoShaTl8,7588
+diffsvg/pp/__init__.py,sha256=NqY-t6lR62vuInYDZu-PFF7uO5kuq9KApSaZ0_jPuDc,257
+diffsvg/pp/utils.py,sha256=7ISyCr-UFjCL_Vsa_0PwhtX2Fsbfm3aMFgbq34l8Ln0,26413
+diffsvg/tl/__init__.py,sha256=AEetgToMRQf8pi1KbrY3UULyl6UTb_B-60Ez3mm0Br0,483
+diffsvg/tl/_exact.py,sha256=V6ZRyx90igdlQ8IQ_uokGxfHZEoAK4C6hmcixhd0EKc,14306
+diffsvg/tl/clustering.py,sha256=rlN3DENhNvfMlv4TmOiCnyAdagh9CaNiEN_1X9oe0cM,6219
+diffsvg/tl/model.py,sha256=9yQlkRLW3bmx177u0TnKUQldGjc6jF7d4wcUg3vmjss,81850
+diffsvg/tl/stability.py,sha256=em2N03RyvxiyZgkSr2waFXCIlTABmWMrj8LEAsH5XHE,13188
+diffsvg-0.1.0.dist-info/METADATA,sha256=-XbQHAGdm-978ZSV-OmzDF6X6EaHp2HZU58nrV-YgVM,4952
+diffsvg-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+diffsvg-0.1.0.dist-info/licenses/LICENSE,sha256=NJjfrbWBi828T_GS40kAzIG9L3hqVmg0xD_zmOPCsoc,1517
+diffsvg-0.1.0.dist-info/RECORD,,

diffsvg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

diffsvg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Tim Treis
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.