bioconductor-cytoviewer

name

bioconductor-cytoviewer

description

This R package supports interactive visualization of multi-channel images and segmentation masks generated by imaging mass cytometry and other highly multiplexed imaging techniques using shiny. The cytoviewer interface is divided into image-level (Composite and Channels) and cell-level visualization (Masks). It allows users to overlay individual images with segmentation masks, integrates well with SingleCellExperiment and SpatialExperiment objects for metadata visualization and supports image do

cytoviewer

Workflows

Standard Workflow

This R package supports interactive visualization of multi-channel images and segmentation masks generated by imaging mass cytometry and other highly multiplexed imaging techniques using shiny. The cytoviewer interface is divided into image-level (Composite and Channels) and cell-level visualization (Masks). It allows users to overlay individual images with segmentation masks, integrates well with SingleCellExperiment and SpatialExperiment objects for metadata visualization and supports image do

library(cytoviewer)
library(cytomapper)

# Load example datasets
data("pancreasImages")
data("pancreasMasks")
data("pancreasSCE")

# Initialize the interactive cytoviewer application
app <- cytoviewer(image = pancreasImages, 
                  mask = pancreasMasks, 
                  object = pancreasSCE, 
                  img_id = "ImageNb", 
                  cell_id = "CellNb")

if (interactive()) {
  shiny::runApp(app, launch.browser = TRUE)
}

Input: CytoImageList objects for images and masks, and a SingleCellExperiment object for cell metadata. Output: A runnable interactive Shiny application.

When to Use

• Interactive Multi-Channel Visualization: Use to interactively explore highly multiplexed images (e.g., from Imaging Mass Cytometry, t-CyCIF, or MIBI) and segmentation masks.
• Overlaying Images and Masks: Use to overlay cell outlines onto composite images and color them by cell-specific metadata.
• Cell-Level Metadata Exploration: Use to visualize segmentation masks colored by continuous or categorical cell-specific metadata.
• Image Export: Use to download composite, individual channel, or mask images directly from the interactive interface.

When NOT to Use

• Static Visualization: For generating static, non-interactive plots of multiplexed images in R scripts, use cytomapper directly instead of launching cytoviewer.
• Non-Spatial Single-Cell Data: For general single-cell RNA-seq visualization without spatial or imaging coordinates, use iSEE or scater.

Data Requirements

• Images (image): A CytoImageList object containing one or multiple multi-channel images where each channel represents pixel-level intensities of a marker.
• Masks (mask): A CytoImageList object containing single-channel segmentation masks with integer values representing cell IDs or background.
• Metadata Object (object): A SingleCellExperiment or SpatialExperiment object containing cell-specific metadata in its colData slot.
• Identifiers: Matching img_id (image identifier column) and cell_id (cell identifier column) to link the single-cell metadata with the images and masks.

Key Parameters

• image (NULL): A CytoImageList object containing multi-channel images.
• mask (NULL): A CytoImageList object containing segmentation masks.
• object (NULL): A SingleCellExperiment or SpatialExperiment object containing cell metadata.
• img_id (NULL): A character string indicating the metadata column containing image identifiers.
• cell_id (NULL): A character string indicating the metadata column containing cell identifiers.

Best Practices

• Set as.is = TRUE when reading in segmentation masks using loadImages() to ensure that pixel values (representing cell IDs) are scaled correctly.
• Add matching image IDs to the elementMetadata slot of both the image and mask CytoImageList objects (e.g., using mcols()) to link them properly.
• Set descriptive channel names on the image object using channelNames(cur_images) <- ... to ensure markers are correctly labeled in the interactive interface.
• Use measureObjects() to calculate cell-specific intensities and morphological features from images and masks to populate the SingleCellExperiment object.

Common Pitfalls

• Mismatched Identifiers: If img_id or cell_id do not match exactly between the SingleCellExperiment object and the CytoImageList objects, metadata overlay and cell-level visualization will fail.
• Incorrect Mask Scaling: Reading in segmentation masks without setting as.is = TRUE in loadImages() can scale integer cell IDs, breaking the link between masks and single-cell metadata.

Alternatives

• cytomapper: For static visualization of highly multiplexed imaging data.
• iSEE: For interactive visualization of general single-cell datasets.
• EBImage: For general image processing and handling in R.

Citations

• Meyer, Eling, and Bodenmiller (2023). Cytoviewer: An R/Bioconductor Package for Interactive Visualization and Exploration of Highly Multiplexed Imaging Data. bioRxiv.
• Eling et al. (2020). Cytomapper: An R/Bioconductor Package for Visualization of Highly Multiplexed Imaging Data. Bioinformatics.

References

• Homepage: bioconductor.org/packages/cytoviewer
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/cytoviewer/inst/doc/cytoviewer.html