spatialDistance

spatialDistance ¶

spatialDistance(
    data,
    xCoordinate: str = "X_centroid",
    yCoordinate: str = "Y_centroid",
    zCoordinate: str = None,
    phenotype: str = "phenotype",
    subset: str = None,
    imageId: str = "imageid",
    label: str = "spatial_distance",
    verbose: bool = True,
    maxWorkers: int = None,
    outputDir: str = None,
    streamData: bool = False,
    sdataTable: str = None,
) -> Union[None, AnnData]

Distance from every cell to the nearest cell of each phenotype.

For each image independently, a BallTree is built per phenotype and queried with every cell, giving a cell x phenotype matrix of nearest-neighbour distances. The result is written to uns[label], indexed like obs so it can be joined back or plotted directly.

Distances are in the units of the coordinate columns — pixels for a typical mcmicro quantification. A cell's distance to its own phenotype is the distance to the nearest other cell of that type, not zero.

Plot the result with sp.pl.spatialDistanceHeatmap or sp.pl.spatialDistanceDistribution.

Parameters:

Name	Type	Description	Default
`data`	`(AnnData \| SpatialData \| str, required)`	The cell table. An `AnnData`, a path to an `.h5ad` file, a `SpatialData` object, or a path to a `.zarr` SpatialData store.	required
`xCoordinate`	`str`	Column in `obs` holding x positions.	`'X_centroid'`
`yCoordinate`	`str`	Column in `obs` holding y positions.	`'Y_centroid'`
`zCoordinate`	`str`	Column in `obs` holding z positions. Leave as `None` for 2D data; set it and the neighbourhood search becomes three-dimensional.	`None`
`phenotype`	`str`	Column in `obs` holding the cell type labels to measure between.	`'phenotype'`
`subset`	`str`	Process only this image.	`None`
`imageId`	`str`	Column in `obs` holding image identifiers. Distances are never computed across images.	`'imageid'`
`label`	`str`	Key in `uns` the distance table is written to.	`'spatial_distance'`
`maxWorkers`	`int`	Cap on parallel workers. Defaults to `max(1, cpu_count() - 1)`. Lower it to cut peak memory.	`None`
`verbose`	`bool`	Print progress messages.	`True`
`outputDir`	`str`	Directory to write the updated object to. With `None` the object is returned instead.	`None`
`streamData`	`bool`	Run out of core against an `.h5ad` path with CAP-AnnData, reading only the sections this function needs and writing back only what it changes. Requires `data` to be a path; the file is updated in place and `None` is returned.	`False`
`sdataTable`	`str`	Which `SpatialData` table to work on. Ignored for `AnnData` input, and optional when the store has exactly one table.	`None`

Returns:

Name	Type	Description
`adata`	`AnnData \| SpatialData \| None`	The updated object when `outputDir` is `None`. `None` in streaming mode and when `outputDir` is given, where the result is written to disk.

Example

adata = sp.tl.spatialDistance(adata, phenotype="phenotype")
adata.uns["spatial_distance"].head()

# Mean distance from each cell type to every other.
sp.pl.spatialDistanceHeatmap(adata, phenotype="phenotype")

# Out of core, on a file too large to load.
sp.tl.spatialDistance("big.h5ad", phenotype="phenotype", streamData=True)