Internal workhorse for spatial plot rendering

SpatPlot() is the S3 generic that underpins all spatial visualization in scplotter. It dispatches based on the class of object and, for Seurat objects, further inspects the image type (VisiumV1, VisiumV2, FOV, or SlideSeq) to invoke the correct rendering method. End-users should use SpatFeaturePlot or SpatDimPlot instead of calling SpatPlot() directly.

Each method assembles the requested spatial layers (image, masks, shapes, points) into a list of ggplot layer objects, then wraps them together via plotthis's internal spatial compositing functions to produce a final coordinate-aligned ggplot.

Usage

SpatPlot(
  object,
  fov = NULL,
  boundaries = NULL,
  image = NULL,
  masks = NULL,
  shapes = NULL,
  points = NULL,
  ext = NULL,
  crop = TRUE,
  group_by = NULL,
  features = NULL,
  layer = NULL,
  scale_factor = NULL,
  layers = NULL,
  flip_y = NULL,
  padding = NULL,
  image_scale = NULL,
  x = NULL,
  y = NULL,
  nmols = 1000,
  shapes_fill_by = NULL,
  graph = NULL,
  shape = 16,
  legend.position = "right",
  legend.direction = "vertical",
  theme = "theme_box",
  theme_args = list(),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  facet_scales = "fixed",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_byrow = TRUE,
  feat_type = "rna",
  use_overlap = FALSE,
  shapes_feat_type = "cell",
  shapes_alpha = NULL,
  spat_unit = NULL,
  spat_loc_name = NULL,
  spat_enr_names = NULL,
  ...
)

Arguments

object

A Seurat object (with spatial data loaded via SeuratObject) or a Giotto object (created with Giotto). The spatial technology is auto-detected from the object's image class.

fov

The name of the field of view (FOV) to plot. For Seurat FOV-based objects (Xenium, CosMx, etc.), defaults to SeuratObject::DefaultFOV(). Not applicable to Visium or Slide-seq objects.

boundaries

The name of the segmentation boundaries within the FOV to use for cell outlines. For Seurat FOV-based objects, defaults to SeuratObject::DefaultBoundary(). Not applicable to Visium or Slide-seq objects.

image

Controls the image/background layer. Possible values:

NULL — Default behavior: for Visium, the first image is used; for Giotto and FOV objects, no image is plotted.
A character string naming an image in the object — that specific image is plotted.
A color name (e.g., "white", "lightgray") — fills the background with a solid color rectangle.
TRUE — For Visium: uses the first image. For Giotto FOV: plots all non-overlapping images. For Seurat FOV: raises an error (no single default image).
FALSE — Disables the image layer entirely.

masks

Logical. Whether to plot cell segmentation masks. Currently not supported — setting this to TRUE will produce an error for all object types.

shapes

Controls the cell boundary (shapes) layer. Possible values:

TRUE — For Seurat FOV objects, uses boundaries as the shape boundaries. For other object types, uses the default boundaries. Not supported for Visium or Slide-seq objects.
A character string — The name of a specific set of boundaries within the FOV (Seurat) or spatial info name (Giotto) to use as shapes.
FALSE — Disables the shapes layer.

Defaults to TRUE when shapes_fill_by is provided, and NULL otherwise.

points

Logical. Whether to plot the points layer (cells, spots, or molecules as points on the spatial coordinates). Default: TRUE.

ext

The spatial extent (bounding box) of the plot. If NULL, the extent is calculated automatically from the data or, when crop = TRUE, from the tissue coordinates. Can be a numeric vector in the format c(xmin, xmax, ymin, ymax) or a terra::SpatExtent object.

crop

Logical. Whether to crop the plot to the extent of the tissue/spots. When TRUE (default), the plot is automatically zoomed to the data extent with optional padding. Analogous to the crop argument in Seurat::SpatialDimPlot().

group_by

A metadata column name used to color the points. Must be a character or factor column in the object's metadata. For SpatDimPlot(), if NULL and the object has FOV data with features, defaults to "molecules"; otherwise defaults to "Identity" (the active cluster identities). For SpatFeaturePlot(), group_by is ignored — use SpatDimPlot for categorical grouping. The special value "molecules" enables molecule-level visualization in FOV-based data.

features

A character vector of feature names to visualize. For SpatFeaturePlot(), each feature is plotted as a separate facet (or combined theme when a single feature is given), with expression values coloring the points. For SpatDimPlot(), features are treated as molecule names to plot at single-molecule resolution (FOV data only). Can include gene names, metadata column names, or dimension reduction components.

layer

The assay layer from which to extract feature expression values. For Seurat objects, one of "data" (default), "scale.data", or "counts". For Giotto objects, one of "normalized" (default), "scaled", "raw", "counts", or "custom".

scale_factor

Internal use. The image scale factor extracted from the object, used to map between pixel and tissue coordinate spaces. Automatically determined from the object's image data.

layers

A character vector specifying which layers to include and in what order. Possible values are "image", "masks", "shapes", and "points". Order matters — the first element is drawn first (bottom). Omit a layer name to disable it. Default: c("image", "masks", "shapes", "points") intersected with which layers are non-FALSE/non-NULL.

flip_y

Logical. Whether to flip the y-axis. This is primarily for internal coordinate system alignment — Visium/Slide-seq objects default to TRUE, FOV-based objects to FALSE. In most cases you do not need to set this manually.

padding

Numeric. Extra space added around the data extent when crop = TRUE. Expressed as a fraction of the data range (e.g., 0.05 adds 5\ defaults to 0. For other object types, defaults to 0 when an image layer is present and 0.05 otherwise.

image_scale

The image scale factor name to use, typically "lowres" or "hires". Controls which resolution of the stored image is rendered. Analogous to the image.scale argument in Seurat::SpatialDimPlot().

x

Internal use. The name of the x-coordinate column in the spatial data. Auto-detected based on the spatial technology ("imagerow" for Visium V1, varies for other types).

y

Internal use. The name of the y-coordinate column in the spatial data. Auto-detected based on the spatial technology ("imagecol" for Visium V1, varies for other types).

nmols

Integer. Maximum number of molecules to plot per feature when group_by = "molecules". Analogous to the nmols argument in Seurat::ImageDimPlot(). Default: 1000.

shapes_fill_by

A column name in the metadata (or a feature/gene name) used to fill the cell boundary shapes. If a single color string is provided, all shapes are filled with that color. When set, shapes defaults to TRUE.

graph

The name of a spatial network graph to overlay on the plot. Currently supported only for Giotto objects. Possible values:

TRUE — Use the default spatial network.
A character string — The graph name. If the name contains ":", the part before the colon is used as spat_unit and the part after as the graph name.
NULL (default) — No graph overlay.

The graph data is retrieved via GiottoClass::getSpatialNetwork().

shape

Numeric. The point shape (ggplot2 shape aesthetic). Default: 16 (filled circle). See https://ggplot2.tidyverse.org/reference/aes_linetype_size_shape.html for the full shape palette.

legend.position

Character. Legend position. One of "right" (default), "left", "top", "bottom", or "none".

legend.direction

Character. Legend direction. One of "vertical" (default) or "horizontal".

theme

A theme function or a character string naming one. Default: "theme_box". Built-in aliases (usable without namespace): "theme_box" (plotthis::theme_box()), "theme_this" (plotthis::theme_this()), "theme_blank" (ggplot2::theme_void()). Any ggplot2 theme can be used with its fully qualified name (e.g., "ggplot2::theme_bw").

theme_args

A named list of additional arguments passed to the theme function. Default: list().

title

Character. Plot title. Default: NULL (no title).

subtitle

Character. Plot subtitle. Default: NULL.

xlab

Character. x-axis label. Default: NULL.

ylab

Character. y-axis label. Default: NULL.

facet_scales

Character. Whether facet scales are "fixed" (default), "free", "free_x", or "free_y". Passed to ggplot2::facet_wrap() when multiple features are plotted.

facet_nrow

Integer. Number of facet rows. Default: NULL (auto-calculated).

facet_ncol

Integer. Number of facet columns. Default: NULL (auto-calculated).

facet_byrow

Logical. Whether to fill facets by row. Default: TRUE.

feat_type

Character. The feature type (modality) to query for expression values in Giotto objects. Common values: "rna" (default), "dna", "protein". Ignored for Seurat objects.

use_overlap

Logical. For Giotto FOV objects, whether to use pre-computed polygon-feature overlap results (from GiottoClass::combineFeatureOverlapData()) instead of cell-level expression. Default: FALSE.

shapes_feat_type

Character. The feature type to use when extracting metadata for shape filling in Giotto objects. Default: "cell".

shapes_alpha

Numeric. Transparency (alpha) value for the shapes layer, between 0 and 1. When points are also plotted, defaults to 0.5 so points remain visible on top of shapes; otherwise defaults to 1.

spat_unit

Character. The spatial unit to query in a Giotto object (e.g., "cell", "subcellular"). Auto-detected if NULL. Ignored for Seurat objects.

spat_loc_name

Character. The spatial locations name to query in a Giotto object. Auto-detected from available spatial locations if NULL. Ignored for Seurat objects.

spat_enr_names

Character. Spatial enrichment results names in a Giotto object (for enrichment-based feature extraction). Ignored for Seurat objects.

...

Additional arguments passed to the underlying layer functions. Arguments are dispatched by prefix:

image_*: Arguments passed to plotthis::SpatImagePlot() (e.g., image_alpha, image_interpolation).
masks_*: Arguments passed to plotthis::SpatMasksPlot().
shapes_*: Arguments passed to plotthis::SpatShapesPlot() (e.g., shapes_color, shapes_linewidth).
points_*: Arguments passed to plotthis::SpatPointsPlot() (e.g., points_size, points_alpha).
No prefix: Arguments without a recognized prefix are treated as points arguments, but with lower priority than points_* arguments.

Value

A ggplot object representing the assembled spatial plot.

Method dispatch

SpatPlot.Seurat — Inspects the first image's class to delegate to SpatPlot.Seurat.Visium, SpatPlot.Seurat.FOV, or SpatPlot.Seurat.SlideSeq.
SpatPlot.Seurat.Visium — Renders 10x Visium data with tissue image, spot points, and optional shape/mask layers.
SpatPlot.Seurat.FOV — Renders FOV-based data (Xenium, CosMx, etc.) with molecule-level or cell-level points, cell boundary shapes, and optional registered images.
SpatPlot.Seurat.SlideSeq — Renders Slide-seq bead data with colored background and point layer.
SpatPlot.giotto — Renders spatial data from Giotto objects with full support for images, shapes, points, molecules, and spatial network graphs.