Utilities

Utility functions for spatial transcriptomics analysis.

Metrics

Metrics for spatial analysis.

spatialvi.utils._metrics.spatial_autocorrelation(adata, var_names=None, spatial_key='spatial', n_neighbors=20, method='moran', layer=None)

Compute spatial autocorrelation for genes.

Parameters:

• adata (AnnData) – AnnData object.

• var_names (list[str] | None) – List of genes to compute. If None, computes for all.

• spatial_key (str) – Key in obsm for spatial coordinates.

• n_neighbors (int) – Number of neighbors for weight matrix.

• method (str) – Autocorrelation method: “moran” or “geary”.

• layer (str | None) – Layer to use. If None, uses X.

• adata (AnnData)

• var_names (list[str] | None)

• spatial_key (str)

• n_neighbors (int)

• method (str)

• layer (str | None)

Return type:

dict[str, float]

Returns:

Dictionary mapping gene names to autocorrelation values.

spatialvi.utils._metrics.compute_morans_i(values, weights)

Compute Moran’s I statistic.

Parameters:

• values (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Values to compute autocorrelation for.

• weights (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Spatial weight matrix.

• values (ndarray[tuple[Any, ...], dtype[_ScalarT]])

• weights (ndarray[tuple[Any, ...], dtype[_ScalarT]])

Return type:

float

Returns:

Moran’s I value.

spatialvi.utils._metrics.compute_gearys_c(values, weights)

Compute Geary’s C statistic.

Parameters:

• values (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Values to compute autocorrelation for.

• weights (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Spatial weight matrix.

• values (ndarray[tuple[Any, ...], dtype[_ScalarT]])

• weights (ndarray[tuple[Any, ...], dtype[_ScalarT]])

Return type:

float

Returns:

Geary’s C value.

spatialvi.utils._metrics.silhouette_spatial(adata, labels_key, spatial_key='spatial')

Compute silhouette score using spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object.

• labels_key (str) – Key in obs for cluster labels.

• spatial_key (str) – Key in obsm for spatial coordinates.

• adata (AnnData)

• labels_key (str)

• spatial_key (str)

Return type:

float

Returns:

Silhouette score.

spatialvi.utils._metrics.niche_purity(adata, labels_key, neighbor_key='nn_index')

Compute niche purity (fraction of neighbors with same label).

Parameters:

• adata (AnnData) – AnnData object with neighbor indices.

• labels_key (str) – Key in obs for labels.

• neighbor_key (str) – Key in obsm for neighbor indices.

• adata (AnnData)

• labels_key (str)

• neighbor_key (str)

Return type:

float

Returns:

Average niche purity.

spatialvi.utils._metrics.spatial_mixing_score(adata, batch_key, neighbor_key='nn_index')

Compute spatial mixing score for batch effect assessment.

Higher values indicate better mixing of batches in space.

Parameters:

• adata (AnnData) – AnnData object with neighbor indices.

• batch_key (str) – Key in obs for batch labels.

• neighbor_key (str) – Key in obsm for neighbor indices.

• adata (AnnData)

• batch_key (str)

• neighbor_key (str)

Return type:

float

Returns:

Spatial mixing score.

Visualization

Visualization utilities for spatial analysis.

spatialvi.utils._visualization.plot_spatial(adata, color=None, spatial_key='spatial', size=1.0, alpha=1.0, cmap='viridis', ax=None, show=True, **kwargs)

Plot cells in spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object.

• color (str | list[str] | None) – Key in obs or var_names to color by.

• spatial_key (str) – Key in obsm for spatial coordinates.

• size (float) – Point size.

• alpha (float) – Point transparency.

• cmap (str) – Colormap for continuous values.

• ax (Axes | None) – Matplotlib axes to use.

• show (bool) – Whether to show the plot.

• **kwargs – Additional arguments for scatter.

• adata (AnnData)

• color (str | list[str] | None)

• spatial_key (str)

• size (float)

• alpha (float)

• cmap (str)

• ax (Axes | None)

• show (bool)

Return type:

Axes | None

Returns:

Matplotlib axes if show=False.

spatialvi.utils._visualization.plot_proportions(adata, proportions_key='proportions', spatial_key='spatial', cell_types=None, ncols=3, size=10, cmap='Reds', show=True, **kwargs)

Plot cell type proportions in spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object.

• proportions_key (str) – Key in obsm for proportions.

• spatial_key (str) – Key in obsm for spatial coordinates.

• cell_types (list[str] | None) – Cell types to plot. If None, plots all.

• ncols (int) – Number of columns in subplot grid.

• size (float) – Point size.

• cmap (str) – Colormap.

• show (bool) – Whether to show the plot.

• **kwargs – Additional arguments for scatter.

• adata (AnnData)

• proportions_key (str)

• spatial_key (str)

• cell_types (list[str] | None)

• ncols (int)

• size (float)

• cmap (str)

• show (bool)

Return type:

Figure | None

Returns:

Matplotlib figure if show=False.

spatialvi.utils._visualization.plot_interactions(interaction_matrix, cell_types, cmap='coolwarm', vmin=None, vmax=None, annot=True, ax=None, show=True, **kwargs)

Plot cell-cell interaction matrix.

Parameters:

• interaction_matrix (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – Interaction scores matrix of shape (n_types, n_types).

• cell_types (list[str]) – List of cell type names.

• cmap (str) – Colormap.

• vmin (float | None) – Minimum value for colormap.

• vmax (float | None) – Maximum value for colormap.

• annot (bool) – Whether to annotate cells with values.

• ax (Axes | None) – Matplotlib axes to use.

• show (bool) – Whether to show the plot.

• **kwargs – Additional arguments for heatmap.

• interaction_matrix (ndarray[tuple[Any, ...], dtype[_ScalarT]])

• cell_types (list[str])

• cmap (str)

• vmin (float | None)

• vmax (float | None)

• annot (bool)

• ax (Axes | None)

• show (bool)

Return type:

Axes | None

Returns:

Matplotlib axes if show=False.

spatialvi.utils._visualization.plot_niche_composition(adata, composition_key='niche_composition', spatial_key='spatial', method='dominant', cell_types=None, size=50, ax=None, show=True, **kwargs)

Plot niche composition in spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object.

• composition_key (str) – Key in obsm for niche composition.

• spatial_key (str) – Key in obsm for spatial coordinates.

• method (Literal['pie', 'stacked', 'dominant']) – Visualization method: - “dominant”: Color by dominant cell type - “stacked”: Stacked bar at each location (for grid data) - “pie”: Pie chart at each location (for sparse data)

• cell_types (list[str] | None) – Cell type names.

• size (float) – Point/marker size.

• ax (Axes | None) – Matplotlib axes to use.

• show (bool) – Whether to show the plot.

• **kwargs – Additional arguments.

• adata (AnnData)

• composition_key (str)

• spatial_key (str)

• method (Literal['pie', 'stacked', 'dominant'])

• cell_types (list[str] | None)

• size (float)

• ax (Axes | None)

• show (bool)

Return type:

Axes | None

Returns:

Matplotlib axes if show=False.