Plot histology image — plotImage • SPATA2

Plots the histology image with ggplot2.

plotImage(object, ...)

# S4 method for class 'SPATA2'
plotImage(
  object,
  img_name = activeImage(object),
  outline = FALSE,
  by_section = TRUE,
  fragments = TRUE,
  line_alpha = 0.9,
  line_color = "black",
  line_size = 0.5,
  line_type = "solid",
  transform = TRUE,
  img_alpha = 1,
  scale_fct = 1,
  xrange = NULL,
  yrange = NULL,
  ...
)

# S4 method for class 'SpatialData'
plotImage(
  object,
  img_name = activeImage(object),
  outline = FALSE,
  by_section = TRUE,
  fragments = TRUE,
  line_alpha = 0.9,
  line_color = "black",
  line_size = 0.5,
  line_type = "solid",
  transform = TRUE,
  img_alpha = 1,
  scale_fct = 1,
  xrange = NULL,
  yrange = NULL,
  unit = "px",
  ...
)

# S4 method for class 'HistoImage'
plotImage(
  object,
  outline = FALSE,
  by_section = TRUE,
  fragments = TRUE,
  line_alpha = 0.9,
  line_color = "black",
  line_size = 1,
  line_type = "solid",
  transform = TRUE,
  img_alpha = 1,
  scale_fct = 1,
  xrange = NULL,
  yrange = NULL,
  display_subtitle = FALSE,
  ...
)

# S4 method for class 'Image'
plotImage(object, scale_fct = 1, img_alpha = 1, ...)

Arguments

object: An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.
...: Additional arguments given to ggpLayerZoom().
img_name: Character value. The name of the image of interest. If NULL, the active image is chosen by default. Either way, must be one of getImageNames().
by_section: Logical value. If TRUE, the outline is used which acknowledges the potential for multiple tissue sections. If FALSE, the outline is used which simply outlines everything with one single polygon.
line_alpha: Numeric. Affects alpha of main lines of the plot.
line_color: Character. Affects color of the main lines of the plot.
line_size: Numeric. Affects size of the main lines of the plot.
line_type: Character. The line type. One of 'blank', 'solid', 'dashed', 'dotted', 'dotdash', 'longdash' and 'twodash'.
transform: Logical value. Ignored if no images exist in the object. If TRUE, spatial transformation instructions saved during image alignment of the image img_name are applied. Only relevant if there are any images registered in the SPATA2 object.
img_alpha: Numeric value. Sets the transparency for the image.
xrange, yrange: Distance vector of length two or NULL. If not NULL, specifies the x- and y-range to which the spatial output is cropped. E.g. xrange = c(200, 500) results in the two dimensional space being cropped from x-coordinate 200px up to x-coordinate 500px. If NULL, the original range is used.
unit: Character value. Units of x- and y-axes. Defaults to 'px'. If a SI unit is specified, uses ggpLayerAxesSI() with default parameters. Add the layer manually with + ggpLayerAxesSI(...) for more control.

Value

A ggplot.

Distance measures

The vignette on distance measures in SPATA2 has been replaced. Click here to read it.

Image visualization with ggplot2

When comparing the output of ggplot() + ggpLayerImage() with other image plotting functions, you may notice that the image appears horizontally flipped when plotted using ggpLayerImage(). This behavior is due to the use of a Cartesian coordinate system in SPATA2, where a pixel with coordinates c(width = 1, height = 1) is plotted on the left side at the bottom. In contrast, functions like EBImage::display() or graphics::plot() use an image space coordinate system, where pixel heights start from the top. Consequently, in image space, pixel c(width = 1, height = 1) is displayed on the top resulting in mirror inverted visualization of the image.

We chose to use a Cartesian coordinate system in SPATA2 because we believe it provides a more intuitive framework for the spatial alignment of tissue, spatial annotations, spatial trajectories, barcoded sots, single cells, etc. where coordinates in the corresponding data.frames are provided in form of x- and y-variables. See getCoordsDf(), getImgAnnOutlineDf(), getTissueOutlineDf() etc.

If you prefer to view your image in the regular orientation, you can use the flipAll() function on your object, specifying axis = "horizontal", to reverse this effect.

Examples


library(SPATA2)
library(patchwork)

object <- loadExampleObject("UKF275T")

object <-
 createNumericAnnotations(
   object = object,
   variable = "HM_HYPOXIA",
   threshold = "kmeans_high",
   id = "hypoxia_ann",
   inner_borders = FALSE,
   force1 = TRUE
   )

# range of hypoxia annotation
hr <- getSpatAnnRange(object, id = "hypoxia_ann")

hr_ggpL <- ggpLayerSpatAnnOutline(object, ids = "hypoxia_ann")

plotSurface(object, "HM_HYPOXIA") + hr_ggpL

p_rect <-
 plotImage(object) +
 hr_ggpL +
 ggpLayerRect(object, xrange = hr$x, yrange = hr$y)

p_zoomed <-
 plotImage(object) +
 ggpLayerZoom(object, xrange = hr$x, yrange = hr$y)

p_rect + p_zoomed