--create-bam
parameter when executing the cellranger count
and cellranger multi
pipelines. This new parameter replaces the previously used --no-bam
option. All other arguments remain compatible with newer versions, unless otherwise specified.This tutorial describes how to run the cellranger multi
pipeline (we recommend completing the other Cell Ranger pipeline tutorials in this series first).
The example data used in this tutorial is for a 3' Cell Multiplexing dataset. In Cell Ranger v7.0 and later, Single Cell Fixed RNA Profiling datasets can be analyzed with the cellranger multi
pipeline as well. For specific multi
pipeline details and outputs, see:
In this tutorial, we will analyze a 3' Cell Multiplexing dataset that consists of two cell lines, Jurkat and Raji, multiplexed at equal proportions with one CMO per cell line, resulting in a pooled sample labeled with two CMOs. Gene Expression (GEX) and Cell Multiplexing libraries were prepared with the Chromium Next GEM Single Cell 3ΚΉ Reagent Kits v3.1 (Dual Index) with Feature Barcode technology.
Use wget
to download the FASTQ data (about 44 GB):
wget https://cg.10xgenomics.com/samples/cell-exp/6.0.0/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_Multiplex/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_Multiplex_fastqs.tar
As of this tutorial's publication, the most current reference transcriptome was the Human reference (GRCh38) - 2020-A. Download and decompress it:
wget https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz
tar -xf refdata-gex-GRCh38-2020-A.tar.gz
Decompress the FASTQ files:
tar -xf SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_Multiplex_fastqs.tar
Navigate to the FASTQ files and observe their filenames. There is one directory that contains the FASTQ files for the GEX library. There are two that contain FASTQ files for the Cell Multiplexing Capture library because the same physical library was sequenced twice for this particular dataset - first for a preliminary sample quality check and second for the actual analysis.
The simplest scenario is to analyze one Gene Expression and one Multiplexing Capture library, which we will demonstrate using the FASTQ files in the ..._1_gex
and ..._1_multiplexing_capture
directories.
.
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L001_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L001_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L001_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L001_R2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L002_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L002_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L002_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L002_R2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L003_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L003_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L003_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex_S2_L003_R2_001.fastq.gz
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L001_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L001_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L001_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L001_R2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L002_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L002_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L002_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L002_R2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L003_I1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L003_I2_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L003_R1_001.fastq.gz
β βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture_S1_L003_R2_001.fastq.gz
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture_S1_L001_I1_001.fastq.gz
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture_S1_L001_I2_001.fastq.gz
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture_S1_L001_R1_001.fastq.gz
βββ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture_S1_L001_R2_001.fastq.gz
The cellranger multi
pipeline has two inputs:
--id
is used to name the output directory that the pipeline runs in.--csv
takes a CSV file that points to the FASTQ files, and contains other parameters from the cellranger multi pipeline.
In this tutorial, you only need to edit a few lines in a pre-made CSV using a text editor of your choice. We are using the text editor nano
to edit the CSV:
nano SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K.csv
Copy and paste the code block below into your text editor. For this example, there are three sections: [gene-expression]
, [libraries]
, and [samples]
. Important: replace the /path/to/
text with the full paths to the reference (in [gene-expression]
section) and FASTQ files (in [libraries]
section) that you downloaded before saving the CSV file.
[gene-expression]
ref,/path/to/refdata-gex-GRCh38-2020-A
create-bam,true
[libraries]
fastq_id,fastqs,lanes,feature_types
SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex,/path/to/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex,any,Gene Expression
SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture,/path/to/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture,any,Multiplexing Capture
[samples]
sample_id,cmo_ids,description
Jurkat,CMO301,Jurkat
Raji,CMO302,Raji
Alternatively, download a multi config CSV template and customize it. Cell Ranger v7.1 enables users to download a multi config CSV template by running:
cellranger multi-template --output=/path/to/FILE.csv
Replace path above with the path to the directory in which you wish to output the template. Omitting the file path downloads the file into your working directory. After downloading, customize the template as shown above.
To print a list and description of all configurable parameters available in cellranger multi
, run:
cellranger multi-template --parameters
Learn more about the multi config CSV on the running cellranger multi
page, which also describes all the available sections, fields, and optional parameters.
Optional: If you want to analyze both sequence runs of the Multiplexing Capture library from this example dataset, add an additional line to the [libraries]
section for the 2nd sequence run:
[libraries]
fastq_id,fastqs,lanes,feature_types
SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex,/path/to/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K/ SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_gex,any,Gene Expression
SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture,/path/to/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_1_multiplexing_capture,any,Multiplexing Capture
SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture,/path/to/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K/SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K_2_multiplexing_capture,any,Multiplexing Capture
Next run the cellranger multi
command with --help
to get the usage and a full list of modifiable parameters.
cellranger multi --help
The output looks similar to this:
cellranger-multi
Analyze multiplexed data or combined gene expression/immune profiling/feature barcode data
USAGE:
cellranger multi [OPTIONS] --id <ID> --csv <CSV>
OPTIONS:
--id A unique run id and output folder name [a-zA-Z0-9_-]+
--description <TEXT> Sample description to embed in output files [default: ]
--csv <CSV> Path of CSV file enumerating input libraries and analysis parameters
--dry Do not execute the pipeline. Generate a pipeline invocation (.mro) file and stop
...
To run cellranger multi
, enter a command such as:
cellranger multi --id=Jurkat_Raji_10K --csv=SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K.csv
Cell Ranger 6.0+ should start with a message like this:
Martian Runtime - v4.0.8
Running preflight checks (please wait)...
Depending on your computational resources, it may take some time for the pipeline to complete. When it does, it should conclude with a message like this:
Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
2022-05-09 19:20:44 Shutting down.
Next, examine the output files using the tree
command:
cd Jurkat_Raji_10K/outs
tree
The tree
command will list 73 directories with 96 files. (If you are used to a cellranger count
run, recall that multiplexing two samples necessitates doubling the per-sample outputs, and these numbers will grow correspondingly as more samples are multiplexed into a single GEM well). Additionally, some output files are general to the entire experiment rather than a specific CMO.
The first section of the outputs contains the config.csv
file, a duplicate of the input config CSV (SC3_v3_NextGem_DI_CellPlex_Jurkat_Raji_10K.csv
). The multi
directory contains a count
directory and a multiplexing_analysis
directory:
ββ config.csv
ββ multi
βββ count
β βββ feature_reference.csv
β βββ raw_cloupe.cloupe
β βββ raw_feature_bc_matrix
β β βββ barcodes.tsv.gz
β β βββ features.tsv.gz
β β βββ matrix.mtx.gz
β βββ raw_feature_bc_matrix.h5
β βββ raw_molecule_info.h5
β βββ unassigned_alignments.bam
β βββ unassigned_alignments.bam.bai
βββ multiplexing_analysis
βββ assignment_confidence_table.csv
βββ cells_per_tag.json
βββ tag_calls_per_cell.csv
βββ tag_calls_summary.csv
For more information on these files, see Cell Multiplexing Outputs.
The per_sample_outs
directory contains two directories, one for Jurkat
and one for Raji
. For brevity, only the Jurkat outputs are shown here.
In the Jurkat/count/analysis
directory, the clustering
directory contains CSV files with the results of graph-based clusters and K-means clustering from 2-10:
βββ clustering
βββ graphclust
β βββ clusters.csv
βββ kmeans_10_clusters
β βββ clusters.csv
βββ kmeans_2_clusters
β βββ clusters.csv
βββ kmeans_3_clusters
β βββ clusters.csv
βββ kmeans_4_clusters
β βββ clusters.csv
βββ kmeans_5_clusters
β βββ clusters.csv
βββ kmeans_6_clusters
β βββ clusters.csv
βββ kmeans_7_clusters
β βββ clusters.csv
βββ kmeans_8_clusters
β βββ clusters.csv
βββ kmeans_9_clusters
βββ clusters.csv
The diffexp
directory likewise contains CSV files with the results of differential expression analysis between the clusters reported above:
βββ diffexp
βββ graphclust
β βββ differential_expression.csv
βββ kmeans_10_clusters
β βββ differential_expression.csv
βββ kmeans_2_clusters
β βββ differential_expression.csv
βββ kmeans_3_clusters
β βββ differential_expression.csv
βββ kmeans_4_clusters
β βββ differential_expression.csv
βββ kmeans_5_clusters
β βββ differential_expression.csv
βββ kmeans_6_clusters
β βββ differential_expression.csv
βββ kmeans_7_clusters
β βββ differential_expression.csv
βββ kmeans_8_clusters
β βββ differential_expression.csv
βββ kmeans_9_clusters
βββ differential_expression.csv
The pca
, tsne
, and, umap
directories contain CSV files for dimensionality reduction:
βββ pca
β βββ 10_components
β βββ components.csv
β βββ dispersion.csv
β βββ features_selected.csv
β βββ projection.csv
β βββ variance.csv
βββ tsne
β βββ 2_components
β β βββ projection.csv
β βββ multiplexing_capture_2_components
β βββ projection.csv
βββ umap
βββ 2_components
β βββ projection.csv
βββ multiplexing_capture_2_components
βββ projection.csv
The remaining per_sample_outs
are described in the Cell Multiplexing Outputs.
βββ sample_cloupe.cloupe
βββ feature_reference.csv
βββ sample_alignments.bam
βββ sample_alignments.bam.bai
βββ sample_filtered_barcodes.csv
βββ sample_filtered_feature_bc_matrix
β βββ barcodes.tsv.gz
β βββ features.tsv.gz
β βββ matrix.mtx.gz
βββ sample_filtered_feature_bc_matrix.h5
βββ sample_molecule_info.h5
βββ metrics_summary.csv
βββ web_summary.html
Questions or feedback about this tutorial? Contact [email protected].