Visualize feature expression on spatial coordinates

Plot continuous feature values — gene expression, dimension reduction components, metadata columns, or any numeric variable — directly on spatial tissue coordinates. SpatFeaturePlot() is the spatial analogue of a feature plot over a UMAP/t-SNE embedding: it paints each spot, cell, or molecule with the expression level of one or more features, revealing the spatial organization of gene activity.

Multiple features are automatically faceted, making it easy to compare spatial expression patterns across a gene panel in a single plot. For categorical grouping (e.g., cluster identity on spatial coordinates), use SpatDimPlot instead.

Usage

SpatFeaturePlot(
  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) or a Giotto object. S3 methods dispatch to the appropriate spatial technology handler.

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

For SpatFeaturePlot, group_by is typically NULL. If you want to color by a categorical variable, use SpatDimPlot instead. Note: for Giotto objects, group_by must be NULL — an error is raised otherwise.

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 spatial feature plot. When multiple features are provided, the plot is faceted with one panel per feature, sharing a common color scale (by default). The return value is always a single ggplot object (faceted if needed), not a list.

Note

SpatFeaturePlot requires features to be set. If features is NULL and no group_by is provided, the plot will be empty — use SpatDimPlot for categorical visualization or set features to a gene name.
For molecule-level visualization in FOV data, use SpatDimPlot with group_by = "molecules" and features set to the molecule names of interest.
The expression layer can significantly affect the visual dynamic range. Use "data" (log-normalized) for balanced visualization or "counts" for raw counts.
For Giotto objects, group_by is explicitly disallowed in SpatFeaturePlot — use SpatDimPlot for group-based coloring.

Supported spatial technologies

SpatFeaturePlot inherits all spatial technology support from the internal SpatPlot() workhorse. See spatialplot_args for details on coordinate handling, layer order, and technology-specific defaults.