1.1 At a glance

To run chetah on an input count matrix input_counts with t-SNE¹ coordinates in input_tsne, and a reference count matrix ref_counts with celltypes vector ref_ct, run:

## Make SingleCellExperiments
reference <- SingleCellExperiment(assays = list(counts = ref_counts),
                                     colData = DataFrame(celltypes = ref_ct))

input <- SingleCellExperiment(assays = list(counts = input_counts),
                              reducedDims = SimpleList(TSNE = input_tsne))

## Run CHETAH
input <- CHETAHclassifier(input = input, ref_cells = reference)

## Plot the classification
PlotCHETAH(input)

## Extract celltypes:
celltypes <- input$celltype_CHETAH

A tumor micro-environment reference dataset containing all major cell types for tumor data can be downloaded: here. This reference can be used for all (tumor) input datasets.

4.1 Required data

If you have your data stored as SingleCellExperiments, continue to the next step. Otherwise, you need the following data before you begin:

• input scRNA-seq count data of the cells to be classified
  • a data.frame or matrix, with cells in the columns and genes in the rows
• (!) normalized scRNA-seq count data of reference cells
  • in similar format as the input
• the cell types of the reference cells
  • a named character vector (names corresponding to the colnames of the reference counts)
• (optional) a 2D reduced dimensional representation of your input data for visualization: e.g. t-SNE¹, PCA.
  • a two-column matrix/data.frame, with the cells in the rows and the two dimensions in the columns

As an example on how to prepare your data, we will use melanoma input data from Tirosh et al. and head-neck tumor reference data from Puram et al. as an example.

## To prepare the data from the package's internal data, run:
celltypes_hn <- headneck_ref$celltypes
counts_hn <- assay(headneck_ref)
counts_melanoma <- assay(input_mel)
tsne_melanoma <- reducedDim(input_mel)

## The input data: a Matrix
class(counts_melanoma)
#> [1] "dgCMatrix"
#> attr(,"package")
#> [1] "Matrix"
counts_melanoma[1:5, 1:5]
#> 5 x 5 sparse Matrix of class "dgCMatrix"
#>              mel_cell1 mel_cell2 mel_cell3 mel_cell4 mel_cell5
#> ELMO2           .         .         .         4.5633    .     
#> PNMA1           .         4.3553    .         .         .     
#> MMP2            .         .         .         .         .     
#> TMEM216         .         .         .         .         5.5624
#> TRAF3IP2-AS1    2.1299    4.0542    2.4209    1.6531    1.3144

## The reduced dimensions of the input cells: 2 column matrix
tsne_melanoma[1:5, ]
#>               tSNE_1    tSNE_2
#> mel_cell1  4.5034553 13.596680
#> mel_cell2 -4.0025667 -7.075722
#> mel_cell3  0.4734054  9.277648
#> mel_cell4  3.2201815 11.445236
#> mel_cell5 -0.3354758  5.092415
all.equal(rownames(tsne_melanoma), colnames(counts_melanoma))
#> [1] TRUE

## The reference data: a Matrix
class(counts_hn)
#> [1] "matrix"
counts_hn[1:5, 1:5]
#>              hn_cell1 hn_cell2 hn_cell3 hn_cell4 hn_cell5
#> ELMO2         0.00000        0  0.00000  1.55430   4.2926
#> PNMA1         0.00000        0  0.00000  4.55360   0.0000
#> MMP2          0.00000        0  7.02880  4.50910   6.3006
#> TMEM216       0.00000        0  0.00000  0.00000   0.0000
#> TRAF3IP2-AS1  0.14796        0  0.65352  0.28924   3.6365

## The cell types of the reference: a named character vector
str(celltypes_hn)
#>  Named chr [1:180] "Fibroblast" "Fibroblast" "Fibroblast" "Fibroblast" ...
#>  - attr(*, "names")= chr [1:180] "hn_cell1" "hn_cell2" "hn_cell3" "hn_cell4" ...
    
## The names of the cell types correspond with the colnames of the reference counts:
all.equal(names(celltypes_hn), colnames(counts_melanoma)) 
#> [1] "Lengths (180, 150) differ (string compare on first 150)"
#> [2] "150 string mismatches"

4.2 SingleCellExperiments

CHETAH expects data to be in the format of a SingleCellExperiment, which is an easy way to store different kinds of data together. Comprehensive information on this data type can be found here.

A SingleCellExperiment holds three things:

• counts: assays
  • as a list of Matrices
• meta-data: colData
  • as DataFrames
• reduced dimensions (e.g. t-SNE, PCA): ReducedDims
  • as a SimpleList of 2-column data.frames or matrices

CHETAH needs

• a reference SingleCellExperiment with:
  • an assay
  • a colData column with the corresponding cell types (default “celltypes”)
• an input SingleCellExperiment with:
  • an assay
  • a reducedDim (e.g. t-SNE)

For the example data, we would make the two objects by running:

## For the reference we define a "counts" assay and "celltypes" metadata
headneck_ref <- SingleCellExperiment(assays = list(counts = counts_hn),
                                     colData = DataFrame(celltypes = celltypes_hn))

## For the input we define a "counts" assay and "TSNE" reduced dimensions
input_mel <- SingleCellExperiment(assays = list(counts = counts_melanoma),
                                  reducedDims = SimpleList(TSNE = tsne_melanoma))

5.1 The output

CHETAH returns the input object, but added:

• input$celltype_CHETAH
  • a named character vector that can directly be used in any other workflow/method.
• “hidden” int_colData and int_metadata, not meant for direct interaction, but
  • which can all be viewed and interacted with using: PlotCHETAH and CHETAHshiny

5.2 Standard plots

CHETAH’s classification can be visualized using: PlotCHETAH. This function plots both the classification tree and the t-SNE (or other provided reduced dimension) map.
Either the final types or the intermediate types are colored in these plots. The non-colored types are represented in a grayscale.

To plot the final types:

PlotCHETAH(input = input_mel)

Conversely, to color the intermediate types:

PlotCHETAH(input = input_mel, interm = TRUE)

If you would like to use the classification, and thus the colors, in another package (e.g. Seurat²), you can extract the colors using:

colors <- PlotCHETAH(input = input_mel, return_col = TRUE)

5.3 CHETAHshiny

The classification of CHETAH and other outputs like profile and confidence scores can be visualized in a shiny application that allows for easy and interactive analysis of the classification.

Here you can view:

• the confidence of all assignments
• the classification in an interactive window
• the genes used by CHETAH, an it’s expression in the input data
• a lot more

The following command will open the shiny application as in an R window. The page can also be opened in your default web-browser by clicking “Open in Browser” at the very top.

CHETAHshiny(input = input_mel)

6.1 Confidence score

CHETAH calculates a confidence score for each assignment of an input cell to one of the branches of a node.
The confidence score:

• has a value between 0 and 2
• will normally lie between 0 and 1
• 0 represents no confidence for an assignment, 1 high confidence.

The default confidence threshold of CHETAH is 0.1.
This means that whenever a cell is assigned to a branch and the confidence of that assignment is lower than 0.1, the classification will stop in that node.

The confidence threshold can be adjusted in order to classify more or fewer cells to a final type:

• Using a confidence threshold of 0 will classify all input cells to a final type. Be aware that this classification can be noisy and can contain incorrect classifications.
  
• Using a threshold of 0.2, 0.3, 0.4, etc, will classify a decreasing number of cells to a final type, with the remaining cells having a increasingly high confidence throughout all nodes in the tree.

For example, to only classify cells with very high confidence:

input_mel <- Classify(input = input_mel, 0.8)
PlotCHETAH(input = input_mel, tree = FALSE)

Conversely, to classify all cells:

input_mel <- Classify(input_mel, 0)
PlotCHETAH(input = input_mel, tree = FALSE)

6.2 Renaming types

For renaming types in the tree, CHETAH comes with the RenameBelowNode function. This can be interesting when you are more interested in the general types, type in the different intermediate and final types.

For the example data, let’s say that we are not interested in all the different subtypes of T-cells (under Node6 and Node7), we can name all these cells “T cells” by running:

input_mel <- RenameBelowNode(input_mel, whichnode = 6, replacement = "T cell")
PlotCHETAH(input = input_mel, tree = FALSE)

To reset the classification to its default, just run Classify again:

input_mel <- Classify(input_mel) ## the same as Classify(input_mel, 0.1)
PlotCHETAH(input = input_mel, tree = FALSE)

7.1 Step 0: Obtain a reference.

• Download or use one of your own scRNA-seq datasets, for which cell type labels are available.
  • A tumor micro-environment reference dataset containing all major cell types for tumor data can be downloaded here
• Make a SingleCellExperiment object, as explained above

7.2 Step 1: good reference characteristics

CHETAH can use any scRNA-seq reference, but the used reference greatly influences the classification.
The following general rules apply on choosing and creating a reference:

• Better results can be achieved by using a reference and an input dataset that are from the same biological type, or at least consist of cells that are in the same cell state. E.g. for an input dataset of PBMCs, a bone marrow reference dataset could be used, but as these cells are more naive or precursor cells, this might negatively influence the classification. In this case, another PBMC dataset would work optimally.
• The annotation of the reference directly influences the classification. The more accurate the cell type labels, the better the classification. Also, discard any cells that are doublets, contaminations, etc.
• The sparser the reference data, the more reference cells are needed to create a reliable reference. For high coverage Smart-Seq2³ data, as little as 10-20 cells are needed per cell type. For sparser 10X Genomics data, 100+ cells normally gives optimal results.

cell_selection <- unlist(lapply(unique(ref$celltypes), function(type) {
    type_cells <- which(ref$celltypes == type)
    if (length(type_cells) > 200) {
        type_cells[sample(length(type_cells), 200)]
    } else type_cells
}))
ref_new <- ref[ ,cell_selection]

7.3 Step 1: normalization

CHETAH does not require normalized input data, but the reference data has to be normalized beforehand. The reference data that is used in this vignette is already normalized. Only for sake of the example, we use this dataset anyway to perform nomalization:

assay(headneck_ref, "counts") <- apply(assay(headneck_ref, "counts"), 2, function(column) log2((column/sum(column) * 100000) + 1))

7.4 Step 2: discaring of house-keeping genes

Certainly with reference with relatively high drop-out rates, CHETAH can be influenced by highly expressed, and thus highly variable, genes. In our experience, mainly ribosomal protein genes can cause such an effect. We therefore delete these genes, using the “ribosomal” list from here

ribo <- read.table("~/ribosomal.txt", header = FALSE, sep = '\t')
headneck_ref <- headneck_ref[!rownames(headneck_ref) %in% ribo[,1], ]

7.5 Step 3: Reference QC

The performance of CHETAH is heavily dependent on the quality of the reference.
The quality of the reference is affected by:

1. the quality of the scRNA-seq data
2. the accuracy of the cell type labels

To see how well CHETAH can distinguish between the cell types in a reference,
CorrelateReference and more importantly ClassifyReference can be run.

CorrelateReference(ref_cells = headneck_ref)
#> Running... in case of 1000s of cells, this may take a couple of minutes

7.5.2 ClassifyReference

Another check to see whether CHETAH can distinguish between the cell types in the reference is ClassifyReference. This function uses the reference to classify the reference itself. If CHETAH works well with the reference, there should be almost no mix-ups in the classification, i.e. all cells of type A should be classified to type A.

ClassifyReference(ref_cells = headneck_ref)
#> Preparing data....
#> Running analysis...

In this plot, the rows are the original cell type labels, the columns the labels that were assigned during classification. The colors and sizes of the squares indicate which part of the cells of the row name type are classified to the column type. E.g. 4th row, 2th column shows that 5-10% of CD4 T cells are classified as regulatory T cells.

In this reference, there is never more than 10% mix-up between two cell types. In addition, a low percentage of cells is classified as an intermediate type. Most mix-ups occur between subtypes of T cells. In this case the user should be aware that these cell type labels have the highest chance to interchange.