# 1 Introduction

This vignette gives an introduction to displaying highly-multiplexed imaging cytometry data with the cytomapper package. As an example, these instructions display imaging mass cytometry (IMC) data. However, other imaging cytometry approaches including multiplexed ion beam imaging (MIBI) (Angelo et al. 2014), tissue-based cyclic immunofluorescence (t-CyCIF) (Lin et al. 2018) and iterative indirect immunofluorescence imaging (4i) (Gut, Herrmann, and Pelkmans 2018), which produce pixel-level intensities and optionally segmentation masks can be displayed using cytomapper.

IMC (Giesen et al. 2014) is a multiplexed imaging cytometry approach to measure spatial protein abundance. In IMC, tissue sections are stained with a mix of around 40 metal-conjugated antibodies prior to laser ablation with $$1\mu{}m$$ resolution. The ablated material is transferred to a mass cytometer for time-of-flight detection of the metal ions (Giesen et al. 2014)(Mavropoulos et al., n.d.). In that way, hundreds of images (usually with an image size of around 1mm x 1mm) can be generated in a reasonable amount of time (Damond et al. 2019).

Raw IMC data are computationally processed using a segmentation pipeline (available at https://github.com/BodenmillerGroup/ImcSegmentationPipeline). This pipeline produces image stacks containing the raw pixel values for up to 40 channels, segmentation masks containing the segmented cells, cell-level expression and metadata information as well as a number of image-level meta information.

Cell-level expression and metadata can be processed and read into a SingleCellExperiment class object. For more information on the SingleCellExperiment object and how to create it, please see the SingleCellExperiment package and the Orchestrating Single-Cell Analysis with Bioconductor workflow. Furthermore, the cytomapper package provides the measureObjects function that generates a SingleCellExperiment based on segmentation masks and multi-channel images.

The cytomapper package provides a new CytoImageList class as a container for multiplexed images or segmentation masks. For more information on this class, refer to the CytoImageList section.

The main functions of this package include plotCells and plotPixels. The plotCells function requires the following object inputs to display cell-level information (expression and metadata):

1. a SingleCellExperiment object, which contains the cells’ counts and metadata
2. a CytoImageList object containing the segmentation masks

The plotPixels function requires the following object inputs to display pixel-level expression information:

1. a CytoImageList object containing the pixel-level information per channel
2. (optionally) a SingleCellExperiment object, which contains the cells’ counts and metadata
3. (optionally) a CytoImageList object containing the segmentation masks

# 2 Quick start

The following section provides a quick example highlighting the functionality of cytomapper. For detailed information on reading in the data, refer to the Reading in data section. More information on the required data format is provided in the Data formats section. In the first step, we will read in the provided toy dataset

data(pancreasSCE)
data(pancreasImages)
data(pancreasMasks)

The CytoImageList object containing pixel-level intensities representing the ion counts for five proteins can be displayed using the plotPixels function:

plotPixels(image = pancreasImages, colour_by = c("H3", "CD99", "CDH"))