In BodenmillerGroup/imcdatasets: Collection of publicly available imaging mass cytometry (IMC) datasets

knitr::opts_chunk$set(error=FALSE, warning=FALSE, message=FALSE,
    fig.retina = 0.75)
library(BiocStyle)

suppressPackageStartupMessages(c(
    library(SingleCellExperiment),
    library(cytomapper),
    library(imcdatasets)
))

Introduction

The r Biocpkg("imcdatasets") package provides access to publicly available datasets generated using imaging mass cytometry (IMC) [@Giesen-2014-IMC].

IMC is a technology that enables measurement of up to 50 markers from tissue sections at a resolution of 1 $\mu m$ @Giesen-2014-IMC. In classical processing pipelines, such as the ImcSegmentationPipeline or steinbock, the multichannel images are segmented to generate cells masks. These masks are then used to extract single cell features from the multichannel images.

Each dataset in imcdatasets is composed of three elements that can be retrieved separately:
1. Single-cell data in the form of a SingleCellExperiment or SpatialExperiment class object (named sce.rds).
2. Multichannel images in the form of a CytoImageList class object (named images.rds).
3. Cell segmentation masks in the form of a CytoImageList class object (named masks.rds).

Available datasets

The listDatasets() function returns all available datasets in imcdatasets, along with associated information. The FunctionCall column gives the name of the R function that enables to load the dataset.

datasets <- listDatasets()
datasets <- as.data.frame(datasets)
datasets$FunctionCall <- sprintf("`%s`", datasets$FunctionCall)
knitr::kable(datasets)

Retrieving data

Users can import the datasets by calling a single function and specifying the type of data to retrieve. The following examples highlight accessing an example dataset linked to the IMMUcan project.

Importing single-cell expression data and metadata

sce <- IMMUcan_2022_CancerExample("sce")
sce

Importing multichannel images

images <- IMMUcan_2022_CancerExample("images")
images

Importing cell segmentation masks

masks <- IMMUcan_2022_CancerExample("masks")
masks

On disk storage

Objects containing multi-channel images and segmentation masks can furthermore be stored on disk rather than in memory. Nevertheless, they need to be loaded into memory once before writing them to disk. This process takes longer than keeping them in memory but reduces memory requirements during downstream analysis.

To write images or masks to disk, set on_disk = TRUE and specify a path where images/masks will be stored as .h5 files:

# Create temporary location
cur_path <- tempdir()

masks <- IMMUcan_2022_CancerExample(data_type = "masks", on_disk = TRUE,
    h5FilesPath = cur_path)
masks

Dataset info and metadata

Additional information about each dataset is available in the help page:

?IMMUcan_2022_CancerExample

The metadata associated with a specific data object can be displayed as follows:

IMMUcan_2022_CancerExample(data_type = "sce", metadata = TRUE)
IMMUcan_2022_CancerExample(data_type = "images", metadata = TRUE)
IMMUcan_2022_CancerExample(data_type = "masks", metadata = TRUE)

Usage

The SingleCellExperiment class objects can be used for data analysis. For more information, please refer to the r Biocpkg("SingleCellExperiment") package and to the Orchestrating Single-Cell Analysis with Bioconductor workflow.

The CytoImageList class objects can be used for plotting cell and pixel information. Some typical use cases are given below. For more information, please see the r Biocpkg("cytomapper") package and the associated vignette.

Subsetting the images and masks

cur_images <- images[1:5]
cur_masks <- masks[1:5]

Plotting pixel information

The images objects can be used to display pixel-level data.

plotPixels(
    cur_images,
    colour_by = c("CD8a", "CD68", "CDH1"),
    bcg = list(
        CD8a = c(0,4,1),
        CD68 = c(0,5,1),
        CDH1 = c(0,5,1)
    )
)

Plotting cell information

The masks and sce objects can be combined to display cell-level data.

plotCells(
    cur_masks, object = sce,
    img_id = "image_number", cell_id = "cell_number",
    colour_by = c("CD8a", "CD68", "CDH1"),
    exprs_values = "exprs"
)

Outlining cells on images

Cell information can be displayed on top of images by combining the images, masks and sce objects.

plotPixels(
    cur_images, mask = cur_masks, object = sce,
    img_id = "image_number", cell_id = "cell_number",
    outline_by = "cell_type",
    colour_by = c("CD8a", "CD68", "CDH1"),
    bcg = list(
        CD8a  = c(0,5,1),
        CD68 = c(0,5,1),
        CDH1 = c(0,5,1)
    )
)