# Cytoviewer

> cytoviewer

- Skill: `biomate-ai/cytoviewer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/cytoviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/cytoviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/cytoviewer

---


# 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

```r
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