from __future__ import annotations
import warnings
from collections.abc import Callable, Iterable, Mapping, Sequence
from functools import partial
from numbers import Real
from typing import Any, Literal
import numpy as np
import pandas as pd
import scanpy as sc
from anndata import AnnData
from fast_array_utils.conv import to_dense
from fast_array_utils.types import HasArrayNamespace as Array
from numpy.typing import NDArray
from pandas.api.types import is_bool_dtype
from sklearn.base import clone
from sklearn.mixture import GaussianMixture
from spatialdata import SpatialData, sanitize_table
from spatialdata._logging import logger as logg
from squidpy._docs import d
from squidpy._utils import (
RNGLike,
SeedLike,
deprecated_randomness_param,
legacy_random,
)
from squidpy._validators import assert_isinstance, assert_key_in_adata, normalize_choice
from squidpy.gr._clusterers import Clusterer, LeidenClusterer
from squidpy.gr._nhood import (
_aggregate_over,
_assert_hop_request,
compute_hop_adjacency_matrices,
nhood_aggregate,
)
from squidpy.gr._utils import extract_adata_if_sdata
__all__ = [
"calculate_niche",
"calculate_niche_neighborhood",
"calculate_niche_utag",
"calculate_niche_cellcharter",
"calculate_niche_spatialleiden",
]
[docs]
@d.dedent
@deprecated_randomness_param
def calculate_niche( # noqa: PLR0917, deprecated and removed in v1.9.0
data: AnnData | SpatialData,
flavor: Literal["neighborhood", "utag", "cellcharter", "spatialleiden"],
library_key: str | None = None,
mask: pd.core.series.Series = None,
groups: str | None = None,
n_neighbors: int | None = None,
resolutions: float | tuple[float, float] | list[float | tuple[float, float]] | None = None,
min_niche_size: int | None = None,
scale: bool = True,
abs_nhood: bool = False,
distance: int | None = None,
n_hop_weights: list[float] | None = None,
aggregation: str | None = None,
n_components: int | None = None,
spatial_connectivities_key: str = "spatial_connectivities",
latent_connectivities_key: str = "connectivities",
layer_ratio: float = 1.0,
n_iterations: int = -1,
use_weights: bool | tuple[bool, bool] = True,
use_rep: str | None = None,
inplace: bool = True,
*,
table_key: str | None = None,
rng: SeedLike | RNGLike | None = None,
) -> AnnData | None:
"""
Calculate niches (spatial clusters) based on a user-defined method in 'flavor'.
The resulting niche labels with be stored in 'adata.obs'.
.. deprecated:: 1.8.4
``calculate_niche`` is deprecated and will be removed in squidpy
v1.9.0. Use one of the flavor-specific functions instead:
- :func:`calculate_niche_neighborhood`
- :func:`calculate_niche_utag`
- :func:`calculate_niche_cellcharter`
- :func:`calculate_niche_spatialleiden`
See Also
--------
calculate_niche_neighborhood : Neighborhood-profile flavor with an explicit signature.
calculate_niche_utag : UTAG flavor with an explicit signature.
calculate_niche_cellcharter : CellCharter flavor with an explicit signature.
calculate_niche_spatialleiden : SpatialLeiden flavor with an explicit signature.
Parameters
----------
%(adata)s
flavor
Method to use for niche calculation. Available options are:
- `'neighborhood'` - cluster the neighborhood profile.
- `'utag'` - use utag algorithm (matrix multiplication).
- `'spatialleiden'` - cluster spatially resolved omics data using Multiplex Leiden.
- `'cellcharter'` - a simplified version of CellCharter's approach, using PCA for dimensionality reduction. An arbitrary embedding can be used instead of PCA by setting the `use_rep` parameter which will try to find the embedding in `adata.obsm`.
library_key
Deprecated, and removed with this function in v1.9.0; no flavor function takes it. Each
library is fitted on its own and its labels are prefixed ``lib=<id>_``, so a niche in one
library is unrelated to the same-numbered niche in another.
Either way, build the graphs per library with :func:`~squidpy.gr.spatial_neighbors`.
For niches shared across libraries, leave this unset. For niches per library, call a
flavor function on each library's slice, which is what this does::
adata.obs["niche"] = "not_a_niche"
for lib in adata.obs["library"].unique():
sub = adata[adata.obs["library"] == lib].copy()
sq.gr.calculate_niche_utag(sub, resolutions=0.5)
adata.obs.loc[sub.obs_names, "niche"] = f"lib={lib}_" + sub.obs["utag_niche_res=0.5"].astype(str)
%(table_key)s
mask
Boolean array to filter cells which won't get assigned to a niche. Spelled
``cluster_mask`` on the three flavors that build an embedding, and
`'spatialleiden'` raises rather than accepting one it cannot honour.
Note that if you want to exclude these cells during neighborhood calculation already, you should subset your AnnData table before running 'sq.gr.spatial_neigbors'.
Mask can look like the following. Here, the index values would correspond to adata.obs.index.
The entries that are False are the ones ignored.
mask = Series([False, False, True], index = ["a", "b", "c"])
groups
Groups based on which to calculate neighborhood profile (E.g. columns of cell type annotations in adata.obs).
Required if flavor == `'neighborhood'`.
n_neighbors
Number of neighbors to use for 'scanpy.pp.neighbors' before clustering using leiden algorithm.
Required if flavor == `'neighborhood'` or flavor == `'utag'`.
resolutions
List of resolutions to use for leiden clustering.
In the case of spatialleiden you can pass a tuple. Resolution for the latent space and spatial layer, respectively. A single float applies to both layers.
Required if flavor == `'neighborhood'` or flavor == `'utag'`.
Optional if flavor == `'spatialleiden'`.
min_niche_size
Minimum required size of a niche. Niches with fewer cells will be labeled as 'not_a_niche'.
Optional if flavor == `'neighborhood'`.
scale
If 'True', compute z-scores of neighborhood profiles.
Optional if flavor == `'neighborhood'`.
abs_nhood
If 'True', calculate niches based on absolute neighborhood profile.
Optional if flavor == `'neighborhood'`.
distance
n-hop neighbor adjacency matrices to use e.g. [1,2,3] for 1-hop,2-hop,3-hop neighbors respectively or "5" for 1-hop,...,5-hop neighbors. 0 (self) is always included.
Required if flavor == `'cellcharter'`.
Optional if flavor == `'neighborhood'`.
n_hop_weights
How to weight subsequent n-hop adjacency matrices. E.g. [1, 0.5, 0.25] for weights of 1-hop, 2-hop, 3-hop adjacency matrices respectively.
Optional if flavor == `'neighborhood'` and `distance` > 1.
aggregation
How to aggregate count matrices. Either 'mean' or 'variance'.
Required if flavor == `'cellcharter'`.
n_components
Number of components to use for GMM.
Required if flavor == `'cellcharter'`.
%(rng)s
Optional if flavor == `'cellcharter'` or flavor == `'spatialleiden'`.
spatial_connectivities_key
Key in `adata.obsp` where spatial connectivities are stored.
Required if flavor == `'spatialleiden'`.
latent_connectivities_key
Key in `adata.obsp` where gene expression connectivities are stored.
Required if flavor == `'spatialleiden'`.
layer_ratio
The ratio of the weighting of the layers; latent space vs spatial. A higher ratio will increase relevance of the spatial neighbors and lead to more spatially homogeneous clusters.
Optional if flavor == `'spatialleiden'`.
n_iterations
Number of iterations to run the Leiden algorithm. If the number is negative it runs until convergence.
Optional if flavor == `'spatialleiden'`.
use_weights
Whether to use weights for the edges for latent space and spatial neighbors, respectively. A single bool applies to both layers.
Optional if flavor == `'spatialleiden'`.
use_rep
Key in `adata.obsm` where the embedding is stored. If provided, this embedding will be used instead of PCA for dimensionality reduction.
Optional if flavor == `'cellcharter'`.
inplace
If 'True', perform the operation in place.
If 'False', return a new AnnData object with the niche labels.
"""
warnings.warn(
"Calling `calculate_niche` is deprecated and will be removed in squidpy "
"v1.9.0. Use `calculate_niche_neighborhood`, `calculate_niche_utag`, "
"`calculate_niche_cellcharter`, or `calculate_niche_spatialleiden` instead.",
FutureWarning,
# `calculate_niche` is wrapped by `@deprecated_randomness_param`, so 2 lands in
# squidpy/_utils.py rather than on the caller the deprecation is addressed to
stacklevel=3,
)
flavor = normalize_choice(flavor, ("neighborhood", "utag", "cellcharter", "spatialleiden"), name="flavor")
# cellcharter-only defaults stay guarded: filling them for other flavors would trip
# the "not used for flavor" warning in _check_unnecessary_args
if mask is not None and flavor == "spatialleiden":
raise ValueError(
"'mask' keeps masked observations out of the niche fit, which 'spatialleiden' cannot "
"do: it clusters the graphs themselves, so an observation either takes part or loses "
"its edges. It is 'cluster_mask' on the other three flavors."
)
if flavor == "cellcharter":
if aggregation is None:
aggregation = "mean"
if n_components is None:
n_components = 10
if distance is None:
distance = 3 if flavor == "cellcharter" else 1
_validate_niche_args(
data,
flavor=flavor,
table_key=table_key,
groups=groups,
n_neighbors=n_neighbors,
resolutions=resolutions,
min_niche_size=min_niche_size,
scale=scale,
abs_nhood=abs_nhood,
distance=distance,
n_hop_weights=n_hop_weights,
aggregation=aggregation,
n_components=n_components,
rng=rng,
spatial_connectivities_key=spatial_connectivities_key,
latent_connectivities_key=latent_connectivities_key,
layer_ratio=layer_ratio,
n_iterations=n_iterations,
use_weights=use_weights,
use_rep=use_rep,
inplace=inplace,
)
if resolutions is None:
resolutions = [0.5]
def run(target: AnnData | SpatialData, *, copy: bool, target_key: str | None) -> AnnData | None:
if flavor == "neighborhood":
return calculate_niche_neighborhood(
target,
groups=groups,
resolutions=resolutions,
n_neighbors=n_neighbors,
spatial_connectivities_key=spatial_connectivities_key,
scale=scale,
distance=distance,
abs_nhood=abs_nhood,
n_hop_weights=n_hop_weights,
embedding_key_added="niche_embedding",
min_niche_size=min_niche_size,
cluster_mask=mask,
copy=copy,
table_key=target_key,
n_iterations=n_iterations,
rng=rng,
)
elif flavor == "utag":
return calculate_niche_utag(
target,
resolutions=resolutions,
n_neighbors=n_neighbors,
use_layer=None,
use_rep=use_rep,
spatial_connectivities_key=spatial_connectivities_key,
embedding_key_added="niche_embedding",
cluster_mask=mask,
min_niche_size=min_niche_size,
copy=copy,
table_key=target_key,
n_iterations=n_iterations,
rng=rng,
)
elif flavor == "cellcharter":
return calculate_niche_cellcharter(
target,
distance=distance,
aggregation=aggregation,
rng=rng,
spatial_connectivities_key=spatial_connectivities_key,
n_clusters=n_components,
use_rep=use_rep,
embedding_key_added="niche_embedding",
cluster_mask=mask,
min_niche_size=min_niche_size,
copy=copy,
table_key=target_key,
)
elif flavor == "spatialleiden":
return calculate_niche_spatialleiden(
target,
resolutions=resolutions,
latent_connectivities_key=latent_connectivities_key,
spatial_connectivities_key=spatial_connectivities_key,
layer_ratio=layer_ratio,
n_iterations=n_iterations,
use_weights=use_weights,
rng=rng,
min_niche_size=min_niche_size,
copy=copy,
table_key=target_key,
)
return None
if library_key is None:
return run(data, copy=not inplace, target_key=table_key)
warnings.warn(
"'library_key' is deprecated and will be removed with `calculate_niche` in squidpy v1.9.0. "
"It fits a separate model per library, so niche labels are not shared between libraries. "
"Either way, build the graphs per library with `spatial_neighbors(..., library_key=...)`. "
"For niches shared across libraries, leave `library_key` unset. For niches per library, "
"call a flavor function on each library's slice, e.g. "
"`calculate_niche_utag(adata[adata.obs['library'] == lib].copy(), ...)`, and copy the "
"labels back; the `calculate_niche` docstring shows how.",
FutureWarning,
stacklevel=3, # the same frame as the deprecation above
)
if flavor == "cellcharter":
columns = ["cellcharter_niche"]
else:
stem = {"neighborhood": "nhood_niche", "utag": "utag_niche", "spatialleiden": "spatialleiden"}[flavor]
columns = [f"{stem}_res={res}" for res in _resolution_values(resolutions, pairs_ok=flavor == "spatialleiden")]
return _niches_per_library(
data,
library_key=library_key,
columns=columns,
table_key=table_key,
copy=not inplace,
run=lambda lib_adata: run(lib_adata, copy=False, target_key=None),
)
[docs]
@d.dedent
def calculate_niche_neighborhood(
data: AnnData | SpatialData,
*,
groups: str,
resolutions: float | list[float],
n_neighbors: int = 15,
spatial_connectivities_key: str = "spatial_connectivities",
scale: bool = True,
distance: int = 1,
abs_nhood: bool = False,
n_hop_weights: list[float] | None = None,
embedding_key_added: str = "niche_embedding",
key_added: str = "nhood_niche",
min_niche_size: int | None = None,
cluster_mask: pd.Series | None = None,
copy: bool = False,
table_key: str | None = None,
flavor: Literal["igraph", "leidenalg"] = "igraph",
n_iterations: int = -1,
rng: SeedLike | RNGLike | None = None,
) -> AnnData | None:
"""Compute spatial niches from local cell-type composition.
Follows monkeybread's
https://github.com/immunitastx/monkeybread/blob/main/src/monkeybread/calc/_neighborhood_profile.py
This method represents every observation by a **neighborhood composition
profile**: a vector describing the cell-type labels observed in its local
spatial neighborhood. Observations with similar surrounding cell-type
compositions are then grouped into niches using Leiden clustering.
A spatial connectivity graph must already be available in
``adata.obsp[spatial_connectivities_key]``. The graph defines which
observations are spatial neighbors; this function does not construct the
graph itself.
For each observation ``i``, the method:
1. Retrieves observations reachable from ``i`` in the spatial graph up to
``distance`` hops away.
2. Counts the values of ``groups`` among those neighboring observations.
3. Optionally combines profiles from different graph-hop distances using
``n_hop_weights``.
4. Uses either raw counts or normalized cell-type proportions as the
neighborhood profile.
5. Optionally z-scores the resulting profile across observations (scale
argument).
6. Constructs a k-nearest-neighbor graph from the profile embedding and
applies Leiden clustering at each requested resolution.
Thus, a niche is defined by a recurring **local cellular composition**,
rather than by the expression profile of an individual observation. For
example, cells surrounded by many immune cells and fibroblasts may be
assigned to one niche even when those cells themselves have different
expression profiles or cell-type labels.
Parameters
----------
%(adata)s
groups
Column in ``adata.obs`` containing categorical labels used to define
neighborhood composition, such as cell types, cell states, clusters,
or anatomical annotations.
resolutions
Resolution parameter(s) for Leiden clustering. A single value produces
one niche annotation. Supplying multiple values performs Leiden
clustering separately for each resolution and adds one niche column per
resolution to ``adata.obs``.
n_neighbors
Number of nearest neighbors used to construct the k-nearest-neighbor
graph on the neighborhood composition embedding before Leiden
clustering.
%(niche_spatial_conn_key)s
scale
Whether to z-score each neighborhood-profile feature across
observations before constructing the clustering graph.
distance
Maximum number of graph hops used to construct each neighborhood
profile. ``distance=1`` uses direct spatial neighbors. Larger values
incorporate increasingly distal observations in the spatial graph.
abs_nhood
Whether to use absolute group counts in the neighborhood profile.
If ``False`` (the default), counts are normalized to proportions, so
each profile captures relative neighborhood composition and is less
sensitive to differences in neighborhood size.
If ``True``, raw counts are retained, so both composition and the
total number of reachable neighbors can influence the embedding.
n_hop_weights
Optional weights used when combining contributions from successive
graph-hop distances. If provided, the weights determine the relative
contribution of direct and higher-order neighbors to the final
neighborhood profile. If not provided, equal weights are used.
%(niche_cluster_mask)s
%(niche_key_added_stem)s
%(niche_common_params)s
%(table_key)s
%(niche_leiden_params)s
Returns
-------
If ``copy=True``, returns a copy of ``adata`` with the neighborhood profile
stored in ``.obsm[embedding_key_added]`` and niche
assignments added to ``.obs``. Otherwise, modifies ``adata`` in place and returns ``None``.
Notes
-----
This approach is most appropriate when niches are expected to differ
primarily in local **cellular composition**. In contrast,
:func:`calculate_niche_utag` and :func:`calculate_niche_cellcharter`
derive niche embeddings from spatially aggregated molecular or latent
features rather than from categorical group frequencies.
"""
embedder = partial(
_nhood_profile_embedding,
groups=groups,
spatial_connectivities_key=spatial_connectivities_key,
scale=scale,
distance=distance,
abs_nhood=abs_nhood,
n_hop_weights=n_hop_weights,
)
clusterers = _leiden_clusterers(
base_colname=key_added,
resolutions=resolutions,
n_neighbors=n_neighbors,
flavor=flavor,
n_iterations=n_iterations,
)
return calculate_niche_custom(
data,
embedder=embedder,
clusterers=clusterers,
rng=rng,
embedding_key_added=embedding_key_added,
min_niche_size=min_niche_size,
cluster_mask=cluster_mask,
copy=copy,
table_key=table_key,
)
[docs]
@d.dedent
def calculate_niche_utag(
data: AnnData | SpatialData,
*,
resolutions: float | list[float],
n_neighbors: int = 15,
use_layer: str | None = None,
spatial_connectivities_key: str = "spatial_connectivities",
embedding_key_added: str = "niche_embedding",
use_rep: str | None = None,
key_added: str = "utag_niche",
min_niche_size: int | None = None,
cluster_mask: pd.Series | None = None,
copy: bool = False,
table_key: str | None = None,
flavor: Literal["igraph", "leidenalg"] = "igraph",
n_iterations: int = -1,
rng: SeedLike | RNGLike | None = None,
) -> AnnData | None:
"""Compute spatial niches from UTAG-style feature aggregation.
UTAG :cite:`kim2022`, adapted from
https://github.com/ElementoLab/utag/blob/main/utag/segmentation.py
This method computes a spatially aggregated feature representation for each
observation and clusters that representation with Leiden. The resulting
niches group observations that occur in similar local molecular
environments.
A spatial connectivity graph must already be available in
``adata.obsp[spatial_connectivities_key]``. The graph determines how
features are propagated or aggregated across spatially neighboring
observations; this function does not construct the graph itself.
The method proceeds as follows:
1. Selects an input feature matrix from ``adata.X`` or from
``adata.layers[use_layer]``.
2. Performs a normalized (by number of cell-neighbors) aggregation of
features over the spatial connectivity graph, producing a new feature
matrix in which each observation reflects information from its local
spatial neighborhood.
3. Reduces that matrix with PCA; the scores are the niche embedding.
4. Constructs a k-nearest-neighbor graph in that embedding space.
5. Applies Leiden clustering at each requested resolution.
If the input contains gene expression values, the embedding describes
local expression programs rather than merely the categorical composition
of neighboring cells.
This differs from :func:`calculate_niche_neighborhood`, which uses counts
or proportions of a categorical ``groups`` annotation. UTAG-style
aggregation can identify niches that have similar local expression
patterns even when their neighborhoods contain different annotated cell
types, or when cell-type labels are unavailable.
Parameters
----------
%(adata)s
resolutions
Resolution parameter(s) for Leiden clustering. A single value produces
one niche annotation. Supplying multiple values runs Leiden clustering
independently at each resolution and adds one niche column per
resolution to ``adata.obs``.
n_neighbors
Number of nearest neighbors used to construct the k-nearest-neighbor
graph on the spatially aggregated embedding before Leiden clustering.
use_layer
Key in ``adata.layers`` containing the feature matrix to aggregate. If
``None``, uses ``adata.X``.
Typically, this should contain a normalized expression matrix or
another observation-by-feature representation appropriate for local
aggregation. The selected matrix determines what biological signal is
used to define niches.
%(niche_spatial_conn_key)s
%(niche_cluster_mask)s
use_rep
Key in :attr:`anndata.AnnData.obsm` holding the representation to aggregate over each
neighborhood, or ``'X'`` for :attr:`~anndata.AnnData.X`. Taken as already reduced, so the
PCA of the aggregate is skipped. Rejected together with ``use_layer``.
%(niche_key_added_stem)s
%(niche_common_params)s
%(table_key)s
%(niche_leiden_params)s
Returns
-------
If ``copy=True``, returns a copy of ``adata`` with the aggregated features in
``.obsm[embedding_key_added]``, PCA-reduced unless ``use_rep``
was given, and niche assignments added to ``.obs``. Otherwise, modifies ``adata`` in place
and returns ``None``.
"""
embedder = partial(
_utag_embedding,
spatial_connectivities_key=spatial_connectivities_key,
use_layer=use_layer,
use_rep=use_rep,
)
clusterers = _leiden_clusterers(
base_colname=key_added,
resolutions=resolutions,
n_neighbors=n_neighbors,
flavor=flavor,
n_iterations=n_iterations,
)
return calculate_niche_custom(
data,
embedder=embedder,
clusterers=clusterers,
rng=rng,
embedding_key_added=embedding_key_added,
min_niche_size=min_niche_size,
cluster_mask=cluster_mask,
copy=copy,
table_key=table_key,
)
[docs]
@d.dedent
def calculate_niche_cellcharter(
data: AnnData | SpatialData,
*,
distance: int = 3,
aggregation: str = "mean",
rng: SeedLike | RNGLike | None = None,
spatial_connectivities_key: str = "spatial_connectivities",
n_clusters: int = 10,
n_pca_components: int | None = None,
n_jobs: int | None = None,
use_rep: str | None = None,
embedding_key_added: str = "niche_embedding",
key_added: str = "cellcharter_niche",
min_niche_size: int | None = None,
cluster_mask: pd.Series | None = None,
copy: bool = False,
table_key: str | None = None,
) -> AnnData | None:
"""Compute spatial niches using a CellCharter-style embedding and GMM :cite:`varrone2023`.
CellCharter recommends a dimensionality-reduced embedding such as scVI, passed as
``use_rep``; PCA of ``adata.X`` is the fallback when it is not given. The mixture
model is scikit-learn's, not CellCharter's torchgmm, so partitions will not match theirs.
This method identifies niches by clustering an embedding that represents
each observation together with information from its surrounding spatial
neighborhood. Unlike :func:`calculate_niche_neighborhood`, which builds
an embedding from categorical cell-type composition, this approach uses a
continuous feature representation and a Gaussian mixture model (GMM) for
clustering.
A spatial connectivity graph must already be present in
``adata.obsp[spatial_connectivities_key]``. This function does not construct
the graph itself.
The method:
1. Takes a reduced representation of every observation: ``adata.obsm[use_rep]``
if given, otherwise the first ``n_pca_components`` principal components of ``adata.X``,
restricted to ``adata.var["highly_variable"]`` when that column is present.
2. Aggregates that representation over each disjoint hop ring of the spatial
graph, from direct neighbors through ``distance`` graph hops, according to
``aggregation``.
3. Concatenates the observation's own representation with every ring's aggregate.
4. Fits a Gaussian mixture model with ``n_clusters`` mixture components.
5. Uses the GMM component assignments as niche labels.
Consequently, each niche corresponds to a probabilistic cluster in a
feature space that encodes both an observation's features and its broader
spatial context. Increasing ``distance`` allows the embedding to reflect
larger tissue-scale neighborhoods, whereas smaller values emphasize local
microenvironments.
Parameters
----------
%(adata)s
distance
Maximum number of graph hops included when constructing the
CellCharter-style spatial embedding. ``distance=1`` emphasizes direct
neighbors; larger values incorporate progressively more distal
observations in the spatial graph.
aggregation
Aggregation statistic used to summarize features across spatial
neighborhoods. Typical options include ``"mean"`` and ``"variance"``.
``"mean"`` emphasizes the average local feature state, such as the
average local expression program. ``"variance"`` emphasizes local
heterogeneity in the feature representation.
%(rng)s
Seeds the Gaussian mixture clustering step.
%(niche_spatial_conn_key)s
n_clusters
Number of Gaussian mixture components, and therefore the number of niche
labels produced per library or dataset.
n_pca_components
Number of principal components of ``adata.X`` aggregated over the hop rings. ``None``
uses 10, the latent width scVI defaults to, or one fewer than the smallest dimension of
``adata.X`` when that is narrower. Named for the PCA because
:class:`~sklearn.mixture.GaussianMixture` spells its cluster count ``n_components``
too; here that is ``n_clusters``. Rejected together with ``use_rep``, which supplies an
already reduced embedding and so skips the PCA.
%(n_jobs_threads)s
use_rep
Key in :attr:`anndata.AnnData.obsm` holding a reduced representation, such as an scVI
latent, or ``'X'`` for :attr:`~anndata.AnnData.X`. Aggregated over the hop rings in place
of the PCA of ``adata.X``.
%(niche_cluster_mask)s
key_added
Name of the :attr:`anndata.AnnData.obs` column the labels are written to.
%(niche_common_params)s
%(table_key)s
Returns
-------
If ``copy=True``, returns a copy of ``adata`` with the embedding stored in
``.obsm[embedding_key_added]`` and GMM-based niche
assignments added to ``.obs``. Otherwise, modifies ``adata`` in place and returns ``None``.
"""
if use_rep is None:
logg.warning(
"CellCharter recommends to use a dimensionality reduced embedding of the data, e.g. a scVI embedding. Since 'use_rep' is not provided, PCA will be used as proxy - performance may be suboptimal."
)
elif n_pca_components is not None:
raise ValueError("'n_pca_components' sizes the PCA, which 'use_rep' replaces; pass one or the other")
embedder = partial(
_nhop_pca_embedding,
distance=distance,
aggregation=aggregation,
spatial_connectivities_key=spatial_connectivities_key,
use_rep=use_rep,
n_pca_components=n_pca_components,
n_jobs=n_jobs,
)
# `GaussianMixture` is a `Clusterer` as it stands, so this flavor needs no wrapper
clusterers = {key_added: GaussianMixture(n_components=n_clusters)}
return calculate_niche_custom(
data,
embedder=embedder,
clusterers=clusterers,
rng=rng,
embedding_key_added=embedding_key_added,
min_niche_size=min_niche_size,
cluster_mask=cluster_mask,
copy=copy,
table_key=table_key,
)
[docs]
@d.dedent
def calculate_niche_spatialleiden(
data: AnnData | SpatialData,
*,
resolutions: float | tuple[float, float] | list[float | tuple[float, float]],
latent_connectivities_key: str = "connectivities",
spatial_connectivities_key: str = "spatial_connectivities",
layer_ratio: float = 1.0,
n_iterations: int = -1,
use_weights: bool | tuple[bool, bool] = True,
rng: SeedLike | RNGLike | None = None,
key_added: str = "spatialleiden",
min_niche_size: int | None = None,
copy: bool = False,
table_key: str | None = None,
) -> AnnData | None:
"""Compute niche assignments using the SpatialLeiden algorithm.
This is a wrapper around SpatialLeiden :cite:`muellerboetticher2025`, which takes
:class:`~anndata.AnnData` as input and works with two layers; one latent space and one
spatial layer. Adapted from https://github.com/HiDiHlabs/SpatialLeiden/.
Parameters
----------
%(adata)s
latent_connectivities_key
Key in ``adata.obsp`` containing the latent-space connectivity matrix.
%(niche_spatial_conn_key)s
resolutions
Resolution parameter(s) for the Leiden optimization. Can be a single
float or a list of floats.
layer_ratio
Relative weight assigned to the latent and spatial layers.
n_iterations
Number of optimization iterations used by SpatialLeiden.
use_weights
Whether to use edge weights during clustering.
%(rng)s
Each resolution is clustered with an independent rng derived from it.
%(niche_min_niche_size)s
%(niche_key_added_stem)s
%(copy)s
%(table_key)s
Returns
-------
If ``copy = True``, returns a copy of ``adata`` with niche annotations added to ``.obs``.
Otherwise, modifies ``adata`` in place and returns ``None``.
"""
resolution_list = _resolution_values(resolutions, pairs_ok=True)
rng = np.random.default_rng(rng)
def run(adata: AnnData) -> None:
_spatialleiden_once(
adata,
key_added=key_added,
resolution_list=resolution_list,
rng=rng,
latent_connectivities_key=latent_connectivities_key,
spatial_connectivities_key=spatial_connectivities_key,
layer_ratio=layer_ratio,
n_iterations=n_iterations,
use_weights=use_weights,
min_niche_size=min_niche_size,
)
return _on_table(data, table_key=table_key, copy=copy, work=run)
@d.dedent
def calculate_niche_custom(
data: AnnData | SpatialData,
*,
embedder: NicheEmbedder,
clusterers: Mapping[str, Clusterer],
rng: SeedLike | RNGLike | None = None,
embedding_key_added: str = "niche_embedding",
min_niche_size: int | None = None,
cluster_mask: pd.Series | None = None,
copy: bool = False,
table_key: str | None = None,
) -> AnnData | None:
"""Compute niche assignments using user-defined embedding, clustering, and postprocessing.
This function provides a flexible pipeline where embedding, clustering,
and postprocessing are decoupled and customizable.
Parameters
----------
%(adata)s
embedder
Any ``(AnnData) -> Array`` callable returning one row per observation.
clusterers
The clusterer labelling each ``adata.obs`` column, keyed by name.
rng
Seeds every fit.
%(niche_common_params)s
%(table_key)s
Returns
-------
If ``copy = True``, returns a copy of ``adata`` with niche annotations added to ``.obs``.
Otherwise, modifies ``adata`` in place and returns ``None``.
Notes
-----
One embedding and one clustering over everything, so the labels mean the same thing for
every observation. Per-library fitting lives in :func:`calculate_niche_spatialleiden`.
See Also
--------
calculate_niche_neighborhood : Convenience wrapper for neighborhood flavor niche analysis.
calculate_niche_utag : Convenience wrapper for utag flavor niche analysis.
calculate_niche_cellcharter : Convenience wrapper for cellcharter flavor niche analysis.
calculate_niche_spatialleiden : Convenience wrapper for spatialleiden flavor niche analysis.
"""
# AnnData accepts `obsm[None]` and only fails at `write_h5ad`
if not isinstance(embedding_key_added, str) or len(embedding_key_added) == 0:
raise ValueError(f"'embedding_key_added' must be a non-empty string, got {embedding_key_added!r}")
rng = np.random.default_rng(rng)
def run(adata: AnnData) -> None:
keep = None
if cluster_mask is not None:
if not is_bool_dtype(cluster_mask):
raise TypeError(f"'cluster_mask' must be a boolean Series, got dtype '{cluster_mask.dtype}'")
if not cluster_mask.index.isin(adata.obs_names).any():
raise ValueError("'cluster_mask' shares no index value with 'adata.obs', so it masks nothing")
# observations the mask omits are kept, as the documented three-entry example reads
keep = cluster_mask.reindex(adata.obs_names, fill_value=True).to_numpy(dtype=bool)
if not keep.any():
raise ValueError("'cluster_mask' excludes every observation, so no niche could be assigned")
# called here, not via a helper: another frame would shift the warnings' stacklevel
embedding = embedder(adata)
adata.obsm[embedding_key_added] = embedding
_fit_clusterers(
adata, embedding=embedding, clusterers=clusterers, rng=rng, keep=keep, min_niche_size=min_niche_size
)
return _on_table(data, table_key=table_key, copy=copy, work=run)
def _validate_niche_args( # noqa: PLR0917, deprecated and removed in v1.9.0
data: AnnData | SpatialData,
*,
flavor: Literal["neighborhood", "utag", "cellcharter", "spatialleiden"],
table_key: str | None,
groups: str | None,
n_neighbors: int | None,
resolutions: float | tuple[float, float] | list[float | tuple[float, float]] | None,
min_niche_size: int | None,
scale: bool,
abs_nhood: bool,
distance: int | None,
n_hop_weights: list[float] | None,
aggregation: str | None,
n_components: int | None,
# the one internal that sees a raw `rng`: it reports on what the caller passed, and
# `None` must stay `None` here so the "unused for this flavor" check can spot it
rng: SeedLike | RNGLike | None,
spatial_connectivities_key: str,
latent_connectivities_key: str,
layer_ratio: float,
n_iterations: int,
use_weights: bool | tuple[bool, bool],
use_rep: str | None,
inplace: bool,
) -> None:
"""
Validate whether necessary arguments are provided for a given niche flavor.
Also warns whether unnecessary optional arguments are supplied.
Raises
------
ValueError
If required arguments for the specified flavor are missing or have incorrect values.
TypeError
If arguments are of incorrect type.
"""
assert_isinstance(data, (AnnData, SpatialData), name="data")
if isinstance(data, SpatialData) and table_key is None:
raise TypeError("missing required keyword-only argument: 'table_key'")
if n_neighbors is not None:
assert_isinstance(n_neighbors, int, name="n_neighbors")
if n_hop_weights is not None:
assert_isinstance(n_hop_weights, list, name="n_hop_weights")
assert_isinstance(scale, bool, name="scale")
assert_isinstance(abs_nhood, bool, name="abs_nhood")
# Define parameters used by each flavor
flavor_param_specs = {
"neighborhood": {
"required": ["groups", "n_neighbors", "resolutions", "spatial_connectivities_key"],
"optional": [
"scale",
"abs_nhood",
"distance",
"n_hop_weights",
"rng",
"n_iterations",
],
"unused": [
"aggregation",
"n_components",
"latent_connectivities_key",
"layer_ratio",
"use_weights",
"use_rep",
],
},
"utag": {
"required": ["n_neighbors", "resolutions", "spatial_connectivities_key"],
"optional": ["rng", "n_iterations", "use_rep"],
"unused": [
"groups",
"scale",
"abs_nhood",
"distance",
"n_hop_weights",
"aggregation",
"n_components",
"latent_connectivities_key",
"layer_ratio",
"use_weights",
],
},
"cellcharter": {
"required": ["distance", "aggregation", "spatial_connectivities_key"],
# `rng` is optional: `None` is a valid value meaning "draw from OS entropy"
"optional": ["n_components", "use_rep", "rng"],
"unused": [
"groups",
"scale",
"abs_nhood",
"n_neighbors",
"resolutions",
"n_hop_weights",
"latent_connectivities_key",
"layer_ratio",
"n_iterations",
"use_weights",
],
},
"spatialleiden": {
"required": ["latent_connectivities_key", "spatial_connectivities_key"],
"optional": [
"resolutions",
"layer_ratio",
"n_iterations",
"use_weights",
"rng",
],
"unused": ["groups", "scale", "abs_nhood", "n_neighbors", "n_hop_weights", "use_rep"],
},
}
for param_name in flavor_param_specs[flavor]["required"]:
param_value = locals()[param_name]
if param_value is None:
raise ValueError(f"'{param_name}' is required for flavor '{flavor}'")
_check_unnecessary_args(
flavor,
{
"groups": groups,
"n_neighbors": n_neighbors,
"resolutions": resolutions,
"min_niche_size": min_niche_size,
"scale": scale,
"abs_nhood": abs_nhood,
"distance": distance,
"n_hop_weights": n_hop_weights,
"aggregation": aggregation,
"n_components": n_components,
"rng": rng,
"use_rep": use_rep,
},
flavor_param_specs[flavor],
)
# Flavor-specific validations
if flavor == "neighborhood":
assert_isinstance(groups, str, name="groups")
if min_niche_size is not None:
assert_isinstance(min_niche_size, int, name="min_niche_size")
if distance is not None and isinstance(distance, int) and distance < 1:
raise ValueError(f"'distance' must be at least 1, got {distance}")
elif flavor == "cellcharter":
if distance is not None:
assert_isinstance(distance, int, name="distance")
if distance is not None and distance < 1:
raise ValueError(f"'distance' must be at least 1, got {distance}")
if aggregation is not None:
assert_isinstance(aggregation, str, name="aggregation")
normalize_choice(aggregation, ["mean", "variance"], name="aggregation")
assert_isinstance(n_components, int, name="n_components")
if n_components < 1:
raise ValueError(f"'n_components' must be at least 1, got {n_components}")
if use_rep is not None:
assert_isinstance(use_rep, str, name="use_rep")
# for mypy
if resolutions is None:
resolutions = [0.0]
elif flavor == "spatialleiden":
assert_isinstance(latent_connectivities_key, str, name="latent_connectivities_key")
assert_isinstance(spatial_connectivities_key, str, name="spatial_connectivities_key")
assert_isinstance(layer_ratio, (float, int), name="layer_ratio")
assert_isinstance(n_iterations, int, name="n_iterations")
if not (
isinstance(use_weights, bool)
or (
isinstance(use_weights, tuple)
and len(use_weights) == 2
and all(isinstance(x, bool) for x in use_weights)
)
):
raise TypeError(f"'use_weights' must be a bool or a tuple of two bools, got {use_weights!r}")
if resolutions is None:
resolutions = [1.0]
assert_isinstance(inplace, bool, name="inplace")
def _check_unnecessary_args(flavor: str, param_dict: dict[str, Any], param_specs: dict[str, Any]) -> None:
"""
Check for unnecessary arguments that were provided but not used by the given flavor.
Parameters
----------
flavor
The flavor being used ('neighborhood', 'utag', 'cellcharter', or 'spatialleiden')
param_dict
Dictionary of parameter names to their values
param_specs
Dictionary with 'required', 'optional', and 'unused' parameter lists for the flavor
"""
unnecessary_args = []
for param_name in param_specs["unused"]:
param_value = param_dict.get(param_name)
# Special handling for parameters whose default is not None
if param_name == "scale" and param_value is True:
continue
if param_name == "abs_nhood" and param_value is False:
continue
if param_value is not None:
unnecessary_args.append(param_name)
if unnecessary_args:
logg.warning(
f"Parameters {', '.join([f'{arg}' for arg in unnecessary_args])} are not used for flavor '{flavor}'.",
)
############
### embedder classes
############
NicheEmbedder = Callable[[AnnData], Array]
def _has_edge_weights(adata: AnnData, *, key: str) -> bool:
"""True when the graph carries values other than 0 and 1."""
weights = adata.obsp[key].data
return bool(weights.size) and not np.array_equal(weights, weights.astype(bool))
def _nhood_profile_embedding(
adata: AnnData,
*,
groups: str,
spatial_connectivities_key: str,
scale: bool,
distance: int,
abs_nhood: bool,
n_hop_weights: list[float] | None,
) -> Array:
"""Neighborhood composition: how frequent each category is around each observation."""
if distance < 1:
raise ValueError(f"'distance' must be >= 1, got {distance}")
if n_hop_weights is not None and len(n_hop_weights) != distance:
raise ValueError(
f"'n_hop_weights' has {len(n_hop_weights)} value(s) but 'distance' is {distance}. "
f"Earlier versions padded a short list with its last value; pass all {distance}."
)
if _has_edge_weights(adata, key=spatial_connectivities_key):
warnings.warn(
f"'{spatial_connectivities_key}' carries non-binary edge weights. They weight hop 1, "
"so the profile is the share of connectivity reaching each category rather than the "
"share of neighboring cells. Set them to 1 for a plain composition. Hops past the "
"first are unweighted either way, since only edges carry weights.",
UserWarning,
# `_on_table`, the pipeline's `run` and the embedder sit in between. Still one short
# through `calculate_niche`.
stacklevel=6,
)
profile = nhood_aggregate(
adata,
groups=groups,
connectivity_key=spatial_connectivities_key,
hops=range(1, distance + 1),
hop_weights=n_hop_weights,
aggregation="sum" if abs_nhood else "mean",
)
# one column per category, and `sc.pp.scale` densifies anyway
profile = to_dense(profile)
# monkeybread counts per cell with a `Counter`; this is the same profile as a one-hot
# product. Scaling follows theirs, see
# https://monkeybread.readthedocs.io/en/latest/notebooks/tutorial.html#niche-analysis
return sc.pp.scale(profile, zero_center=True) if scale else profile
def _utag_embedding(
adata: AnnData, *, spatial_connectivities_key: str, use_layer: str | None, use_rep: str | None
) -> Array:
"""Each observation inherits the mean features of its immediate neighbors."""
aggregated = nhood_aggregate(
adata, layer=use_layer, use_rep=use_rep, connectivity_key=spatial_connectivities_key, hops=(1,)
)
# already reduced, and on one basis across libraries. This PCA would refit it per library.
return to_dense(aggregated) if use_rep is not None else sc.pp.pca(aggregated)
def _nhop_pca_embedding(
adata: AnnData,
*,
distance: int,
aggregation: str,
spatial_connectivities_key: str,
use_rep: str | None = None,
n_pca_components: int | None = None,
n_jobs: int | None = None,
) -> Array:
"""Reduced features and their ring aggregates, concatenated as in CellCharter."""
aggregation = normalize_choice(aggregation, ("mean", "variance"), name="aggregation")
if distance < 1:
raise ValueError(f"'distance' must be >= 1, got {distance}")
hops = range(distance + 1)
_assert_hop_request(adata, connectivity_key=spatial_connectivities_key, hops=hops)
if _has_edge_weights(adata, key=spatial_connectivities_key):
warnings.warn(
f"'{spatial_connectivities_key}' carries non-binary edge weights, which this flavor "
"ignores entirely: the hop rings are boolean, as in CellCharter. The 'neighborhood' "
"flavor weights hop 1 by them.",
UserWarning,
# `_on_table`, the pipeline's `run` and the embedder sit in between. Still one short
# through `calculate_niche`.
stacklevel=6,
)
# CellCharter aggregates an already reduced representation, so PCA comes first: the rings then
# aggregate a narrow dense matrix instead of `distance + 1` copies of every gene
if use_rep is None:
features = _pca_features(adata, n_pca_components=n_pca_components)
elif use_rep == "X": # the spelling `scanpy.pp.neighbors` takes
features = to_dense(adata.X)
else:
assert_key_in_adata(adata, use_rep, attr="obsm")
features = to_dense(adata.obsm[use_rep])
rings = compute_hop_adjacency_matrices(adata.obsp[spatial_connectivities_key], distance, n_jobs=n_jobs)
# hop 0 is the observation itself, so it heads the concatenation and every ring follows.
# Filling a preallocated block keeps the features' dtype and frees each aggregate as it lands
width = features.shape[1]
# a ring mean is not a count, so integer features cannot hold the block they are written into
dtype = np.result_type(features.dtype, np.float32)
embedding = np.empty((features.shape[0], width * (len(rings) + 1)), dtype=dtype)
embedding[:, :width] = features
for position, ring in enumerate(rings, start=1):
embedding[:, position * width : (position + 1) * width] = _aggregate_over(ring, features, aggregation)
return embedding
def _pca_features(adata: AnnData, *, n_pca_components: int | None) -> Array:
"""The PCA that stands in for a reduced representation when ``use_rep`` is not given."""
# scanpy's `pca(adata)` masks by `highly_variable` but also writes to `adata`; mask here instead
if "highly_variable" in adata.var:
X = adata.X[:, adata.var["highly_variable"].to_numpy()]
else:
X = adata.X
ceiling = min(X.shape)
if ceiling <= 1:
# a one-marker panel is its own reduction, and PCA cannot return a component here
return to_dense(X)
if n_pca_components is None:
# 10 matches scVI's default latent width, the input CellCharter is designed around
return sc.pp.pca(X, n_comps=min(10, ceiling - 1))
if not 1 <= n_pca_components < ceiling:
raise ValueError(
f"'n_pca_components' must be between 1 and {ceiling - 1}, the features PCA runs on "
f"({'highly variable ' if 'highly_variable' in adata.var else ''}genes and observations), "
f"got {n_pca_components}"
)
return sc.pp.pca(X, n_comps=n_pca_components)
def _resolution_values(resolutions: Any, *, pairs_ok: bool) -> list[Any]:
"""The resolution values, one per clustering run and one per labelled column.
*pairs_ok* admits the ``(latent, spatial)`` pair that only SpatialLeiden takes.
"""
if isinstance(resolutions, str | tuple) or not isinstance(resolutions, Iterable):
values = [resolutions]
else:
values = list(resolutions)
expected = "numbers or (latent, spatial) pairs of numbers" if pairs_ok else "numbers"
for value in values:
if isinstance(value, tuple):
if not pairs_ok:
raise TypeError(f"'resolutions' got the pair {value}, which only the 'spatialleiden' flavor takes")
if len(value) != 2 or not all(isinstance(x, Real) for x in value):
raise TypeError(f"'resolutions' got {value!r}, which is not a pair of numbers")
elif not isinstance(value, Real):
raise TypeError(f"'resolutions' must be {expected}, got {value!r}")
if len(values) == 0:
raise ValueError("'resolutions' is empty, so there is nothing to cluster")
repeated = sorted({str(v) for v in values if values.count(v) > 1})
if len(repeated) > 0:
raise ValueError(f"'resolutions' repeats {', '.join(repeated)}, but each value labels its own column")
return values
def _leiden_clusterers(
*,
base_colname: str,
resolutions: float | Sequence[float],
n_neighbors: int,
flavor: Literal["igraph", "leidenalg"],
n_iterations: int,
) -> dict[str, Clusterer]:
"""One Leiden clusterer per requested resolution, keyed by the column it labels."""
values = _resolution_values(resolutions, pairs_ok=False)
return {
f"{base_colname}_res={res}": LeidenClusterer(
n_neighbors=n_neighbors, resolution=res, flavor=flavor, n_iterations=n_iterations
)
for res in values
}
def _fit_clusterers(
adata: AnnData,
*,
embedding: Array,
clusterers: Mapping[str, Clusterer],
rng: np.random.Generator,
keep: NDArray[np.bool_] | None = None,
min_niche_size: int | None = None,
) -> list[str]:
"""Fit each clusterer on *embedding* and write its labels, returning the column names.
*keep* restricts the fit to those observations; the rest are labelled ``'not_a_niche'``
without having taken part in it.
"""
for column, clusterer in clusterers.items():
# `isinstance` sees method presence only, so check the one parameter the pipeline sets:
# a deterministic estimator such as DBSCAN satisfies the protocol and then rejects it
if not isinstance(clusterer, Clusterer):
raise TypeError(f"clusterer for '{column}' must implement fit_predict, get_params and set_params")
if "random_state" not in clusterer.get_params():
raise TypeError(f"clusterer for '{column}' has no 'random_state', so the pipeline cannot seed its fits")
# one rng per clusterer, so a resolution sweep is seeded independently of its length
rngs = rng.spawn(len(clusterers))
for (column, clusterer), rng in zip(clusterers.items(), rngs, strict=True):
if column in adata.obs.columns:
logg.info(f"Overwriting existing column '{column}'")
# a fresh clone per fit, so the estimator handed in is never mutated
fit = clone(clusterer).set_params(random_state=legacy_random(rng))
if keep is None:
labels = np.asarray(fit.fit_predict(embedding)).astype(str)
else:
labels = np.full(adata.n_obs, "not_a_niche", dtype=object)
labels[keep] = np.asarray(fit.fit_predict(embedding[keep])).astype(str)
adata.obs[column] = _niche_labels(labels, min_niche_size)
return list(clusterers)
def _niche_labels(labels: NDArray[np.str_] | NDArray[np.object_], min_niche_size: int | None) -> pd.Categorical:
"""String niche labels as a categorical, niches under *min_niche_size* relabeled ``'not_a_niche'``."""
if min_niche_size is not None:
niches, counts = np.unique(labels, return_counts=True)
labels = np.where(np.isin(labels, niches[counts < min_niche_size]), "not_a_niche", labels)
# the categories order the legend and the colors, so keep `sc.tl.leiden`'s: 0, 1, 2, ... 10
return pd.Categorical(labels, categories=sorted(np.unique(labels), key=_label_order))
def _label_order(label: str) -> tuple[bool, int, str]:
"""Numeric labels in numeric order, then any other label as text."""
try:
return False, int(label), ""
except ValueError:
return True, 0, label
############
### postprocessing
############
# TODO(v1.9.0): delete with `calculate_niche`, its only caller; no flavor function takes `library_key`
def _niches_per_library(
data: AnnData | SpatialData,
*,
library_key: str,
columns: list[str],
table_key: str | None,
copy: bool,
run: Callable[[AnnData], object],
) -> AnnData | None:
"""v1.8.3's ``library_key``: each library fitted on its own, labels prefixed ``lib=<id>_``."""
def loop(adata: AnnData) -> None:
assert_key_in_adata(adata, library_key, attr="obs")
# fresh per call, so a rerun cannot keep the previous run's labels; an observation with
# no library keeps "not_a_niche", as in v1.8.3
labels = {col: np.full(adata.n_obs, "not_a_niche", dtype=object) for col in columns}
libraries = adata.obs[library_key]
for lib_id in libraries.dropna().unique():
at = np.flatnonzero((libraries == lib_id).to_numpy())
lib_adata = adata[at].copy()
run(lib_adata)
for col in columns:
values = lib_adata.obs[col].astype(str).to_numpy()
labels[col][at] = [v if v == "not_a_niche" else f"lib={lib_id}_{v}" for v in values]
for col, values in labels.items():
adata.obs[col] = pd.Categorical(values)
return _on_table(data, table_key=table_key, copy=copy, work=loop)
def _on_table(
data: AnnData | SpatialData,
*,
table_key: str | None,
copy: bool,
work: Callable[[AnnData], None],
) -> AnnData | None:
"""Run *work* on the table, taking it out of a SpatialData and putting it back."""
orig_adata = extract_adata_if_sdata(data, table_key=table_key)
adata = orig_adata.copy() if copy else orig_adata
work(adata)
# For SpatialData, the column names shouldn't have = sign. Hence, run sanitize_table.
# TODO: In future, change the naming standard of any niche columns added to not have '=' to be compatible with spatialdata naming
if isinstance(data, SpatialData):
sanitize_table(adata)
return adata if copy else None
def _spatialleiden_once(
adata: AnnData,
*,
key_added: str,
resolution_list: list[Any],
rng: np.random.Generator,
latent_connectivities_key: str,
spatial_connectivities_key: str,
layer_ratio: float,
n_iterations: int,
use_weights: bool | tuple[bool, bool],
min_niche_size: int | None,
) -> None:
"""One SpatialLeiden run per resolution, in place."""
try:
import spatialleiden as sl
except ImportError as e:
msg = "Please install the spatialleiden algorithm: `pip install squidpy[leiden]` or `conda install bioconda::spatialleiden` or `pip install spatialleiden`."
raise ImportError(msg) from e
# every resolution is a separate clustering run, so seed each one independently
resolution_rngs = rng.spawn(len(resolution_list))
for res, res_rng in zip(resolution_list, resolution_rngs, strict=True):
sl.spatialleiden(
adata,
resolution=res,
use_weights=use_weights,
n_iterations=n_iterations,
layer_ratio=layer_ratio,
latent_neighbors_key=latent_connectivities_key,
spatial_neighbors_key=spatial_connectivities_key,
random_state=legacy_random(res_rng),
directed=False,
key_added=f"{key_added}_res={res}",
)
# `sl.spatialleiden` writes its labels into `obs` rather than returning them, so read them
# back and finish them as every other flavor's are: string labels, small niches relabeled
column = f"{key_added}_res={res}"
adata.obs[column] = _niche_labels(adata.obs[column].to_numpy().astype(str), min_niche_size)