groupCorrelation

groupCorrelation ¶

groupCorrelation(
    data,
    groupBy,
    condition,
    normalize=False,
    subsetGroups=None,
    orderRow=None,
    orderColumn=None,
    clusterRows=True,
    clusterColumns=True,
    cmap="vlag",
    figsize=None,
    overlayValues=False,
    fontSize=10,
    fontColor="black",
    fileName="groupCorrelation.pdf",
    outputDir=None,
    saveDir=None,
    show=True,
    returnData=False,
    returnFig=False,
    dpi=300,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Correlate groups with each other by their composition across a condition.

A groupBy x condition contingency table is built, optionally row-normalised to proportions, and the groups are then correlated with one another. Use it to ask which samples resemble which, in terms of the cell types they contain.

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` whose values become the rows and columns of the correlation matrix — usually the sample or image id.	required
`condition`	`(str, required)`	Column in `obs` that supplies the composition vector for each group — usually `'phenotype'`.	required
`normalize`	`bool`	Convert each group's counts to proportions before correlating. Do this when the groups differ a lot in cell number.	`False`
`subsetGroups`	`list`	Restrict to these `groupBy` values.	`None`
`orderRow`	`list`	Explicit row order.	`None`
`orderColumn`	`list`	Explicit column order.	`None`
`clusterRows`	`bool`	Accepted for signature compatibility with scimap; the current implementation does not reorder rows. Use `orderRow` instead.	`True`
`clusterColumns`	`bool`	Accepted for signature compatibility with scimap; the current implementation does not reorder columns. Use `orderColumn` instead.	`True`
`cmap`	`str`	Matplotlib colormap. `'vlag'` is accepted and mapped to `'coolwarm'`.	`'vlag'`
`figsize`	`tuple`	Figure size in inches.	`None`
`overlayValues`	`bool`	Print the correlation coefficient inside each cell.	`False`
`fontSize`	`int`	Tick label font size.	`10`
`fontColor`	`str`	Accepted for signature compatibility with scimap; overlaid values are drawn in the default text colour.	`'black'`
`fileName`	`str`	File name for the saved figure. The extension decides the format.	`'groupCorrelation.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 group x group correlation matrix with `returnData=True`; `(fig, ax)` with `returnFig=True`.

Example

# Which samples have similar cell-type composition?
sp.pl.groupCorrelation(
    adata, groupBy="imageid", condition="phenotype", normalize=True
)