Data

Data utilities for spatial transcriptomics analysis.

Datasets

Synthetic datasets for testing and examples.

spatialvi.data._datasets.synthetic_spatial(n_cells=1000, n_genes=200, n_cell_types=5, n_batches=1, spatial_dims=2, spatial_scale=100.0, library_size_mean=10000, library_size_std=3000, dropout_rate=0.3, seed=None)

Generate synthetic spatial transcriptomics data.

Creates an AnnData object with: - Count matrix with cell type-specific expression patterns - Spatial coordinates - Cell type labels - Optional batch labels

Parameters:

• n_cells (int) – Number of cells to generate.

• n_genes (int) – Number of genes.

• n_cell_types (int) – Number of cell types.

• n_batches (int) – Number of batches.

• spatial_dims (int) – Number of spatial dimensions (2 or 3).

• spatial_scale (float) – Scale of spatial coordinates.

• library_size_mean (float) – Mean library size.

• library_size_std (float) – Standard deviation of library size.

• dropout_rate (float) – Rate of dropout (zero inflation).

• seed (int | None) – Random seed for reproducibility.

• n_cells (int)

• n_genes (int)

• n_cell_types (int)

• n_batches (int)

• spatial_dims (int)

• spatial_scale (float)

• library_size_mean (float)

• library_size_std (float)

• dropout_rate (float)

• seed (int | None)

Return type:

AnnData

Returns:

AnnData object with synthetic spatial data.

spatialvi.data._datasets.synthetic_scrna(n_cells=2000, n_genes=200, n_cell_types=5, n_batches=1, library_size_mean=10000, library_size_std=3000, dropout_rate=0.3, seed=None)

Generate synthetic single-cell RNA-seq data.

Creates an AnnData object suitable for use as a reference for spatial deconvolution methods.

Parameters:

• n_cells (int) – Number of cells to generate.

• n_genes (int) – Number of genes.

• n_cell_types (int) – Number of cell types.

• n_batches (int) – Number of batches.

• library_size_mean (float) – Mean library size.

• library_size_std (float) – Standard deviation of library size.

• dropout_rate (float) – Rate of dropout (zero inflation).

• seed (int | None) – Random seed for reproducibility.

• n_cells (int)

• n_genes (int)

• n_cell_types (int)

• n_batches (int)

• library_size_mean (float)

• library_size_std (float)

• dropout_rate (float)

• seed (int | None)

Return type:

AnnData

Returns:

AnnData object with synthetic scRNA-seq data.

spatialvi.data._datasets.synthetic_visium(n_spots=500, n_genes=200, n_cell_types=5, cells_per_spot_mean=10, cells_per_spot_std=3, grid_rows=25, grid_cols=20, seed=None)

Generate synthetic Visium-like spatial data.

Creates aggregated spot-level data with known cell type compositions.

Parameters:

• n_spots (int) – Number of spots to generate.

• n_genes (int) – Number of genes.

• n_cell_types (int) – Number of cell types.

• cells_per_spot_mean (float) – Mean number of cells per spot.

• cells_per_spot_std (float) – Std of cells per spot.

• grid_rows (int) – Number of rows in spatial grid.

• grid_cols (int) – Number of columns in spatial grid.

• seed (int | None) – Random seed for reproducibility.

• n_spots (int)

• n_genes (int)

• n_cell_types (int)

• cells_per_spot_mean (float)

• cells_per_spot_std (float)

• grid_rows (int)

• grid_cols (int)

• seed (int | None)

Return type:

AnnData

Returns:

AnnData object with synthetic Visium data.

Fields

Custom data fields for spatial transcriptomics.

class spatialvi.data._fields.SpatialCoordinatesField(registry_key, attr_key='spatial')

Bases: ObsmField

Field for spatial coordinates.

Parameters:

• registry_key (str) – Key to register in the data registry.

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

• registry_key (str)

• attr_key (str)

validate_field(adata)

Validate spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object to validate.

• adata (AnnData)

Return type:

None

class spatialvi.data._fields.NeighborIndexField(registry_key, attr_key='nn_index', n_neighbors=None)

Bases: ObsmField

Field for spatial neighbor indices.

Parameters:

• registry_key (str) – Key to register in the data registry.

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

• n_neighbors (int | None) – Expected number of neighbors.

• registry_key (str)

• attr_key (str)

• n_neighbors (int | None)

validate_field(adata)

Validate neighbor indices.

Parameters:

• adata (AnnData) – AnnData object to validate.

• adata (AnnData)

Return type:

None

class spatialvi.data._fields.NeighborDistanceField(registry_key, attr_key='nn_dist')

Bases: ObsmField

Field for spatial neighbor distances.

Parameters:

• registry_key (str) – Key to register in the data registry.

• attr_key (str) – Key in adata.obsm for neighbor distances.

• registry_key (str)

• attr_key (str)

validate_field(adata)

Validate neighbor distances.

Parameters:

• adata (AnnData) – AnnData object to validate.

• adata (AnnData)

Return type:

None

class spatialvi.data._fields.NicheCompositionField(registry_key, attr_key='niche_composition', n_cell_types=None)

Bases: ObsmField

Field for neighborhood cell type composition.

Parameters:

• registry_key (str) – Key to register in the data registry.

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

• n_cell_types (int | None) – Expected number of cell types.

• registry_key (str)

• attr_key (str)

• n_cell_types (int | None)

validate_field(adata)

Validate niche composition.

Parameters:

• adata (AnnData) – AnnData object to validate.

• adata (AnnData)

Return type:

None

Preprocessing

Preprocessing utilities for spatial transcriptomics data.

spatialvi.data._preprocessing.compute_spatial_neighbors(adata, spatial_key='spatial', n_neighbors=20, index_key='nn_index', dist_key='nn_dist', metric='euclidean', copy=False)

Compute spatial nearest neighbors.

Parameters:

• adata (AnnData) – AnnData object with spatial coordinates.

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

• n_neighbors (int) – Number of neighbors to compute.

• index_key (str) – Key to store neighbor indices in obsm.

• dist_key (str) – Key to store neighbor distances in obsm.

• metric (Literal['euclidean', 'manhattan', 'cosine']) – Distance metric to use.

• copy (bool) – Whether to return a copy of the AnnData.

• adata (AnnData)

• spatial_key (str)

• n_neighbors (int)

• index_key (str)

• dist_key (str)

• metric (Literal['euclidean', 'manhattan', 'cosine'])

• copy (bool)

Return type:

AnnData | None

Returns:

AnnData with neighbor information if copy=True, else None.

spatialvi.data._preprocessing.compute_niche_composition(adata, labels_key, index_key='nn_index', composition_key='niche_composition', copy=False)

Compute neighborhood cell type composition.

Parameters:

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

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

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

• composition_key (str) – Key to store composition in obsm.

• copy (bool) – Whether to return a copy of the AnnData.

• adata (AnnData)

• labels_key (str)

• index_key (str)

• composition_key (str)

• copy (bool)

Return type:

AnnData | None

Returns:

AnnData with composition if copy=True, else None.

spatialvi.data._preprocessing.normalize_spatial(adata, spatial_key='spatial', method='minmax', copy=False)

Normalize spatial coordinates.

Parameters:

• adata (AnnData) – AnnData object with spatial coordinates.

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

• method (Literal['minmax', 'zscore', 'center']) – Normalization method: - “minmax”: Scale to [0, 1] - “zscore”: Zero mean, unit variance - “center”: Center around zero

• copy (bool) – Whether to return a copy of the AnnData.

• adata (AnnData)

• spatial_key (str)

• method (Literal['minmax', 'zscore', 'center'])

• copy (bool)

Return type:

AnnData | None

Returns:

AnnData with normalized coordinates if copy=True, else None.

spatialvi.data._preprocessing.filter_by_spatial_density(adata, spatial_key='spatial', min_density=None, max_density=None, n_neighbors=10, copy=False)

Filter cells by local spatial density.

Parameters:

• adata (AnnData) – AnnData object with spatial coordinates.

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

• min_density (float | None) – Minimum density threshold (cells per unit area).

• max_density (float | None) – Maximum density threshold.

• n_neighbors (int) – Number of neighbors for density estimation.

• copy (bool) – Whether to return a copy of the AnnData.

• adata (AnnData)

• spatial_key (str)

• min_density (float | None)

• max_density (float | None)

• n_neighbors (int)

• copy (bool)

Return type:

AnnData | None

Returns:

Filtered AnnData if copy=True, else None.

spatialvi.data._preprocessing.add_spatial_noise(adata, spatial_key='spatial', noise_scale=0.01, seed=None, copy=False)

Add small noise to spatial coordinates.

Useful for breaking ties in coordinates that are on a regular grid.

Parameters:

• adata (AnnData) – AnnData object with spatial coordinates.

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

• noise_scale (float) – Scale of noise relative to coordinate range.

• seed (int | None) – Random seed for reproducibility.

• copy (bool) – Whether to return a copy of the AnnData.

• adata (AnnData)

• spatial_key (str)

• noise_scale (float)

• seed (int | None)

• copy (bool)

Return type:

AnnData | None

Returns:

AnnData with noisy coordinates if copy=True, else None.

spatialvi.data._preprocessing.get_neighbor_expression(adata, index_key='nn_index', layer=None, aggregation='mean')

Get aggregated expression of neighboring cells.

Parameters:

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

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

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

• aggregation (Literal['mean', 'sum', 'max']) – Aggregation method.

• adata (AnnData)

• index_key (str)

• layer (str | None)

• aggregation (Literal['mean', 'sum', 'max'])

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]

Returns:

Aggregated neighbor expression array of shape (n_cells, n_genes).