Cell Ranger

.title[
# Cell Ranger
]
.subtitle[
## Bioinformatics Resource Center, Rockefeller University
]
.author[
### .link-title[<a href="https://rockefelleruniversity.github.io/CellRanger/">Course Website</a>]
]
.author[
### .link-title[<a href="mailto:brc@rockefeller.edu" class="email">brc@rockefeller.edu</a>]
]

---

## Overview

- .link[[Course Home Page](http://rockefelleruniversity.github.io/CellRanger/)]
- .link[[Running Cell Ranger](https://rockefelleruniversity.github.io/CellRanger/presentations/singlepage/Session1.html#Cell_Ranger3)]
- .link[[Output Files](https://rockefelleruniversity.github.io/CellRanger/presentations/singlepage/Session1.html#Output_files)]
- .link[[Web Summary](https://rockefelleruniversity.github.io/CellRanger/presentations/singlepage/Session1.html#Web_Summary_QC)]

---
class: inverse, center, middle

# Set Up

---

## Materials

Links to material and slides for this course can be found on github.

* .link[[Cell Ranger](https://rockefelleruniversity.github.io/CellRanger/)]

Or can be downloaded as a zip archive from here.

* .link[[Download zip](https://github.com/rockefelleruniversity/CellRanger/zipball/master)]

---
## Course materials

Once the zip file in unarchived. All presentations as HTML slides and pages will be available in the directories underneath.

* **r_course/presentations/slides/**
Presentations as an HTML slide show.
* **r_course/presentations/singlepage/** 
Presentations as an HTML single page.

---
class: inverse, center, middle

# Cell Ranger

---

## Sample Prep

There are several single cell sequencing technologies. The most common is from 10X Genomics.

![overview](./imgs/drops.png)

---
## A scRNAseq workflow

We often need many tools across several computational languages to [analyze these complex experiments](https://rockefelleruniversity.github.io/SingleCell_Bootcamp/). Deciding what is appropriate often depends on the data set and its QC metrics. Our first step is nearly always to run Cell Ranger.

![overview](./imgs/advancedworkflow.png)

---
class: inverse, center, middle

# Cell Ranger

---

## Cell Ranger

.pull-left[
Cell Ranger is a suite of tools for single cell processing and analysis available from 10X Genomics. It performs key processing steps i.e. demultiplexing, conversion to FASTQ and mapping. It is also the first chance to delve into your data sets QC.

In this session we will give a brief overview of running this tool and then dive deeper into interpreting the outputs.
  ]
.pull-right[
![](./imgs/CellRangerPage.png)
  ]

---
## Do I need to run this?

- Often genomics centers will run it for you and deliver mtx/hdf5 files (i.e. here at Rockefeller)

- Why run Cell Ranger yourself?:
  * You want to integrate data sets, but they were processed by different versions of Cell Ranger
  * You may want to change Cell Ranger parameters i.e. export BAMs, or force an expected cell number
  * Most commonly you want to reanalyze a published data set

---
## Cell Ranger Download

- Cell Ranger is available from the .link[[10x genomics website](https://support.10xgenomics.com/single-cell-gene-expression/software/downloads/latest)]

- Also available are pre-baked references for Human and Mouse genomes (GRCh37/38 and GRCm37)

]
  
.pull-right[![](./imgs/CellRangerDownload.png)
  ]

---
## Cell Ranger

- Cell Ranger only runs on linux machines (CentOS/RedHat 7.0+ and Ubuntu 14.04+)
- Due to memory requirements, typically users run Cell Ranger on a remote server and not their own machines
- To download Cell Ranger and the required reference onto a remote server, we typically use the *wget* command (these commands are all on the [Download](https://support.10xgenomics.com/single-cell-gene-expression/software/downloads/latest) page)

[This will all be in terminal on the server you are using]

```shell
wget -O cellranger-8.0.0.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-8.0.0.tar.gz?Expires=1711772964&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA&Signature=muvzcbqxba6d-blyYS02MVfLlzwZk6iZNQWXdaoCLnl7owW2nEN-IHwSPwdNoYl-6Xia7rr0S1sLCUQTsekGm2pQKcd0kqK~ndHK0DM7SwSVpXLlRvBV5pXt~EIlsxATVBKVeQLnUy698N-WnRlT~ahjlU-nMdpomX9-lOkF~w8gbgHBdtPXunTWfW87sSJLpHMDVENSF7TFJsXERDwDnsXyQLCuEhfGTCOnupkaATlLEr9kaeCStePKkwGyqgi1m8Ua02NNGHWPIJ6I1mDt695wo~dgptpJF4SDNRTyE-TuXrHfIqRjZB60zhWRJczFo2kpL7FCKwliE-vJ6djcSw__"
```

Download reference genome for Cell Ranger i.e. Human genome (GRCh38)

```shell
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2024-A.tar.gz"
```

---
## Cell Ranger set-up

- Having downloaded the software and references, we can then unpack them.

```shell
tar -xzvf cellranger-8.0.0.tar.gz
tar -xzvf refdata-gex-GRCh38-2020-A.tar.gz
```

- Finally we can add the Cell Ranger directory to our PATH.

```shell
export PATH=/PATH_TO_CELLRANGER_DIRECTORY/cellranger-8.0.0:$PATH
```

---
## Running Cell Ranger count

Typically you will have FASTQ files from your experiment (or downloaded from a repository like GEO). These are likely to have been generated using the **Cell Ranger mkfastq** toolset to produce a directory of FASTQ files.

As we have the downloaded Cell Ranger software and required pre-build reference for Human (GRCh38) we can generate count data from the FASTQ files. This will make a count matrix and associated files.

```shell
cellranger count --id=my_run_name \
   --fastqs=PATH_TO_FASTQ_DIRECTORY \
   --transcriptome=/PATH_TO_CELLRANGER_DIRECTORY/refdata-gex-GRCh38-2020-A
   --create-bam=true
```

---
## Working with custom genomes

If you are working with a genome which is not Human and/or Mouse you will need to find another source for your Cell Ranger reference.

- Luckily many references are pre-built by other consortiums.
- We can build our own references using other tools in Cell Ranger using the *mkgtf* and *mkref* functions.
- For this you just need a FASTA file (DNA sequence) and a GTF file (Gene Annotation) for your reference.
- We have a more in-depth guide on how to do this in our .link[[scRNA-seq bootcamp](https://rockefelleruniversity.github.io/SingleCell_Bootcamp/)].

---

# Output files

---

## Outputs

Having completed the Cell Ranger count step, the user will have created a folder, with the name set by the **--id** flag from the count command.

Within this folder there will be the **outs/** directory which contains all the outputs generated from Cell Ranger count.

![](./imgs/outputs.png)

---
## Count Matrices

The count matrices which are needed for further analysis are stored in both MEX and HDF5 formats within the output directories.

The filtered matrix only contains detected, cell-associated barcodes whereas the raw contains all barcodes (background and cell-associated).

**MEX format**
- filtered_feature_bc_matrix
- raw_feature_bc_matrix

**HDF5 format**
- filtered_feature_bc_matrix.h5
- raw_feature_bc_matrix.h5

---
## BAM files

.pull-left[
The outs directory may also contain a BAM file of alignments for all barcodes against the reference _(possorted_genome_bam.bam)_ as well as an associated BAI index file _(possorted_genome_bam.bam.bai)_. This depends on whether you put true or false in the *--create-bam argument*. Older versions of Cell Ranger did not have this argument and would default to producing this BAM file.

This BAM file is sometimes used in downstream analysis such as scSplit/Velocyto as well as for the generation of signal graphs such as bigWigs.
  ]
  
.pull-right[

]

---
## Cloupe files

Cell Ranger also outputs _cloupe.cloupe_ files for visualization within the .link[[10X Loupe browser software](https://www.10xgenomics.com/support/software/loupe-browser/latest)].

This allows for the visualization of scRNA-seq/snRNA-seq as a t-sne/umap with the ability to overlay metrics of QC and gene expression onto the cells in real time.

---

# Web Summary QC

---

## QC outputs

Assessment of the overall quality of a scRNA-seq/snRNA-seq experiment after Cell Ranger can give our first chance to dig into the quality of your dataset and gain insight any issues we might face in data analysis.

---

## QC is essential

- Empty droplets
- Low quality cells (dead or dying)
- Ambient RNA contamination
- Doublets
  ]

.pull-right[
 <div align="center">
<img src="imgs/bad_cells.png" alt="igv" height="460" width="310">
<caption>Huemos et al. (2023)</caption>
</div>
  ]

---
## Metrics and Web Summary

Cell Ranger will also output summaries of useful metrics as a text file _(metrics_summary.csv)_ and as a intuitive web-page.

Metrics include

- Counts/UMIs per cell
- Number of cells detected
- Alignment quality
- Distribution of reads in genomic features
- Sequencing saturation
- t-sne/UMAP with default clustering

---
## Web Summary Example

We will be looking at the web summary generated from a PBMC dataset with ~1,000 cells from a healthy human donor. The full experiment details can be found on the 10X website .link[[here](https://www.10xgenomics.com/datasets/1-k-pbm-cs-from-a-healthy-donor-v-3-chemistry-3-standard-3-0-0)] and you can get a copy of a web summary from Cell Ranger version 8 .link[[here](./../../data/web_summary.html)].

[NOTE: Older web summaries contain largely the same information, but slightly different layout]
---

## Web Summary overview

.pull-left[
The web summary html file contains an interactive report describing the most essential QC for your single cell experiment as well as initial clustering and dimension reduction for your data.

The web summary also contains useful information on the input files and the versions used in this analysis for reproducibility.
  ]

.pull-left[
The first thing we can review is the **Run Summary** information panel. **(Top Left)**
As most people do not run Cell Ranger themselves this is important to check it matches expectations.

- Sample ID - Sample name (Assigned in **cellranger count**)
- Chemistry - The 10x chemistry used
- Include introns - Whether counting was run to include intronic counts (typical for single nucleus RNAseq, but also useful for scRNAseq)
- Pipeline Version - Version of Cell Ranger used

]

---
## Command Line Arguments

A corresponding section of the web summary is the Command Line Arguments used to run Cell Ranger. **(Bottom)**
Again this is an important section to double-check to make sure everything was run correctly.

- Input Path - Path to the input fastq files
- Reference Path and Transcriptome - References used in analysis

![](./imgs/websum5.png)

---
## Sequencing panel

.pull-left[
The **Sequencing** panel highlights information on the quality of the Illumina sequencing. **Top Right**.

- Number of reads - Total number of paired reads in library
- Number of Short Reads Skipped - Reads that were filtered out for being too short
- Valid Barcodes - Proportion of barcodes matching barcodes in whitelist (~ 740 thousand)
- Valid UMIs - Total number of UMIs that are not all one base and contain no unknown bases
- Sequencing saturation - Unique valid barcode/UMI versus all valid barcode/UMI
- Q30 scores - Assessment of sequencing qualities for barcode/UMI/RNA Reads

]

---
## Sequencing panel

Key Metrics we look for:

**Q30 Bases in RNA Read > 65% (usually > 80%)**

* Reflects the sequencing quality
  * Need to check with sequencing service supplier
		
**Sequencing Saturation > 40% (usually range 20% ~ 80%)**

* Reflects the complexity of libraries
  * Consider reconstructing library if too low

---
## Mapping panel

.pull-left[
The **Mapping** panel highlights information on the mapping of reads to the reference genome and transcriptome. **Bottom Left**

- Reads Mapped to Genome - Total mapped reads
- Reads Mapped Confidently to Genome - Uniquely mapped reads
- Reads Mapped Confidently to Exonic/Intronic/Intergenic - Uniquely mapped reads to specific regions
- Reads Mapped Confidently to Transcriptome - Reads mapped to a unique gene (and consistent with slice junctions)
- Reads Mapped Antisense to Gene - Reads mapped to the opposite strand of a gene
  ]

---
## Mapping panel

Key Metrics we look for:

**Mapped to Genome > 60% (usually range 50% ~ 90%)**

* Mapping rate to reference genome
  * Check reference genome version if too low

**Reads Mapped Confidently to Transcriptome > 30% (usually > 60%)**

* Reflection of annotation to transcriptome
  * Check annotation if too low

---
## Cells panel

.pull-left[
The **Cells** panel highlights some of the most important information in the report: the total number of cells captured and the distribution of counts across cells and genes. **Top Right**. Their importance is clear as several metrics are repeated and placed as the headline of the report.

- Estimated Number of Cells - Total number of barcodes associated to at least one cell.
- Mean Reads per cell -  Average reads in each cell
- Median Genes per Cell - Median number of genes detected (at least 1 count) per cell associated barcodes

]
.pull-right[
![](./imgs/websum6.png)
  ]

---
## Cells panel

.pull-left[
The **Cells** panel also has other metrics which help describe the depth and ambient RNA proportion. **Top Right**.

- Median Reads per Cell - Median number of transcriptome reads within cell associated barcodes
- Fraction Reads in Cells - Fraction of reads from valid barcode, associated to a cell and mapped to transcriptome
- Total Genes Detected - Number of genes with at least 1 count

]
  
.pull-right[
![](./imgs/websum6.png)
  ]
  
---
## Cells panel

Key Metrics we look for:

**Fraction Reads in Cells > 70% (usually > 85%)**

* Reflects the ambient RNA contamination
  * Consider correcting for ambient RNA if < 90%

**Median reads per cell > 20,000/cell and estimated number of cells 500 - 10,000**

* May be caused by the failure of cell identification
  * Need to check knee plot and re-evaluate cell number

---
## The Knee plot

The Cell panel also includes an interactive knee plot.

The knee plot shows:

- On the x-axis, the barcodes ordered by the most frequent on the left to the least frequent on the right

- On the y-axis, the frequency of each ordered barcode.

- Highlighted in dark blue are the barcodes marked as associated to cells.

]
  
.pull-right[
![](./imgs/websum6.png)
  ]

---
## Knee plot

It is apparent that barcodes labelled blue (cell-associated barcodes) do not have a cut-off just based on the UMI count.

In newer versions of Cell Ranger a two step process is used to define cell-associated barcodes based on the EmptyDrops method (Lun et al.,2019).

- First high RNA containing cells are identified based on a UMI cut-off.
- Second, low UMI containing cells are used as a background training set to identify additional cell-associated barcodes not called in first step.

If required, a **--force-cells** flag can be used with _cellranger count_ to identify a specific number of cell-associated barcodes.

]

---
## Knee plot

The Knee plot also acts a good QC tools to investigate differing types of single cell failure.

Whereas our previous knee plot represented a good sample, differing knee plot patterns can be indicative of specific problems with the single cell protocol. We will show you some examples of these below from real data.

---
## Knee plot

.pull-left[
In this example we see no specific cliff and knee suggesting a failure in the integration of oil, beads and samples (wetting failure) or a compromised sample.
  ]

---
## Knee plot

If there is a clog in the machine we may see a knee plot where the overall number of samples is low.

]
.pull-right[
![](./imgs/lowbarcode.png)
  ]

---
## Knee plot

There may be occasions where we see two sets of cliff-and-knees in our knee plot.

This could be indicative of a heterogenous sample where we have two populations of cells with differing overall RNA levels.

Knee plots should be interpreted in the context of the biology under investigation.

]
.pull-right[
![](./imgs/hetero.png)
  ]

---
## Knee plot

It is important to know what version and parameters were used to run Cell Ranger.

This cell calling step is continually updated and it can have a dramatic affect on your results. The .link[[Web Summary](https://cf.10xgenomics.com/samples/cell-exp/3.0.0/pbmc_1k_v3/pbmc_1k_v3_web_summary.html)] on 10X Genomics for this dataset is from Cell Ranger V3.0 if you want to compare.

Cell Ranger V8.0 was just released last month and, as with almost every prior version, there's been a change in default parameters.

---
## Gene Expression page

.pull-left[
The web-summary also contains an analysis page where default dimension reduction, clustering and differential expressions between clusters has been performed.

Additionally the analysis page contains information on sequencing saturation and gene per cell vs reads per cell.

]

---
## t-SNE and clustering

- Review for high and low UMI cells driving t-SNE structure and/or clustering.
- Expected separation between and structure across clusters may be observed within the t-SNE plot.
- Identify expected clusters based on expression of marker genes

]

---
## Sequence and Gene saturation

.pull-left[
The sequence saturation and Median genes per cell plots show these calculations (as show on summary page) over successive down sampling of the data.

By reviewing the curve of the down sampled metrics we can assess whether we are approaching saturation for either of these metrics.

]

.pull-right[
 <div align="center">
<img src="imgs/anal3.png" alt="igv" height="200" width="200">
</div>
 <div align="center">
<img src="imgs/anal4.png" alt="igv" height="200" width="200">
</div>
  ]

---
## QC issues going forward?

Early issues with QC can manifest in many ways downstream. This is from a published dataset:

---
## Next steps

Fingers crossed there's no QC issues.

Often at this step we wouldn't make any decisions unless there is a clear complete failure. This is an important first step in setting expectations/preparing for what you may need to do for the dataset.

---

## Back to the scRNAseq workflow

There are many tools both in R and python to dig further into QC and to tackle any analysis issues that arise. Many of these tools have pros and cons, but there is no one universal workflow for every dataset. We use a combination of Seurat, Bioconductor and python packages in our [typical analysis workflows](https://rockefelleruniversity.github.io/SingleCell_Bootcamp/).

![overview](./imgs/advancedworkflow.png)

---
## Extra Resources

- .link[[10X Genomics Website](https://www.10xgenomics.com/)]
- .link[[10X Genomics guide for Web Summaries](https://www.10xgenomics.com/support/single-cell-gene-expression/documentation/steps/sequencing/interpreting-cell-ranger-web-summary-files-for-single-cell-gene-expression-assays)]
- .link[[BRC Single Cell Analysis Bootcamp](https://rockefelleruniversity.github.io/SingleCell_Bootcamp/)]
  + A comprehensive guide to single cell analysis in R
  + Includes the use of Seurat, Bioconductor and other tools outside of the typical R framework.