Save spatial cell type annotation heatmaps

Creates and optionally saves spatial heatmaps for all cell types from PhiSpace continuous annotations. This function generates publication-ready visualizations showing the spatial distribution of cell type scores across tissue sections.

saveCellTypeMaps(
  sce,
  methodName = "PhiSpace",
  tissueName = "SpatialSample",
  coordNames = c("x", "y"),
  freeColScale = FALSE,
  quants = c(0.1, 1),
  psize = 0.5,
  savePlots = TRUE,
  returnPlots = FALSE,
  legendPosition = "none",
  censQuant = 1,
  ctypes = NULL,
  outputDir = "figs/spatialCellTypeHeatmaps",
  width = 10,
  height = 10,
  fignrow = 4,
  figncol = 4,
  fsize_title = 10,
  plot_margin = c(0, 0, 0, 0),
  fileFormat = "png",
  dpi = 300
)

Arguments

sce

A SingleCellExperiment or SpatialExperiment object containing spatial coordinates and PhiSpace annotations in reducedDim slot.

methodName

Character. Name of the reduced dimension containing cell type scores (default: "PhiSpace").

tissueName

Character. Name identifier for the tissue/sample, used in output filenames when saving plots (default: "SpatialSample").

coordNames

Character vector of length 2. Column names in colData(sce) containing x and y spatial coordinates. For SpatialExperiment objects, this will be automatically detected if not specified (default: c("x", "y")).

freeColScale

Logical. Whether to use independent color scales for each cell type (TRUE) or a unified scale across all cell types (FALSE). Unified scaling facilitates comparison between cell types (default: FALSE).

quants

Numeric vector of length 2. Quantiles used to set color scale limits when freeColScale = FALSE (default: c(0.1, 1)).

psize

Numeric. Point size for spatial coordinates (default: 0.5).

savePlots

Logical. Whether to save plots to disk (default: TRUE).

returnPlots

Logical. Whether to return the list of ggplot objects (default: FALSE). Note: renamed from returnPlot for clarity.

legendPosition

Character. Position of color legend. One of "none", "left", "right", "bottom", "top" (default: "none").

censQuant

Numeric between 0 and 1. Quantile threshold for censoring low values to reduce noise in visualization (default: 1, no censoring).

ctypes

Character vector. Specific cell types to plot. If NULL, all cell types from the annotation will be plotted (default: NULL).

outputDir

Character. Directory path where plots will be saved. Directory will be created if it doesn't exist (default: "figs/spatialCellTypeHeatmaps").

width

Numeric. Plot width in inches when saving (default: 10).

height

Numeric. Plot height in inches when saving (default: 10).

fignrow

Integer. Number of rows in multi-panel figures (default: 4).

figncol

Integer. Number of columns in multi-panel figures (default: 4).

fsize_title

Numeric. Font size for plot titles (default: 10).

plot_margin

Numeric vector of length 4. Plot margins in points (top, right, bottom, left) (default: c(0,0,0,0)).

fileFormat

Character. File format for saved plots. One of "png", "pdf", "jpeg", "tiff" (default: "png").

dpi

Numeric. Resolution for raster formats (default: 300).

Value

If returnPlots = TRUE, returns a named list of ggplot objects, one for each cell type. If savePlots = TRUE, plots are saved to the specified directory. Invisible NULL otherwise.

Details

This function creates spatial heatmaps showing the distribution of PhiSpace cell type scores across tissue sections. Each cell type is visualized as a separate heatmap where color intensity represents the confidence score for that cell type at each spatial location.

Key features:

  • Automatic handling of both SingleCellExperiment and SpatialExperiment objects

  • Flexible color scaling options (unified vs. independent scales)

  • Multi-panel output for efficient visualization of many cell types

  • Customizable censoring to reduce visualization noise

  • Multiple output formats supported

Color scaling:

  • freeColScale = FALSE: Uses the same color scale across all cell types, facilitating direct comparison of scores between different cell types

  • freeColScale = TRUE: Each cell type uses its own optimal color scale, maximizing contrast within each individual plot

Output organization: When saving plots, multiple cell types are arranged in multi-panel figures (e.g., 4x4 grids). If there are more cell types than can fit in one figure, multiple files will be created with sequential numbering.

See also

VizSpatial for single cell type visualization PhiSpace for generating cell type annotations

Examples

if (FALSE) { # \dontrun{
# Basic usage with default settings
saveCellTypeMaps(sce_with_phispace)

# Customize visualization parameters
saveCellTypeMaps(
  sce = spatial_sce,
  tissueName = "MouseBrain_Section1",
  psize = 0.8,
  censQuant = 0.9,
  freeColScale = TRUE
)

# Return plots for further customization
plots <- saveCellTypeMaps(
  sce = spatial_sce,
  savePlots = FALSE,
  returnPlots = TRUE
)

# Plot specific cell types only
saveCellTypeMaps(
  sce = spatial_sce,
  ctypes = c("Neurons", "Astrocytes", "Microglia"),
  fignrow = 1, figncol = 3
)
} # }