---
title: "Accessing IMC datasets"
date: "Created: 02 November 2020; Compiled: `r BiocStyle::doc_date()`"
package: "`r BiocStyle::pkg_ver('imcdatasets')`"
author:
- name: Nicolas Damond
  affiliation: [Department for Quantitative Biomedicine; University of Zurich, 
  Institute of Molecular Health Sciences; ETH Zurich]
  email: nicolas.damond@dqbm.uzh.ch
- name: Nils Eling
  affiliation: [Department for Quantitative Biomedicine; University of Zurich, 
  Institute of Molecular Health Sciences; ETH Zurich]
  email: nils.eling@dqbm.uzh.ch
output:
    BiocStyle::html_document:
        toc_float: yes
bibliography: "`r system.file('scripts', 'ref.bib', package='imcdatasets')`"
vignette: >
    %\VignetteIndexEntry{"Accessing IMC datasets"}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r style, echo=FALSE}
knitr::opts_chunk$set(error=FALSE, warning=FALSE, message=FALSE,
    fig.retina = 0.75)
library(BiocStyle)
```

```{r library, echo=FALSE, results='hide'}
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](https://github.com/BodenmillerGroup/ImcSegmentationPipeline) 
or [steinbock](https://bodenmillergroup.github.io/steinbock/latest/), 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.

```{r list-datasets}
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](https://immucan.eu/) project.

__Importing single-cell expression data and metadata__

```{r import-dataset}
sce <- IMMUcan_2022_CancerExample("sce")
sce
```

__Importing multichannel images__

```{r import-images}
images <- IMMUcan_2022_CancerExample("images")
images
```

__Importing cell segmentation masks__

```{r import-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:

```{r on_disk}
# 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:

```{r function-help}
?IMMUcan_2022_CancerExample
```

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

```{r access-metadata, eval = FALSE}
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](http://bioconductor.org/books/release/OSCA/) 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](https://www.bioconductor.org/packages/devel/bioc/vignettes/cytomapper/inst/doc/cytomapper.html).

__Subsetting the images and masks__

```{r usage-subset}
cur_images <- images[1:5]
cur_masks <- masks[1:5]
```

__Plotting pixel information__

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

```{r usage-pixel}
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.

```{r usage-cell}
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.

```{r usage-outline}
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)
    )
)
```

# Session info {.unnumbered}

```{r sessionInfo, echo=FALSE}
sessionInfo()
```

# References