Package 'HistoImagePlot'

Plot HoverNet H5AD Segmentation Overlay with Thumbnail

Description

Creates a side-by-side visualization of the original tissue thumbnail image and the HoverNet cell segmentation with colored cell type labels. This function works with HoverNet data stored in h5ad format and imported as a SpatialExperiment object.

Usage

plotHoverNetH5ADOverlay(
  hovernet,
  thumbnail_path,
  title = NULL,
  point_size = 0.01,
  legend_point_size = 2,
  color_palette = NULL,
  ncol = 2,
  rel_widths = c(1, 1.08),
  title_size = 25,
  flip_image = TRUE
)

Arguments

hovernet	A SpatialExperiment or SpatialFeatureExperiment object containing HoverNet segmentation data from h5ad format.
thumbnail_path	Path or URL to the thumbnail PNG image file.
title	Optional. Title for the combined plot. If NULL, uses "HoverNet Segmentation". Default is NULL.
point_size	Numeric value for the size of points in the segmentation plot. Default is 0.01.
legend_point_size	Numeric value for the size of points in the legend. Default is 2.
color_palette	Optional. A named vector of colors for cell types. If NULL, uses RColorBrewer palette. Default is NULL.
ncol	Number of columns for the side-by-side plots. Default is 2.
rel_widths	Relative widths of the image and segmentation plots. Default is c(1, 1.08).
title_size	Font size for the main title. Default is 25.
flip_image	Logical. Whether to flip the image vertically to match coordinate system. Default is TRUE.

Details

The function performs the following steps:

1. Loads the thumbnail PNG image (from local path or URL with caching)

2. Creates a segmentation plot colored by cell type using the type column from colData

3. Combines the thumbnail and segmentation side-by-side

4. Adds an optional title

The function expects the SpatialExperiment to have:

• spatialCoords with columns x_centroid and y_centroid

• colData with a type column for cell type classification

Remote PNG files are automatically cached using BiocFileCache for efficient handling without manual downloads.

Value

A ggplot object combining the thumbnail image and segmentation overlay with an optional title.

Examples

# Load h5ad HoverNet data
h5ad_url <- paste0(
  "https://store.cancerdatasci.org/hovernet/h5ad/",
  "TCGA-VG-A8LO-01A-01-DX1.B39A4D64-82A1-4A04-8AB6-918F3058B83B.h5ad"
)
hn_spe <- HoverNet(h5ad_url, outClass = "SpatialExperiment") |> import()

thumb_url <- paste0(
  "https://store.cancerdatasci.org/hovernet/thumb/",
  "TCGA-VG-A8LO-01A-01-DX1.B39A4D64-82A1-4A04-8AB6-918F3058B83B.png"
)
plotHoverNetH5ADOverlay(hn_spe, thumbnail_path = thumb_url)

---

Plot HoverNet Segmentation Overlay with Thumbnail

Description

Creates a side-by-side visualization of the original tissue thumbnail image and the HoverNet cell segmentation with colored cell type labels. The function automatically retrieves the thumbnail image associated with a HoverNet JSON file and overlays the segmentation data.

Usage

plotHoverNetOverlay(
  hovernet,
  json_path = NULL,
  title = NULL,
  point_size = 0.01,
  legend_point_size = 2,
  color_palette = NULL,
  ncol = 2,
  rel_widths = c(1, 1.08),
  title_size = 25,
  flip_image = TRUE
)

Arguments

hovernet	A SpatialExperiment or SpatialFeatureExperiment object created by importing a HoverNet JSON file, or a path/URL to a HoverNet JSON file.
json_path	Optional. Path or URL to the HoverNet JSON file. Only required if hovernet is a SpatialExperiment object and the original JSON path is not stored in metadata. Default is NULL.
title	Optional. Title for the combined plot. If NULL, uses the basename of the JSON file. Default is NULL.
point_size	Numeric value for the size of points in the segmentation plot. Default is 0.01.
legend_point_size	Numeric value for the size of points in the legend. Default is 2.
color_palette	Optional. A named vector of colors for cell types. If NULL, uses the colors from the HoverNet type map or RColorBrewer. Default is NULL.
ncol	Number of columns for the side-by-side plots. Default is 2.
rel_widths	Relative widths of the image and segmentation plots. Default is c(1, 1.08).
title_size	Font size for the main title. Default is 25.
flip_image	Logical. Whether to flip the image vertically to match coordinate system. Default is TRUE.

Details

The function performs the following steps:

1. If hovernet is a file path, imports it using HoverNet() and import()

2. Retrieves the associated thumbnail PNG

3. Creates a segmentation plot colored by cell type

4. Combines the thumbnail and segmentation side-by-side

5. Adds an optional title

The thumbnail is automatically downloaded and cached if a URL is provided. The segmentation uses the type column from the colData and colors are taken from the type_map metadata if available.

Value

A ggplot object combining the thumbnail image and segmentation overlay with an optional title.

Examples

json_url <- paste0(
  "https://store.cancerdatasci.org/hovernet/json/",
  "TCGA-VG-A8LO-01A-01-DX1.B39A4D64-82A1-4A04-8AB6-918F3058B83B.json.gz"
)
plotHoverNetOverlay(json_url, title = "TCGA-VG-A8LO Sample")

---