In ellispatrick/SegmentedCellExperiment: S4 Class for segmented spatial 'omics data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(BiocStyle)

A SegmentedCellExperiment is an object designed to store data from imaging cytometry (FISH, IMC, CycIF, spatial transcriptomics, ... ) that has already been segmented and reduced to individual cells. A SegmentedCellExperiment extends DataFrame and defines methods that take advantage of DataFrame nesting to represent various elements of cell-based experiments with spatial orientation that are commonly encountered. This object is able to store information on a cell's spatial location, cellType, morphology, intensity of gene/protein marks as well as image level phenotype information. Ideally this type of data can be used for cell clustering, point process models or nearest neighbour analysis. Below we will consider a few examples of data formats that can be transformed into a SegmentedCellExperiment.

First, load the package.

library(SegmentedCellExperiment)
library(S4Vectors)

Example 1 - Data resembles cellProfiler output

Here we create a SegmentedCellExperiment from data that was output from cellProfiler or similar programs. This assumes that there are columns with the string AreaShape_ and Intensity_Mean and that there are ObjectNumber and ImageNumber columns.

Here we create toy cellProfiler data.

### Something that resembles cellProfiler data

set.seed(51773)

n = 10

cells <- data.frame(row.names = seq_len(n))
cells$ObjectNumber <- seq_len(n)
cells$ImageNumber <- rep(1:2,c(n/2,n/2))
cells$AreaShape_Center_X <- runif(n)
cells$AreaShape_Center_Y <- runif(n)
cells$AreaShape_round <- rexp(n)
cells$AreaShape_diameter <- rexp(n, 2)
cells$Intensity_Mean_CD8 <- rexp(n, 10)
cells$Intensity_Mean_CD4 <- rexp(n, 10)

We can then create a SegmentedCellExperiment object.

cellExp <- SegmentedCellExperiment(cells, cellProfiler = TRUE)
cellExp

Extract the location information and overwrite it as well.

loc <- location(cellExp)
head(loc)

location(cellExp) <- loc

We can then set the cell types of each cell by extracting and clustering marker intensity information.

intensities <- intensity(cellExp)
kM <- kmeans(intensities,2)
cellType(cellExp) <- paste('cluster',kM$cluster, sep = '')

loc <- location(cellExp)
head(loc)

Example 2 - Three pancreatic islets from from Damond et al (2019)

Read in data.

isletFile <- system.file("extdata","isletCells.csv", package = "SegmentedCellExperiment")
cells <- read.csv(isletFile)

head(colnames(cells))

We can then create a SegmentedCellExperiment object.

cellExp <- SegmentedCellExperiment(cells, cellProfiler = TRUE)
cellExp

We can then set the cell types of each cell by extracting and clustering marker intensity information.

intensities <- intensity(cellExp)
kM <- kmeans(intensities,4)
cellType(cellExp) <- paste('cluster',kM$cluster, sep = '')

loc <- location(cellExp)
head(loc)

Here is a very simple plot in ggplot showing the spatial distribution of the cell types

plot(cellExp, imageID=1)

Example 3 - Custom intensity and morphology column names

Here we create toy data that has a slightly more fluid naming stucture.

set.seed(51773)

n = 10

cells <- data.frame(row.names = seq_len(n))
cells$cellID <- seq_len(n)
cells$imageCellID <- rep(seq_len(n/2),2)
cells$imageID <- rep(1:2,c(n/2,n/2))
cells$x <- runif(n)
cells$y <- runif(n)
cells$shape_round <- rexp(n)
cells$shape_diameter <- rexp(n, 2)
cells$intensity_CD8 <- rexp(n, 10)
cells$intensity_CD4 <- rexp(n, 10)
cells$cellType <- paste('cluster',sample(1:2,n,replace = TRUE), sep = '_')

We can then create a SegmentedCellExperiment object.

cellExp <- SegmentedCellExperiment(cells, cellTypeString = 'cellType', intensityString = 'intensity_', morphologyString = 'shape_')
cellExp

Extract morphology information

morph <- morphology(cellExp)
head(morph)

Phenotype information

We can also include phenotype information for each image. Create some corresponding toy phenotype information which must have a imageID variable.

phenoData <- DataFrame(imageID = c('1','2'), age = c(21,81), status = c('dead','alive'))
phenotype(cellExp) <- phenoData
phenotype(cellExp)
phenotype(cellExp, expand = TRUE)

Example 4 - Minimal example, cells only have spatial coordinates

Here we generate data where we only know the location of each cell.

set.seed(51773)

n = 10

cells <- data.frame(row.names = seq_len(n))
cells$x <- runif(n)
cells$y <- runif(n)
cellExp <- SegmentedCellExperiment(cells)
cellExp