spatialDistanceHeatmap

spatialDistanceHeatmap ¶

spatialDistanceHeatmap(
    data,
    spatialDistance="spatial_distance",
    phenotype="phenotype",
    imageId="imageid",
    log=False,
    heatmapSummarize=True,
    heatmapNaColor="grey",
    heatmapCmap="vlag_r",
    distanceFrom=None,
    distanceTo=None,
    subsetCol=None,
    subsetValue=None,
    fileName="spatial_distance_heatmap.pdf",
    outputDir=None,
    saveDir=None,
    show=True,
    returnData=False,
    returnFig=False,
    dpi=300,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Cell-type by cell-type distance matrix, as a heatmap.

Reads the per-cell distances that sp.tl.spatialDistance writes to uns[spatialDistance], averages them within each phenotype, and draws the result. A reversed colormap is used by default so that near reads as warm.

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
`spatialDistance`	`str`	Key in `uns` holding the distance table.	`'spatial_distance'`
`phenotype`	`str`	Column in `obs` used to group the rows.	`'phenotype'`
`imageId`	`str`	Column in `obs` holding image identifiers.	`'imageid'`
`log`	`bool`	Plot `log1p` of the distances. Useful when a few cell types are far apart and compress everything else.	`False`
`heatmapSummarize`	`bool`	Accepted for signature compatibility with scimap; distances are always averaged across images in the current implementation. Use `subsetCol` and `subsetValue` to restrict to one image.	`True`
`heatmapNaColor`	`str`	Colour for missing pairs. Accepted for signature compatibility.	`'grey'`
`heatmapCmap`	`str`	Matplotlib colormap. `'vlag_r'` is accepted and mapped to `'coolwarm_r'`.	`'vlag_r'`
`distanceFrom`	`str \| list`	Keep only these phenotypes as rows — the cell types you are measuring from.	`None`
`distanceTo`	`str \| list`	Keep only these phenotypes as columns — the cell types you are measuring to.	`None`
`subsetCol`	`str`	Column in `obs` to filter on before plotting.	`None`
`subsetValue`	`str \| list`	Values of `subsetCol` to keep.	`None`
`**kwargs`	`dict`	Extra options. `figsize` sets the figure size in inches; it is scaled from the matrix shape when omitted.	`{}`
`fileName`	`str`	File name for the saved figure. The extension decides the format.	`'spatial_distance_heatmap.pdf'`
`outputDir`	`str`	Directory to save the figure in. When `None` nothing is written.	`None`
`saveDir`	`str`	Deprecated alias for `outputDir`, kept for scripts carried over from scimap. `outputDir` wins when both are given.	`None`
`show`	`bool`	Call `plt.show()` before returning. Set `False` in scripts and notebooks that save rather than display.	`True`
`returnData`	`bool`	Return the `DataFrame` behind the plot instead of drawing it.	`False`
`returnFig`	`bool`	Return `(fig, axes)`. With `returnData` as well, returns `(fig, axes, plotData)`.	`False`
`dpi`	`int`	Resolution of the saved figure.	`300`
`transparent`	`bool`	Save with a transparent background.	`False`
`sdataTable`	`str`	Which `SpatialData` table to read. Ignored for `AnnData` input, and optional when the store has exactly one table.	`None`

Returns:

Name	Type	Description
`result`	`None \| DataFrame \| tuple`	`None` by default; the phenotype x phenotype mean-distance table with `returnData=True`; `(fig, ax)` with `returnFig=True`.

Example

adata = sp.tl.spatialDistance(adata, phenotype="phenotype")
sp.pl.spatialDistanceHeatmap(adata, phenotype="phenotype")

# Only how far immune cells sit from tumour cells, in one image.
sp.pl.spatialDistanceHeatmap(
    adata,
    distanceFrom=["Treg", "NK cells"],
    distanceTo=["ECAD+"],
    subsetCol="imageid",
    subsetValue="sample_1",
)