heatmap

heatmap ¶

heatmap(
    data,
    groupBy,
    layer=None,
    subsetMarkers=None,
    subsetGroups=None,
    clusterRows=True,
    clusterColumns=True,
    standardScale=None,
    orderRow=None,
    orderColumn=None,
    showPrevalence=False,
    cmap="vlag",
    figsize=None,
    saveDir=None,
    outputDir=None,
    fileName=None,
    verbose=True,
    show=True,
    returnData=False,
    returnFig=False,
    dpi=300,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Mean marker expression per group of cells, as a heatmap.

Cells are averaged within each category of groupBy, giving a group x marker matrix. Rows and columns are hierarchically clustered by default (average linkage on Euclidean distance), so related phenotypes and co-expressed markers end up next to each other.

Clustering and manual ordering are mutually exclusive: passing orderRow or orderColumn together with clusterRows=True or clusterColumns=True raises a ValueError.

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
`groupBy`	`(str, required)`	Column in `obs` to average within — typically `'phenotype'`, a cluster label, or `'imageid'`.	required
`layer`	`str`	Which matrix to average. `None` uses `.X`, `'raw'` uses `.raw.X`, any other string names a key in `.layers`.	`None`
`subsetMarkers`	`list`	Restrict the columns to these markers.	`None`
`subsetGroups`	`list`	Restrict the rows to these `groupBy` values.	`None`
`clusterRows`	`bool`	Hierarchically cluster the groups.	`True`
`clusterColumns`	`bool`	Hierarchically cluster the markers.	`True`
`standardScale`	`str`	`'row'` z-scores each group across markers, `'column'` z-scores each marker across groups, `None` leaves the means as they are. Use `'column'` when markers sit on very different scales.	`None`
`orderRow`	`list`	Explicit group order. Requires `clusterRows=False`.	`None`
`orderColumn`	`list`	Explicit marker order. Requires `clusterColumns=False`.	`None`
`showPrevalence`	`bool`	Annotate each row with the number of cells it summarises.	`False`
`cmap`	`str`	Any Matplotlib colormap name. `'vlag'` is accepted and mapped to `'coolwarm'`.	`'vlag'`
`figsize`	`tuple`	Figure size in inches. Scaled from the matrix shape when `None`.	`None`
`verbose`	`bool`	Print progress messages.	`True`
`outputDir`	`str`	Directory to save the figure in. When `None` nothing is written.	`None`
`fileName`	`str`	File name for the saved figure. The extension decides the format.	`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 group x marker `DataFrame` with `returnData=True`, `(fig, ax)` with `returnFig=True`, and `(fig, ax, plotData)` with both.

Example

# Phenotypes against the markers that define them.
sp.pl.heatmap(adata, groupBy="phenotype", standardScale="column")

# A fixed marker order, no clustering, saved to disk.
sp.pl.heatmap(
    adata,
    groupBy="phenotype",
    clusterColumns=False,
    orderColumn=["CD45", "ECAD", "SMA"],
    outputDir="figures",
    fileName="phenotype_heatmap.pdf",
    show=False,
)

# The underlying numbers, without drawing anything.
means = sp.pl.heatmap(adata, groupBy="phenotype", returnData=True)