scanpy.pl.spatial#

scanpy.pl.spatial(adata, *, color=None, mask_obs=None, gene_symbols=None, use_raw=None, sort_order=True, edges=False, edges_width=0.1, edges_color='grey', neighbors_key=None, arrows=False, arrows_kwds=None, groups=None, components=None, dimensions=None, layer=None, projection='2d', scale_factor=None, color_map=None, cmap=None, palette=None, na_color=None, na_in_legend=True, size=1.0, frameon=None, legend_fontsize=None, legend_fontweight='bold', legend_loc='right margin', legend_fontoutline=None, colorbar_loc='right', vmax=None, vmin=None, vcenter=None, norm=None, add_outline=False, outline_width=(0.3, 0.05), outline_color=('black', 'white'), ncols=4, hspace=0.25, wspace=None, title=None, show=None, save=None, ax=None, return_fig=None, marker='.', basis='spatial', img=None, img_key=_empty, library_id=_empty, crop_coord=None, alpha_img=1.0, bw=False, spot_size=None, **kwargs)[source]#

Scatter plot in spatial coordinates.

This function allows overlaying data on top of images. Use the parameter img_key to see the image in the background And the parameter library_id to select the image. By default, 'hires' and 'lowres' are attempted.

Use crop_coord, alpha_img, and bw to control how it is displayed. Use size to scale the size of the Visium spots plotted on top.

As this function is designed to for imaging data, there are two key assumptions about how coordinates are handled:

1. The origin (e.g (0, 0)) is at the top left – as is common convention with image data.

2. Coordinates are in the pixel space of the source image, so an equal aspect ratio is assumed.

If your anndata object has a "spatial" entry in .uns, the img_key and library_id parameters to find values for img, scale_factor, and spot_size arguments. Alternatively, these values be passed directly.

Parameters:

adata AnnData: Annotated data matrix.
color str | Sequence[str] | None (default: None): Keys for annotations of observations/cells or variables/genes, e.g., 'ann1' or ['ann1', 'ann2'].
gene_symbols str | None (default: None): Column name in .var DataFrame that stores gene symbols. By default var_names refer to the index column of the .var DataFrame. Setting this option allows alternative names to be used.
use_raw bool | None (default: None): Use .raw attribute of adata for coloring with gene expression. If None, defaults to True if layer isn’t provided and adata.raw is present.
layer str | None (default: None): Name of the AnnData object layer that wants to be plotted. By default adata.raw.X is plotted. If use_raw=False is set, then adata.X is plotted. If layer is set to a valid layer name, then the layer is plotted. layer takes precedence over use_raw.
library_id str | None | Empty (default: _empty): library_id for Visium data, e.g. key in adata.uns["spatial"].
img_key str | None | Empty (default: _empty): Key for image data, used to get img and scale_factor from "images" and "scalefactors" entires for this library. To use spatial coordinates, but not plot an image, pass img_key=None.
img ndarray | None (default: None): image data to plot, overrides img_key.
scale_factor float | None (default: None): Scaling factor used to map from coordinate space to pixel space. Found by default if library_id and img_key can be resolved. Otherwise defaults to 1..
spot_size float | None (default: None): Diameter of spot (in coordinate space) for each point. Diameter in pixels of the spots will be size * spot_size * scale_factor. This argument is required if it cannot be resolved from library info.
crop_coord tuple[int, int, int, int] | None (default: None): Coordinates to use for cropping the image (left, right, top, bottom). These coordinates are expected to be in pixel space (same as basis) and will be transformed by scale_factor. If not provided, image is automatically cropped to bounds of basis, plus a border.
alpha_img float (default: 1.0): Alpha value for image.
bw bool | None (default: False): Plot image data in gray scale.
sort_order bool (default: True): For continuous annotations used as color parameter, plot data points with higher values on top of others.
groups str | Sequence[str] | None (default: None): Restrict to a few categories in categorical observation annotation. The default is not to restrict to any groups.
dimensions tuple[int, int] | Sequence[tuple[int, int]] | None (default: None): 0-indexed dimensions of the embedding to plot as integers. E.g. [(0, 1), (1, 2)]. Unlike components, this argument is used in the same way as colors, e.g. is used to specify a single plot at a time. Will eventually replace the components argument.
components str | Sequence[str] | None (default: None): For instance, ['1,2', '2,3']. To plot all available components use components='all'.
projection Literal['2d', '3d'] (default: '2d'): Projection of plot (default: '2d').
legend_loc str (default: 'right margin'): Location of legend, either 'on data', 'right margin' or a valid keyword for the loc parameter of Legend.
legend_fontsize Union[int, float, Literal['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'], None] (default: None): Numeric size in pt or string describing the size. See set_fontsize().
legend_fontweight Union[int, Literal['light', 'normal', 'medium', 'semibold', 'bold', 'heavy', 'black']] (default: 'bold'): Legend font weight. A numeric value in range 0-1000 or a string. Defaults to 'bold' if legend_loc == 'on data', otherwise to 'normal'. See set_fontweight().
legend_fontoutline int | None (default: None): Line width of the legend font outline in pt. Draws a white outline using the path effect withStroke.
colorbar_loc str | None (default: 'right'): Where to place the colorbar for continous variables. If None, no colorbar is added.
size float (default: 1.0): Point size. If None, is automatically computed as 120000 / n_cells. Can be a sequence containing the size for each cell. The order should be the same as in adata.obs.
color_map Colormap | str | None (default: None): Color map to use for continous variables. Can be a name or a Colormap instance (e.g. "magma”, "viridis" or mpl.cm.cividis), see get_cmap(). If None, the value of mpl.rcParams["image.cmap"] is used. The default color_map can be set using set_figure_params().
palette str | Sequence[str] | Cycler | None (default: None): Colors to use for plotting categorical annotation groups. The palette can be a valid ListedColormap name ('Set2', 'tab20', …), a Cycler object, a dict mapping categories to colors, or a sequence of colors. Colors must be valid to matplotlib. (see is_color_like()). If None, mpl.rcParams["axes.prop_cycle"] is used unless the categorical variable already has colors stored in adata.uns["{var}_colors"]. If provided, values of adata.uns["{var}_colors"] will be set.
na_color Union[str, tuple[float, ...], None] (default: None): Color to use for null or masked values. Can be anything matplotlib accepts as a color. Used for all points if color=None.
na_in_legend bool (default: True): If there are missing values, whether they get an entry in the legend. Currently only implemented for categorical legends.
frameon bool | None (default: None): Draw a frame around the scatter plot. Defaults to value set in set_figure_params(), defaults to True.
title str | Sequence[str] | None (default: None): Provide title for panels either as string or list of strings, e.g. ['title1', 'title2', ...].
vmin Union[str, float, Callable[[Sequence[float]], float], Sequence[Union[str, float, Callable[[Sequence[float]], float]]], None] (default: None): The value representing the lower limit of the color scale. Values smaller than vmin are plotted with the same color as vmin. vmin can be a number, a string, a function or None. If vmin is a string and has the format pN, this is interpreted as a vmin=percentile(N). For example vmin=’p1.5’ is interpreted as the 1.5 percentile. If vmin is function, then vmin is interpreted as the return value of the function over the list of values to plot. For example to set vmin tp the mean of the values to plot, def my_vmin(values): return np.mean(values) and then set vmin=my_vmin. If vmin is None (default) an automatic minimum value is used as defined by matplotlib scatter function. When making multiple plots, vmin can be a list of values, one for each plot. For example vmin=[0.1, 'p1', None, my_vmin]
vmax Union[str, float, Callable[[Sequence[float]], float], Sequence[Union[str, float, Callable[[Sequence[float]], float]]], None] (default: None): The value representing the upper limit of the color scale. The format is the same as for vmin.
vcenter Union[str, float, Callable[[Sequence[float]], float], Sequence[Union[str, float, Callable[[Sequence[float]], float]]], None] (default: None): The value representing the center of the color scale. Useful for diverging colormaps. The format is the same as for vmin. Example: sc.pl.umap(adata, color=’TREM2’, vcenter=’p50’, cmap=’RdBu_r’)
add_outline bool | None (default: False): If set to True, this will add a thin border around groups of dots. In some situations this can enhance the aesthetics of the resulting image
outline_color tuple[str, str] (default: ('black', 'white')): Tuple with two valid color names used to adjust the add_outline. The first color is the border color (default: black), while the second color is a gap color between the border color and the scatter dot (default: white).
outline_width tuple[float, float] (default: (0.3, 0.05)): Tuple with two width numbers used to adjust the outline. The first value is the width of the border color as a fraction of the scatter dot size (default: 0.3). The second value is width of the gap color (default: 0.05).
ncols int (default: 4): Number of panels per row.
wspace float | None (default: None): Adjust the width of the space between multiple panels.
hspace float (default: 0.25): Adjust the height of the space between multiple panels.
return_fig bool | None (default: None): Return the matplotlib figure.
kwargs: Arguments to pass to matplotlib.pyplot.scatter(), for instance: the maximum and minimum values (e.g. vmin=-2, vmax=5).
show bool | None (default: None): Show the plot, do not return axis.
save bool | str | None (default: None): If True or a str, save the figure. A string is appended to the default filename. Infer the filetype if ending on {'.pdf', '.png', '.svg'}.
ax Axes | None (default: None): A matplotlib axes object. Only works if plotting a single component.

Return type:

Figure | Axes | list[Axes] | None

Returns:

If show==False a Axes or a list of it.

Examples

This function behaves very similarly to other embedding plots like umap()

>>> import scanpy as sc
>>> adata = sc.datasets.visium_sge("Targeted_Visium_Human_Glioblastoma_Pan_Cancer")
>>> sc.pp.calculate_qc_metrics(adata, inplace=True)
>>> sc.pl.spatial(adata, color="log1p_n_genes_by_counts")

scanpy.pl.spatial

Contents

scanpy.pl.spatial#