spatial#

API pages include interactive (HTML) plots that would possibly not render correctly on a mobile device.

Spatial plot.

Parameters:

data (AnnData | SpatialData) – Spatial data to plot. AnnData inputs use Visium-style metadata stored on the object. SpatialData inputs are resolved via the table_name, image_name, shapes_name, and coordinate_system arguments below.
key (str, default None) – The key (cell feature or gene name) to color the spots by.
frame (DataFrame | None, default None) – A prebuilt frame to plot from. If provided, the frame is used directly and building from data is skipped. Must contain the key column.
library_id (str | None, default None) – The library identifier. If None and only one library is present, it is auto-selected; if multiple libraries are present, this must be provided. Leave as None when no library metadata is present (generic spatial data). Ignored for SpatialData inputs.
image (bool, default True) – Whether to render the tissue image as a background layer.
image_key (str, default 'lowres') – Which image variant to render. Visium ships with ‘hires’ and ‘lowres’. Falls back to ‘hires’, then to any available variant, when the requested one is missing. Ignored for SpatialData inputs.
greyscale (bool, default False) – Whether to convert an RGB(A) image to greyscale (Rec.709 luminance).
image_alpha (float | None, default None) – Alpha (transparency) of the tissue image. Distinct from alpha, which controls spot transparency.
cmap (str | list | None, default None) – Colormap name or list of colors. Greyscale images only.
norm (bool | None, default None) – Whether to linearly scale greyscale luminance values to [0, 255]. Greyscale images only.
vmin (float | None, default None) – Lower bound for greyscale luminance normalization.
vmax (float | None, default None) – Upper bound for greyscale luminance normalization.
scale_axis ({0, 1} | None, default None) – Whether to standardize key values between 0 and 1 with min-max scaling. Constant values are set to 0. Only applied when key is numeric.
spatial_key (str, default 'spatial') – The embedding key containing spot coordinates in fullres pixel space. Ignored for SpatialData inputs (coordinates come from the chosen spot geometries).
table_name (str | None, default None) – Selects which annotation table to use when multiple are present. If None and exactly one table is present, it is auto-selected. SpatialData inputs only.
image_name (str | None, default None) – Selects which background image to render when multiple are present. If None and exactly one image is present, it is auto-selected. SpatialData inputs only.
shapes_name (str | None, default None) – Selects which spot geometries to use when multiple are present. If None and exactly one geometry is present, it is auto-selected. SpatialData inputs only.
coordinate_system (str | None, default None) – Target coordinate system. Image and geometries are aligned into this system before plotting. If None, the single available system is used, falling back to ‘global’ when multiple are defined. SpatialData inputs only.
polygon (bool, default False) – Render polygon-shaped geometries as filled polygons. When False (default), polygon geometries are reduced to their centroids and rendered as points. SpatialData inputs only.
crop (Sequence[int] | None, default None) – Crop the plot to a region given as (left, right, top, bottom).
mapping (FeatureSpec | None, default None) – Additional aesthetic mappings, the result of aes().
size (float | None, default 0.8) – Spot size.
alpha (float, default 1.0) – Alpha (transparency) of the spots.
groups (str | Sequence[str] | None, default None) – Select specific groups to show.
drop (str | Sequence[str] | None, default None) – Drop specific groups, filtering out rows where key matches any of them. Categorical keys only.
variable_keys (str | Sequence[str] | None, default None) – Variable keys to add to the DataFrame. If None, no additional keys are added.
add_columns (str | Sequence[str] | None, default None) – Extra metadata columns or variable names to materialise into the frame, on top of those inferred from key, mapping, and tooltips.
include_dimensions (bool | int) – Whether to include dimensions from embeddings in the DataFrame, default is False. Providing an integer will limit the number of dimensions to given number.
tooltips ({'none'} | Sequence[str] | FeatureSpec | None, default None) – Tooltips to show when hovering over a spot. None auto-generates from mapped keys; ‘none’ disables tooltips.
interactive (bool, default False) – Whether to make the plot interactive.
observations_name (str, default 'Barcode') – The name to give the barcode column in the DataFrame.
color_low (str, default '#f6f6f6') – Color for low values in the continuous gradient.
color_mid (str | None, default None) – Color for mid values in the continuous gradient. When None, the scale falls back to a 2-color gradient between color_low and color_high.
color_high (str, default '#377eb8') – Color for high values in the continuous gradient.
mid_point ({'mean', 'median', 'mid'} | float, default 'mid') – Midpoint for the continuous color gradient.
**point_kwargs – Additional parameters forwarded to geom_point.

Returns:

PlotSpec – Spatial plot of tissue spots over the H&E image.

Raises:

UnsupportedDataTypeError – If data is not a supported spatial data object.
KeyError – If a requested table, image, shape, or coordinate system is missing.
ValueError – If spatial components are ambiguous, crop is invalid, or polygon rendering cannot join shapes back to the table.
NotImplementedError – If polygon rendering encounters unsupported MultiPolygon geometry.

Notes

If no tissue image metadata is present, the plot falls back to a plain spatial scatter using the raw coordinates.

Examples

An example interactive spatial plot with a categorical key.

import scanpy as sc
from lets_plot import *

import cellestial as cl

data = cl.datasets.human_lymph_node(cache_directory="data")

cl.spatial(data,key="clusters",interactive=True)

With a gene name as the key.

cl.spatial(data, key="MS4A1",interactive=True)

Customize the plot

(
    cl.spatial(data, key="MS4A1", size=2.4, interactive=True)
    + ggsize(600, 600)
    + scale_color_viridis()
)

With another dataset.

import squidpy as sq

data_hne = sq.datasets.visium_hne_adata()

cl.spatial(data_hne,key="cluster",interactive=True)

Make the background image greyscale.

cl.spatial(data_hne,key="cluster",greyscale=True,interactive=True)

Select specific groups to show.

cl.spatial(data_hne,key="cluster", groups=["Hippocampus", "Hypothalamus_1", "Striatum"], interactive=True)