spatialCooccurrence

spatialCooccurrence ¶

spatialCooccurrence(
    data,
    spatialCooccurrence="spatialCooccurrence",
    summarizePlot=True,
    pVal=0.05,
    rowCluster=False,
    colCluster=False,
    cmap="vlag",
    nonsigColor="grey",
    subsetPhenotype=None,
    subsetNeighbourPhenotype=None,
    binaryView=False,
    fileName="spatial_cooccurrence.pdf",
    outputDir=None,
    saveDir=None,
    show=True,
    returnData=False,
    returnFig=False,
    dpi=300,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Co-occurrence heatmap: which cell types sit next to which, more than chance.

Reads the long-format table that sp.tl.spatialCooccurrence writes to uns[spatialCooccurrence] — phenotype, neighbour_phenotype, one score column per image and one pvalue_<image> column per image — and pivots it into a matrix. Pairs whose p-value is at or above pVal are drawn in nonsigColor rather than on the colour scale, so only the significant structure carries colour.

For backward compatibility, a uns value that is already a phenotype x neighbour_phenotype matrix is plotted as-is, with no significance masking.

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
`spatialCooccurrence`	`str`	Key in `uns` holding the result. Falls back to `'spatial_interaction'` so results carried over from scimap still plot.	`'spatialCooccurrence'`
`summarizePlot`	`bool`	`True` averages the scores across images and keeps the largest (most conservative) p-value per pair. `False` keeps one column per image, with the pairs as rows.	`True`
`pVal`	`float`	Significance threshold for the greying-out.	`0.05`
`rowCluster`	`bool`	Accepted for signature compatibility with scimap; rows are not reordered. Use `subsetPhenotype` to control which rows appear.	`False`
`colCluster`	`bool`	Accepted for signature compatibility with scimap; see `rowCluster`.	`False`
`cmap`	`str`	Matplotlib colormap. `'vlag'` is accepted and mapped to `'coolwarm'`.	`'vlag'`
`nonsigColor`	`str`	Colour for pairs that fail the `pVal` threshold.	`'grey'`
`subsetPhenotype`	`str \| list`	Keep only these phenotypes as rows.	`None`
`subsetNeighbourPhenotype`	`str \| list`	Keep only these phenotypes as columns.	`None`
`binaryView`	`bool`	Reduce the scores to their sign — attraction, avoidance — instead of their magnitude.	`False`
`**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_cooccurrence.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 pivoted score matrix with `returnData=True`; `(fig, ax)` with `returnFig=True`.

Example

adata = sp.tl.spatialCooccurrence(adata, phenotype="phenotype", permutation=1000)
sp.pl.spatialCooccurrence(adata)

# Attraction/avoidance only, per image.
sp.pl.spatialCooccurrence(adata, binaryView=True, summarizePlot=False)