sonic-spatial 1.0.0rc1__py3-none-any.whl

sonic/__init__.py

@@ -0,0 +1,73 @@
+"""
+sonic: kernel-based spatial pattern detection and comparison for spatial omics.
+
+The public top-level API is organised in four layers:
+
+1. **Kernels** — :class:`MatrixKernel` (dense / sparse), :class:`FFTKernel`
+   (regular grid), :class:`NUFFTKernel` (irregular 2D coordinates). The
+   :class:`~sonic.kernels.Kernel` and
+   :class:`~sonic.kernels.MatrixKernelBase` ABCs live in
+   :mod:`sonic.kernels` and are intended for backend authors.
+2. **Statistical tests** — :func:`spatial_q_test` and :func:`spatial_r_test`.
+   A single entry point per test dispatches on the kernel type (matrix, FFT,
+   or NUFFT). Signature: ``(x, kernel, null_params=None, return_pval=True,
+   is_standardized=False)``.
+3. **Detectors** — :class:`DetectorIrregular` consumes :class:`anndata.AnnData`
+   (irregular grids, matrix/NUFFT backends); :class:`DetectorGrid` consumes
+   :class:`spatialdata.SpatialData` (regular grids, FFT backend).
+4. **Comparators** — cross-sample pattern comparison:
+   :class:`ComparatorIrregular` on a list of AnnData (NUFFT backend);
+   :class:`ComparatorGrid` on a list of SpatialData (FFT backend).
+"""
+
+import logging
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+# Version resolution order: prefer the file written by ``setuptools-scm`` at
+# build time (``src/sonic/_version.py`` — see ``[tool.setuptools_scm]`` in
+# ``pyproject.toml``), fall back to installed-package metadata, then to a
+# last-known release string for unbuilt / shallow-clone checkouts.
+try:
+    from sonic._version import version as __version__  # type: ignore[assignment]
+except ImportError:  # _version.py absent — source checkout without a build step
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        __version__ = version("sonic-spatial")
+    except (ImportError, PackageNotFoundError):
+        __version__ = "0.0.0+unknown"
+
+from sonic.api import Comparator, Detector
+from sonic.comparators import ComparatorGrid, ComparatorIrregular
+from sonic.detectors.grid import DetectorGrid
+from sonic.detectors.irregular import DetectorIrregular
+from sonic.kernels import MatrixKernel
+from sonic.kernels.fft import FFTKernel
+from sonic.kernels.nufft import NUFFTKernel
+from sonic.statistics import spatial_q_test, spatial_r_test
+
+# The :class:`~sonic.kernels.Kernel` and
+# :class:`~sonic.kernels.MatrixKernelBase` ABCs are intentionally not
+# re-exported here. They are extension points for backend authors and
+# live at ``sonic.kernels`` (the canonical path). Importing them through
+# ``sonic`` directly is unsupported.
+
+__all__ = [
+    # Kernels
+    "MatrixKernel",
+    "FFTKernel",
+    "NUFFTKernel",
+    # Statistical tests
+    "spatial_q_test",
+    "spatial_r_test",
+    # Detectors
+    "DetectorIrregular",
+    "DetectorGrid",
+    # Cross-sample
+    "ComparatorIrregular",
+    "ComparatorGrid",
+    # Factories — type-dispatched discovery face on the four classes above
+    "Detector",
+    "Comparator",
+]

sonic/_rasterize.py

@@ -0,0 +1,95 @@
+"""
+Shared :func:`spatialdata.rasterize_bins` wrappers used by
+:class:`sonic.DetectorGrid` and :class:`sonic.ComparatorGrid`.
+
+Both consumers need the same boilerplate:
+
+1. Coerce the table's X matrix to CSC sparse (required by ``rasterize_bins``).
+2. Forward to ``spatialdata.rasterize_bins`` with the user-supplied keys.
+3. Restore structurally absent grid positions as ``NaN``; SpatialData emits
+   zeros for both absent bins and observed zero-valued bins.
+
+Callers differ only in what they do with the rasterized image afterwards —
+``DetectorGrid`` stashes it back into ``sdata.images`` under a derived key,
+``ComparatorGrid`` extracts the array and reindexes the gene axis — so the
+shared helper stops after restoring the raster's structural-missing mask.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import scipy.sparse as sp
+import spatialdata as sd
+
+__all__ = ["ensure_csc_table", "rasterize_table"]
+
+
+def _mean_fill_missing(values: np.ndarray, axis: tuple[int, ...]) -> np.ndarray:
+    """Mean-fill ``NaN`` bins in place so centering makes their residuals zero."""
+    missing = np.isnan(values)
+    if not missing.any():
+        return values
+    n_observed = np.prod([values.shape[i] for i in axis]) - missing.sum(axis=axis, keepdims=True)
+    np.copyto(values, 0.0, where=missing)
+    sums = values.sum(axis=axis, keepdims=True)
+    means = np.full_like(sums, np.nan)
+    np.divide(sums, n_observed, out=means, where=n_observed > 0)
+    np.copyto(values, means, where=missing)
+    return values
+
+
+def ensure_csc_table(sdata: Any, table_name: str) -> None:
+    """Coerce ``sdata.tables[table_name].X`` to CSC sparse in-place, if sparse.
+
+    ``spatialdata.rasterize_bins`` performs column-wise slicing and requires CSC.
+    Dense arrays are left untouched.
+    """
+    if table_name not in sdata.tables:
+        raise ValueError(f"Table {table_name!r} not found in sdata.")
+    table = sdata.tables[table_name]
+    X = getattr(table, "X", None)
+    if X is None or isinstance(X, np.ndarray):
+        return
+    if sp.issparse(X) and X.format != "csc":
+        table.X = X.tocsc()
+
+
+def rasterize_table(
+    sdata: Any,
+    *,
+    bins: str,
+    table_name: str,
+    col_key: str,
+    row_key: str,
+    value_key: str | list[str] | None = None,
+    return_region_as_labels: bool = False,
+):
+    """Rasterize a table while preserving structural missingness as ``NaN``.
+
+    ``spatialdata.rasterize_bins`` initializes its bounding rectangle with
+    zeros, making an absent bin indistinguishable from an observed zero. This
+    wrapper reconstructs occupancy from ``row_key`` / ``col_key`` and masks
+    only absent positions. The mask is applied lazily to image outputs; label
+    outputs are returned unchanged.
+    """
+    ensure_csc_table(sdata, table_name)
+    rasterized = sd.rasterize_bins(
+        sdata,
+        bins=bins,
+        table_name=table_name,
+        col_key=col_key,
+        row_key=row_key,
+        value_key=value_key,
+        return_region_as_labels=return_region_as_labels,
+    )
+    if return_region_as_labels:
+        return rasterized
+
+    table = sdata.tables[table_name]
+    rows = np.asarray(table.obs[row_key])
+    cols = np.asarray(table.obs[col_key])
+    occupied = np.zeros(rasterized.shape[-2:], dtype=bool)
+    occupied[(rows - rows.min()).astype(int), (cols - cols.min()).astype(int)] = True
+    return rasterized if occupied.all() else rasterized.where(occupied)

sonic/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0rc1'
+__version_tuple__ = version_tuple = (1, 0, 0, 'rc1')
+
+__commit_id__ = commit_id = None

sonic/api.py

@@ -0,0 +1,182 @@
+"""
+Top-level factory entry points: :func:`Detector` and :func:`Comparator`.
+
+Thin one-liner discovery face on top of the four explicit classes
+(:class:`DetectorIrregular`, :class:`DetectorGrid`,
+:class:`ComparatorIrregular`, :class:`ComparatorGrid`). Dispatches on
+the runtime type of the input data so users don't have to know the
+``Irregular`` / ``Grid`` split:
+
+>>> det = Detector(adata)             # → DetectorIrregular
+>>> det = Detector(sdata)             # → DetectorGrid
+>>> cmp = Comparator([adata, ...])    # → ComparatorIrregular
+>>> cmp = Comparator([sdata, ...])    # → ComparatorGrid
+
+The factories only check ``isinstance`` to pick the right class, then
+forward kwargs verbatim. Asymmetry between the two:
+
+- :func:`Detector` does **not** pass the data argument to the
+  constructor — the caller chains ``.setup_data(data)`` afterwards
+  (matching the explicit-class flow).
+- :func:`Comparator` **does** pass the sample list as the first
+  positional argument, since both comparator constructors take
+  ``samples`` there. Cross-sample contrasts (``design``) are
+  supplied later, at test time, on
+  :meth:`~sonic.ComparatorIrregular.test_diff_freq` /
+  :meth:`~sonic.ComparatorIrregular.test_diff_expr`.
+
+For advanced use (custom kernel selection, sample-list inputs that
+mix two backends intentionally) prefer the explicit class names —
+the factories deliberately reject mixed-type lists with a
+:class:`TypeError`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from sonic.comparators import ComparatorGrid, ComparatorIrregular
+from sonic.detectors.grid import DetectorGrid
+from sonic.detectors.irregular import DetectorIrregular
+
+__all__ = ["Detector", "Comparator"]
+
+
+def _is_anndata(obj: Any) -> bool:
+    """Return True if ``obj`` is an :class:`anndata.AnnData`. Lazy
+    import so the factories work even when ``anndata`` isn't
+    available — though in practice ``anndata`` is a hard dependency
+    of :mod:`sonic`.
+    """
+    try:
+        from anndata import AnnData
+    except ImportError:  # pragma: no cover — anndata is a hard dep
+        return False
+    return isinstance(obj, AnnData)
+
+
+def _is_spatialdata(obj: Any) -> bool:
+    """Return True if ``obj`` is a :class:`spatialdata.SpatialData`.
+    Lazy import so the factories raise a clear :class:`TypeError`
+    rather than :class:`ImportError` when ``spatialdata`` isn't
+    installed.
+    """
+    try:
+        from spatialdata import SpatialData
+    except ImportError:
+        return False
+    return isinstance(obj, SpatialData)
+
+
+def _supported_types_msg() -> str:
+    return (
+        "supported types: anndata.AnnData (→ DetectorIrregular / "
+        "ComparatorIrregular) or spatialdata.SpatialData (→ "
+        "DetectorGrid / ComparatorGrid)"
+    )
+
+
+def Detector(data: Any, **kwargs: Any) -> Any:  # noqa: N802 - factory mimics class names
+    """Construct the right :class:`~sonic.Detector` for ``data``.
+
+    Dispatches on ``type(data)``:
+
+    - :class:`anndata.AnnData` → :class:`~sonic.DetectorIrregular`.
+    - :class:`spatialdata.SpatialData` → :class:`~sonic.DetectorGrid`.
+
+    The data itself is **not** passed to the constructor — the caller
+    is expected to chain ``.setup_data(data, ...)`` afterwards (the
+    factory only uses ``data``'s type to pick a class).
+
+    Parameters
+    ----------
+    data : anndata.AnnData or spatialdata.SpatialData
+        The dataset whose type drives the dispatch.
+    **kwargs
+        Forwarded to the chosen class's ``__init__`` verbatim.
+
+    Returns
+    -------
+    DetectorIrregular or DetectorGrid
+        Constructed (but not yet set up) detector instance.
+
+    Raises
+    ------
+    TypeError
+        If ``data`` is neither an ``AnnData`` nor a ``SpatialData``.
+
+    Examples
+    --------
+    >>> from sonic import Detector
+    >>> det = Detector(adata, kernel_method="gaussian", backend="matrix")
+    >>> det = det.setup_data(adata)
+    >>> df = det.compute_qstat()
+    """
+    if _is_anndata(data):
+        return DetectorIrregular(**kwargs)
+    if _is_spatialdata(data):
+        return DetectorGrid(**kwargs)
+    raise TypeError(
+        f"Detector cannot dispatch on type {type(data).__name__!r}; " f"{_supported_types_msg()}."
+    )
+
+
+def Comparator(  # noqa: N802 - factory mimics class names
+    data_list: Sequence[Any], **kwargs: Any
+) -> Any:
+    """Construct the right :class:`~sonic.Comparator` for ``data_list``.
+
+    Dispatches on the homogeneous element type:
+
+    - all :class:`anndata.AnnData` → :class:`~sonic.ComparatorIrregular`.
+    - all :class:`spatialdata.SpatialData` → :class:`~sonic.ComparatorGrid`.
+    - mixed types → :class:`TypeError`.
+
+    Unlike :func:`Detector`, the data list **is** forwarded as the
+    first positional arg to the chosen class (both comparator
+    constructors take ``samples`` as their first positional
+    parameter).
+
+    Parameters
+    ----------
+    data_list : sequence of anndata.AnnData or sequence of spatialdata.SpatialData
+        Per-sample inputs. Must all be of the same type.
+    **kwargs
+        Forwarded to the chosen class's ``__init__`` verbatim
+        (e.g. ``gene_names=...``, ``feature_mode=...``, etc.). The
+        cross-sample contrast (``design``) is supplied later on
+        :meth:`test_diff_freq` / :meth:`test_diff_expr`, not here.
+
+    Returns
+    -------
+    ComparatorIrregular or ComparatorGrid
+        Constructed comparator instance.
+
+    Raises
+    ------
+    TypeError
+        If ``data_list`` is empty or its elements aren't all the
+        same supported type.
+
+    Examples
+    --------
+    >>> from sonic import Comparator
+    >>> cmp = Comparator([a1, a2, a3]).compute_spectra()
+    >>> df = cmp.test_diff_freq(group_labels)
+    """
+    items = list(data_list)
+    if len(items) == 0:
+        raise TypeError(
+            f"Comparator requires a non-empty list of samples; " f"{_supported_types_msg()}."
+        )
+    all_anndata = all(_is_anndata(x) for x in items)
+    all_spatialdata = all(_is_spatialdata(x) for x in items)
+    if all_anndata:
+        return ComparatorIrregular(items, **kwargs)
+    if all_spatialdata:
+        return ComparatorGrid(items, **kwargs)
+    raise TypeError(
+        f"Comparator received a list of mixed / unsupported types "
+        f"{[type(x).__name__ for x in items]}; {_supported_types_msg()}."
+    )

sonic/comparators/__init__.py

@@ -0,0 +1,33 @@
+"""
+``sonic.comparators`` — cross-sample spatial-pattern comparison.
+
+Subpackage grouping the layer-4 public classes:
+
+- :class:`ComparatorIrregular` — wraps a sequence of
+  :class:`anndata.AnnData` (irregular spots, NUFFT backend).
+- :class:`ComparatorGrid` — wraps a sequence of
+  :class:`spatialdata.SpatialData` (regular rasterized bins, FFT
+  backend).
+
+Both classes share the same post-``compute_spectra`` surface
+(``normalize_background``, ``normalize_covariates``,
+``test_diff_freq``, ``test_diff_expr``) through
+the private :class:`~sonic.comparators.base._ComparatorBase` mixin.
+Cross-sample contrasts are supplied at test time via the ``design``
+argument on the test methods — the comparator itself is
+design-agnostic, so one fitted comparator can serve any number of
+unrelated contrasts on the same spectra. The shape-only frequency
+test is available via a ``normalize_shape: bool = False`` keyword on
+:meth:`test_diff_freq` (forwarded to the standalone ``compare_*``
+function).
+
+The array-level spectral feature helpers live in
+:mod:`sonic.comparators.features`; normalization primitives live in
+:mod:`sonic.comparators.normalization`; statistical comparison
+primitives live in :mod:`sonic.comparators.multisample`.
+"""
+
+from sonic.comparators.grid import ComparatorGrid
+from sonic.comparators.irregular import ComparatorIrregular
+
+__all__ = ["ComparatorIrregular", "ComparatorGrid"]