bodenmillergroup/cytomapper

R package for visualization of highly multiplexed imaging data

cytomapper

R/Bioconductor package to spatially visualize pixel- and cell-level information obtained from highly multiplexed imaging.

Its official package page can be found here: https://bioconductor.org/packages/cytomapper

Check status

Bioc branch	Checks
Release
Devel

Introduction

Highly multiplexed imaging acquires single-cell expression values of selected proteins in a spatially-resolved fashion. These measurements can be visualized across multiple length-scales. First, pixel-level intensities represent the spatial distributions of feature expression with highest resolution. Second, after segmentation, expression values or cell-level metadata (e.g. cell-type information) can be visualized on segmented cell areas. This package contains functions for the visualization of multiplexed read-outs and cell-level information obtained by multiplexed imaging cytometry. The main functions of this package allow 1. the visualization of pixel-level information across multiple channels (plotPixels), 2. the display of cell-level information (expression and/or metadata) on segmentation masks (plotCells) and 3. gating + visualization of cells on images (cytomapperShiny).

The cytomapper package provides toy data that were generated using imaging mass cytometry [1] taken from Damond et al. [2]. For further instructions to process raw imaging mass cytometry data, please refer to the IMC Segmentation Pipeline and the histoCAT as alternative visualization tool.

Requirements

The cytomapper package requires R version >= 4.0. It builds on data objects and functions contained in the SingleCellExperiment and EBImage packages. Therefore, these packages need to be installed (see below).

Installation

The cytomapper package can be installed from Bioconductor via:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
    
BiocManager::install("cytomapper")

The development version of the cytomapper package can be installed from Github using remotes in R. Please make sure to also install its dependecies:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
    
BiocManager::install(c("EBImage", "SingleCellExperiment"))

# install.packages("remotes")

remotes::install_github("BodenmillerGroup/cytomapper", build_vignettes = TRUE, dependencies = TRUE)

To load the package in your R session, type the following:

library(cytomapper)

Functionality

The cytomapper package offers three main functions: plotPixels, plotCells and cytomapperShiny.

plotPixels

The function takes a CytoImageList object (available via the cytomapper package) containing multi-channel images representing pixel-level expression values and optionally a CytoImageList object containing segementation masks and a SingleCellExperiment object containing cell-level metadata.

It allows the visualization of pixel-level information of up to six channels and outlining cells based on cell-level metadata. To see the full functionality in R type:

?plotPixels

plotCells

This function takes a CytoImageList object containing segementation masks and a SingleCellExperiment object containing cell-level mean expression values and metadata information.

It allows the visualization of cell-level expression data and metadata information. To see the full functionality in R type:

?plotCells

cytomapperShiny

This Shiny application allows gating of cells based on their expression values and visualises selected cells on their corresponding images.

It requires at least a SingleCellExperiment as input and optionally CytoImageList objects containing segmentation masks and multi-channel images. For full details, please refer to:

?cytomapperShiny

Getting help

For more information on processing imaging mass cytometry data, please refer to the IMC Segmentation Pipeline. This pipeline generates multi-channel tiff stacks containing the pixel-level expression values and segementation masks that can be used for the plotting functions in the cytomapper package.

More information on how to work with and generate a SingleCellExperiment object can be obtained from: Orchestrating Single-Cell Analysis with Bioconductor

An extensive introduction to image analysis in R can be found at: Introduction to EBImage

A full overview on the analysis workflow and functionality of the cytomapper package can be found by typing:

vignette("cytomapper")

For common issues regarding the cytomapper package, please refer to the wiki.

Demonstrations

To see example usage of the cytomapper package, please refer to its publication repository and a number of workshop demonstrations.

Citation

Please cite cytomapper as:

Nils Eling, Nicolas Damond, Tobias Hoch, Bernd Bodenmiller (2020). cytomapper: an R/Bioconductor package for visualization of highly
  multiplexed imaging data. Bioinformatics, doi: 10.1093/bioinformatics/btaa1061

Authors

Nils Eling nils.eling 'at' dqbm.uzh.ch

Nicolas Damond

Tobias Hoch

Maintainer

Lasse Meyer

References

[1] Giesen et al. (2014), Nature Methods, 11

[2] Damond et al. (2019), Cell Metabolism, 29

cytomapper's Issues

Make return_plot output conform with ggplot/cowplot

How to export cell mask from qupath?

Hi,
I have a naive question, I have an image overlay with 13 markers on which I performed cell segmentation on Qupath, I was wandering if you know hot to export the mask as a tif file to use with cytomapper.
Thank you

Rethink the name "SingleCellMapper"

Potential other names:
ICMapper - for "imaging cytometry" - inclusive CyCIF, MIBI, mIF

Things that the user can modify

contrast, etc.
legend.cex
image.title.colour
image.title.cex
image.title.text
scale_bar.pos
legend = NULL

Change "highly multiplexed imaging cytometry" to "highly multiplexed imaging" everywhere

Add option to load .h5 files into CytoImageList object

Also document serialising .rds files with links to .h5 files in the "on disk" vignette

Write proper replacement methods for "[[" and "["

show clustering groups in cytomapper

Dear developer,

Sorry to bother you, well, I got the results following steinbock and read in R using IMCtools. I got some clusters info after running UMAP. How can I input these cluster infos into cytomapper and make it visualized in certain images?

Thank you very much for your help.

Fan

Make normalize function more efficient

Normalizing individual channels with different inputRanges

When using the normalize function the same inputRange values are applied to all channels of the image but occasionally a certain channel needs to be enahnced more than others. A work around is to adjust the contrast in the bcg parameter for specific channels.

Potentially switch to ggplot logic

Warinings and errors when reading tif file exported with qupath

Hi,
I used qupath to export a tif file with 13 channels and antother file containing the cell mask.
When I read the multichannel file I get

images <- loadImages("/mnt/sda3/qupath_analysis/image_export_original.tif", pattern="tif")
Warning messages:
1: In readTIFF(x, all = all, ...) :
  TIFFReadDirectory: Unknown field with tag 50838 (0xc696) encountered
2: In readTIFF(x, all = all, ...) :
  TIFFReadDirectory: Unknown field with tag 50839 (0xc697) encountered

channelNames(images)
NULL

channelNames(images)= c("nuclei","ker","CD3", 'CD68', 'CD8', 'CXCL13', 'DC-LAMP','FAP', 'FOXP3', 'KI67','MZB1',
+                         'PD1','PDPN','TCF1')
Error in dimnames(y) <- `*vtmp*` : 
  length of 'dimnames' [3] not equal to array extent

I am using the dev version of Cytomapper.
Have you ever encountered this issue?

Implement HDF5Array backend

We need to test different ways of keeping images on disk.
Also, most functions in cytomapper should be parallelizable.

extend vignette section 8.1 Subsetting the SingleCellExperiment object

If the user wants to visualize the occurrence of a variable with a large number of unique elements, the image legend contains all possible elements (which appears very messy with more than ~15 elements) from the said variable. This is true even if an image contains only a fraction of all elements. The subsetting of the 'sce' object allows to display only the elements relevant for an image.

The following images show an example of how subsetting the sce object can help to improve the interpretability of images and the corresponding legend. Here, chemokine clusters are shown. Subsetting of the sce object retains only clusters relevant for the current image.

The vignette could be extended to illustrate such cases and help the user understand why subsetting an sce object can be helpful and sometimes necessary.

Without subsetting

With subsetting

Reader function for single-channel tiffs

As discussed with @ellispatrick it might be good to add a function that reads in single-channel tiffs into multi-channel CytoImageList objects. In general this is the format often used to store low-plex IF data or data prepared for histoCAT.

Make image handling more efficient

Somehow use raster images to write .h5 files - basically avoiding loading images into memory

Implement graphList and plotGraph function

Missing system libraries on Ubuntu 20.04 for EBImage

I know that this does not directly affect cytomapper, but probably good to document it somewhere.

On Ubuntu 20.04, the following system libraries are required for EBImage:

sudo apt-get install libfftw3-3 libfftw3-dev libtiff5-dev

Scale function should take multiple scaling factors

One scaling factor per image

Use shinytest for javascript testing

We need to wait until shinytest::ShinyDriver allows an app object as input

Implement a measureObjects function

This should be a wrapper for EBImage::computeFeatures.
The function takes two CytoImageList objects and returns a SingleCellExperiment object facilitating the data read-in process a looooot.

Create mockImage, mockSCE

Also create sce.rda in /data/ folder

shiny: wrong outlines

If no cells are selected in a scatter plot, all cells are outlined in the corresponding "Selection" image.

Implement ImageList class and utils

This should facilitate the handling of a list of multiplexed images

legend with many elements is not fully visible

legend entries are cut off when there are too many unique elements (see image). there is maybe a way to illustrate all unique elements in multiple columns instead of just one.

Fix scale that expression is comparable across images

Rewrite plotCells that only masks can be displayed

Implement cellDist function

This function should return the mean pixel distance to the nearest cell-type, patch or whatever the user specifies.

Bug when setting `legend = NULL`

When setting legend = NULL, the individual image size is not correctly calculated.

Implement scale and normalize function

CytomapperShiny gating only applies to one ROI of the 6

Thanks for your great IMC analysis tools and we tried copy pasting the script from the IMC data analysis workflow website for cytomapperShiny and everything seems to work fine until we look at the number of cells labeled per patient. Our gated populations only apply to one ROI each, instead of applying to all ROIs.

Number of cells labeled per patient

table(spe$cell_labels, spe$patient_id)

                             220525_segmentationkit_testonNASHmice_001

B cells 27
CD11b positive no F480 or Ly6G 0
CD31 endothelial cells 0
Cholangiocytes 0
Hepatocytes 0
Kupffer cells 0
LSECs 0
neutrophils 0
T cells 19
unlabeled 2547

                             220525_segmentationkit_testonNASHmice_002

B cells 0
CD11b positive no F480 or Ly6G 0
CD31 endothelial cells 0
Cholangiocytes 41
Hepatocytes 0
Kupffer cells 0
LSECs 0
neutrophils 0
T cells 0
unlabeled 2311

Are we supposed to download a given gate for each ROI in the shiny? Or did we need to edit the script to avoid this? Also, it would be really helpful if after you gate a population in the Shiny, the cells would be taken out of the gating scheme so you do not have this issue with doublets that you mention.

Thanks again for your help and support,
Best,
Tess

Allow multiple colour list entries even when colouring only one factor

As discovered by @SchulzDan it's not super intuitive to only supply a colour list that contains exactly the same entries as indicated by colour or outline.

Test if images that are being returned are numerically the same as EBImage output

Move legend to side of images

Switch to snapshot unit testing

We need to wait until the expect_snapshot_output of the testthat package makes it on CRAN.

Fix size of legend titles, image titles and scale_bar label

Add function to compensate images

Ported from here

Change loadImages functionality to always return an ImageList object

Keep metadata when compensating images

mcols(images) are currently lost.

separate container for 'Expression' colorbar in shiny

create a separate container for the legend that comes without zoom functionality.
i) this will allow increasing the size of the actual pseudo-color image
ii) makes the pseudo-color image interpretable while zooming (otherwise the colorbar info is not visible)

Reduce size of example files

Ideally, we want to have a folder smaller than 1MB

Expand plotCells and plotPixels to take extra arguments in "..."

Potentially change to ImagingExperiment class from Caridnal

We could build an "CyometryImagingExperiment" class
Or at least build an "CytometryImageList" class inherited from "ImageList" class of Cardinal

Fix subset_images parameter

plotPixels(image = pancreasImages, subset_images = 1) and
plotPixels(image = pancreasImages, subset_images = 1:3)
both work, but
plotPixels(image = pancreasImages, subset_images = 1:2)
plotPixels(image = pancreasImages, subset_images = 2:3)
return the error message:
Error in normalizeDoubleBracketSubscript(i, x, exact = exact, allow.NA = TRUE, : subscript is out of bounds

Tried with a larger dataset: subset_images works when subsetting an odd number of images but not when subsetting an even number

Allow/document cowplot/patchwork support

Currently, when return_plot = TRUE, the plots can be used in cowplot/patchwork when coercing them into a grob. But that doesn't look nice. So: find a better way to allow visualization with ggplot objects

Figure out why subset_images is slower than subsetting the list directly

add option to visualize densities in scatter plots in shiny

Write unit tests for all hidden functions

Compare to existing packages

Spaniel, IrisSpatialFeatures, Cardinal, imager, other?

Fix pattern argument in loadImages function

Make sure that regex matching is only applied to filenames, not paths