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