spatialScatterPlot

spatialScatterPlot ¶

spatialScatterPlot(
    data,
    colorBy,
    topLayer=None,
    xCoordinate="X_centroid",
    yCoordinate="Y_centroid",
    imageId="imageid",
    layer=None,
    subset=None,
    s=None,
    ncols=None,
    alpha=1,
    dpi=200,
    fontSize=None,
    plotLegend=True,
    cmap="RdBu_r",
    catCmap="tab20",
    vmin=None,
    vmax=None,
    customColors=None,
    figsize=(5, 5),
    invertYaxis=True,
    outputDir=None,
    fileName="scimapScatterPlot.png",
    show=True,
    returnData=False,
    returnFig=False,
    transparent=False,
    sdataTable=None,
    **kwargs
)

Scatter cells at their tissue coordinates, coloured by anything.

One panel per entry in colorBy. Each key is looked up in obs first, then in var_names, so colorBy="phenotype" and colorBy="CD45" both work. Numeric values get a continuous colormap and a colourbar; categorical values get a discrete palette and a legend.

The y axis is inverted by default, because image coordinates count downwards from the top-left corner — without that the tissue appears mirrored relative to the raw image.

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
`colorBy`	`(str \| list, required)`	What to colour by. Each entry may be an `obs` column or a marker name. A `KeyError` names the key if it is in neither.	required
`topLayer`	`list`	Accepted for signature compatibility with scimap; the current implementation draws categories in sorted order.	`None`
`xCoordinate`	`str`	Column in `obs` holding x positions.	`'X_centroid'`
`yCoordinate`	`str`	Column in `obs` holding y positions.	`'Y_centroid'`
`imageId`	`str`	Column in `obs` holding image identifiers, used by `subset`.	`'imageid'`
`layer`	`str`	Which matrix to read marker values from. `None` uses `.X`.	`None`
`subset`	`str \| list`	Restrict to these images. Plotting a whole multi-image object at once is rarely useful.	`None`
`s`	`float`	Point size. Defaults to 5. Lower it to 1-3 for dense slides.	`None`
`ncols`	`int`	Panels per row. Defaults to `min(3, len(colorBy))`.	`None`
`alpha`	`float`	Point opacity.	`1`
`dpi`	`int`	Resolution of the saved figure.	`200`
`fontSize`	`int`	Title and legend font size.	`None`
`plotLegend`	`bool`	Draw the legend for categorical colours.	`True`
`cmap`	`str`	Colormap for numeric values.	`'RdBu_r'`
`catCmap`	`str`	Colormap used to build the discrete palette for categorical values.	`'tab20'`
`vmin`	`float`	Lower colour limit for numeric values.	`None`
`vmax`	`float`	Upper colour limit for numeric values.	`None`
`customColors`	`dict`	Explicit `{category: colour}` mapping. Categories missing from the mapping are drawn light grey.	`None`
`figsize`	`tuple`	Size of a single panel in inches.	`(5, 5)`
`invertYaxis`	`bool`	Invert the y axis so the plot matches the orientation of the raw image.	`True`
`outputDir`	`str`	Directory to save the figure in.	`None`
`fileName`	`str`	File name for the saved figure.	`'scimapScatterPlot.png'`
`show`	`bool`	Call `plt.show()` before returning.	`True`
`returnData`	`bool`	Return the plotted `DataFrame` instead of drawing.	`False`
`returnFig`	`bool`	Return `(fig, axes)`.	`False`
`transparent`	`bool`	Save with a transparent background.	`False`
`sdataTable`	`str`	Which `SpatialData` table to read.	`None`

Returns:

Name	Type	Description
`result`	`None \| DataFrame \| tuple`	`None` by default; a `DataFrame` of coordinates plus the coloured keys with `returnData=True`; `(fig, axes)` with `returnFig=True`.

Example

# Phenotypes in one image.
sp.pl.spatialScatterPlot(adata, colorBy="phenotype", subset="sample_1", s=3)

# Two markers side by side.
sp.pl.spatialScatterPlot(adata, colorBy=["CD45", "ECAD"], layer="rescaled")

# Fixed colours for the phenotypes that matter.
sp.pl.spatialScatterPlot(
    adata,
    colorBy="phenotype",
    customColors={"Treg": "#e41a1c", "ECAD+": "#377eb8"},
    outputDir="figures",
    show=False,
)