10x Genomics
Chromium Single Cell Immune Profiling
Cell Ranger7.1 (latest), printed on 11/21/2024
Joint Analysis of Gene Expression and V(D)J data
A tutorial on running the cellranger multi pipeline
Learning objectives
In this tutorial, you will:
- Get a brief introduction to Cell Ranger's multi pipeline
- Work with an example dataset
- Download example FASTQs
- Download the reference transcriptome and V(D)J reference
- Create a multi config CSV
- Set up the directory for running multi
- Set up the command for running multi
- Run the multi pipeline
- Generate and explore the output files
- Learn the next steps
Prerequisites
To follow along, you must:
- Have basic UNIX command line experience
- Fulfill these system requirements
- Download and install the Cell Ranger software
- Choose a compute platform
- Have access to a UNIX command prompt
Cell Ranger's multi pipeline
The cellranger multi pipeline takes FASTQ files from cellranger mkfastq, BCL Convert, or bcl2fastq for any combination of 5' single cell gene expression, Feature Barcode (cell surface protein or antigen) and V(D)J libraries from a single GEM well. It performs alignment, filtering, barcode counting, and UMI counting on the gene expression and/or Feature Barcode libraries. It also performs sequence assembly and paired clonotype calling on the V(D)J libraries. Additionally, the cell calls provided by the gene expression data are used to improve the cell calls inferred by the V(D)J library.
Example dataset
We will work with the Human B cells dataset from a Healthy Donor (1k cells). This dataset was sequenced with the following configuration:
Paired-end (26X90), dual-indexed sequencing. Read 1: 26 cycles, i7 index: 10 cycles, i5 index: 10 cycles, Read 2: 90 cycles
Download example FASTQs
Watch a short video tutorial or follow the text instructions below.
Video tutorial:
Text instructions:
Open up a terminal window. You may log in to a remote server or choose to perform the compute on your local machine. Refer to the System Requirements page for details.
In the working directory, create a new folder called dataset-multi-practice/ and cd into that folder:
mkdir dataset-multi-practice cd dataset-multi-practice
Download the input FASTQ files:
curl -LO https://cf.10xgenomics.com/samples/cell-vdj/6.0.0/sc5p_v2_hs_B_1k_multi_5gex_b_Multiplex/sc5p_v2_hs_B_1k_multi_5gex_b_Multiplex_fastqs.tar
A file named sc5p_v2_hs_B_1k_multi_5gex_b_Multiplex_fastqs.tar should appear in your directory when you list files with the ls command.
Uncompress the FASTQs:
tar -xf sc5p_v2_hs_B_1k_multi_5gex_b_Multiplex_fastqs.tar
You should now see a folder called sc5p_v2_hs_B_1k_multi_5gex_b_fastqs that contains two subfolders, sc5p_v2_hs_B_1k_5gex_fastqs and sc5p_v2_hs_B_1k_b_fastqs.
Navigate back to the working directory:
cd ..
Double check you are in the correct directory by running the ls command; the working directory should have the dataset-multi-practice folder.
Download the reference transcriptome and V(D)J reference
Watch a short video tutorial or follow the text instructions below.
Video tutorial:
Text instructions:
Download the pre-built human reference transcriptome to the working directory and uncompress it:
curl -O https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz tar -xf refdata-gex-GRCh38-2020-A.tar.gz
Next, download the pre-built V(D)J reference to the working directory and uncompress it:
curl -O https://cf.10xgenomics.com/supp/cell-vdj/refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0.tar.gz tar -xf refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0.tar.gz
Create a multi config CSV
Watch a short video tutorial or follow the text instructions below.
Video tutorial:
Text instructions:
In your working directory, create a new CSV file called multi_config.csv using your text editor of choice:
nano multi_config.csv
Copy and paste this text into the newly created file, and customize the code in red:
[gene-expression] reference,/jane.doe/working-directory/refdata-gex-GRCh38-2020-A expect-cells,1000 [vdj] reference,/jane.doe/working-directory/refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0 [libraries] fastq_id,fastqs,lanes,feature_types,subsample_rate sc5p_v2_hs_B_1k_5gex,/jane.doe/working-directory/dataset-multi-practice/sc5p_v2_hs_B_1k_multi_5gex_b_fastqs/sc5p_v2_hs_B_1k_5gex_fastqs,1|2,gene expression, sc5p_v2_hs_B_1k_b,/jane.doe/working-directory/dataset-multi-practice/sc5p_v2_hs_B_1k_multi_5gex_b_fastqs/sc5p_v2_hs_B_1k_b_fastqs,1|2,vdj,
Use your text editor's save command to save the file. In nano, save by typing → → .
A customizable multi config CSV template is available for download on the example dataset page, under the Input Files tab.
Set up the directory for running multi
Once you have all the necessary files, make a new directory called runs/ in your home directory:
mkdir runs/ cd runs/
You will run cellranger multi in the runs/ directory.
Set up the command for running multi
After downloading the FASTQ files, the reference transcriptome, and a V(D)J reference, you are ready to run cellranger multi.
Print the usage statement to get a list of all the options:
cellranger multi --help
The output should look similar to:
user_prompt$ cellranger multi --help
cellranger-multi
Analyze multiplexed data or combined gene expression/immune profiling/feature
barcode data
USAGE:
cellranger multi [FLAGS] [OPTIONS] --id --csv
FLAGS:
--dry Do not execute the pipeline. Generate a pipeline
invocation (.mro) file and stop
--disable-ui Do not serve the web UI
--noexit Keep web UI running after pipestance completes or fails
--nopreflight Skip preflight checks
-h, --help Prints help information
OPTIONS:
--id A unique run id and output folder name [a-zA-Z0-
9_-]+
--description Sample description to embed in output files
[default: ]
--csv Path of CSV file enumerating input libraries and
analysis parameters
--jobmode Job manager to use. Valid options: local
(default), sge, lsf, slurm or path to a
.template file. Search for help on "Cluster
Mode" at support.10xgenomics.com for more
details on configuring the pipeline to use a
compute cluster [default: local]
--localcores Set max cores the pipeline may request at one
time. Only applies to local jobs
....
Options used in this tutorial
| Option | Description |
|---|---|
| --id | The id argument must be a unique run ID. We will call this run HumanB_Cell_multi based on the sample type in the example dataset. |
| --csv | Path to the multi config CSV file enumerating input libraries and analysis parameters. Your multi_config.csv file is in the working directory. When executing cellranger multi from the runs directory, the relative path should be: ../multi_config.csv |
Run the multi pipeline
Watch a short video tutorial or follow the text instructions below.
Video tutorial:
Text instructions:
From within the working-directory/runs/ directory, run cellranger multi
cellranger multi --id=HumanB_Cell_multi --csv=../multi_config.csv
The run begins similar to this:
user_prompt$ cellranger multi --id=HumanB_Cell_multi --csv=/jane.doe/working-directory/multi_config.csv Martian Runtime - v4.0.6 Serving UI at http://bespin1.fuzzplex.com:43129?auth=tIgY0u8ax70yeWhWKF61SkSgJDKvOIgZ-yjxYNJXXtY Running preflight checks (please wait)... 2022-01-06 16:36:56 [runtime] (ready) ID.HumanB_Cell_multi.SC_MULTI_CS.PARSE_MULTI_CONFIG 2022-01-06 16:36:56 [runtime] (run:hydra) ID.HumanB_Cell_multi.SC_MULTI_CS.PARSE_MULTI_CONFIG.fork0.chnk0.main 2022-01-06 16:37:26 [runtime] (chunks_complete) ID.HumanB_Cell_multi.SC_MULTI_CS.PARSE_MULTI_CONFIG 2022-01-06 16:37:26 [runtime] (ready) ID.HumanB_Cell_multi.SC_MULTI_CS.SC_MULTI_CORE.MULTI_CHEMISTRY_DETECTOR._GEM_WELL_CHEMISTRY_DETECTOR.DETECT_COUNT_CHEMISTRY 2022-01-06 16:37:26 [runtime] (run:hydra) ID.HumanB_Cell_multi.SC_MULTI_CS.SC_MULTI_CORE.MULTI_CHEMISTRY_DETECTOR._GEM_WELL_CHEMISTRY_DETECTOR.DETECT_COUNT_CHEMISTRY.fork0.chnk0.main ....
When the output of the cellranger multi command says, “Pipestance completed successfully!”, the job is done:
web_summary: /jane.doe/working-directory/runs/HumanB_Cell_multi/outs/per_sample_outs/HumanB_Cell_multi/web_summary.html
metrics_summary: /jane.doe/working-directory/runs/HumanB_Cell_multi/outs/per_sample_outs/HumanB_Cell_multi/metrics_summary.csv
}
Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
Generate and explore the output files
Watch a short video tutorial or follow the text instructions below.
Video tutorial:
Text instructions:
A successful cellranger multi run produces a new directory called HumanB_Cell_multi/ (based on the --id flag specified during the run). The contents of the HumanB_Cell_multi/ directory:
── runs
└── HumanB_Cell_multi
├── _cmdline
├── _filelist
├── _finalstate
├── HumanB_Cell_multi.mri.tgz
├── _invocation
├── _jobmode
├── _log
├── _mrosource
├── outs/
├── _perf
├── SC_MULTI_CS/
├── _sitecheck
├── _tags
├── _timestamp
├── _uuid
├── _vdrkill
└── _versions
The outs/ directory contains all important output files generated by the cellranger multi pipeline:
── runs
└── HumanB_Cell_multi
└──outs
├── config.csv
├── multi
│ ├── count
│ │ ├── raw_cloupe.cloupe
│ │ ├── raw_feature_bc_matrix
│ │ ├── raw_feature_bc_matrix.h5
│ │ ├── raw_molecule_info.h5
│ │ ├── unassigned_alignments.bam
│ │ └── unassigned_alignments.bam.bai
│ └── vdj_b
│ ├── all_contig_annotations.bed
│ ├── all_contig_annotations.csv
│ ├── all_contig_annotations.json
│ ├── all_contig.bam
│ ├── all_contig.bam.bai
│ ├── all_contig.fasta
│ ├── all_contig.fasta.fai
│ └── all_contig.fastq
├── per_sample_outs
│ └── HumanB_Cell_multi
│ ├── count
│ ├── metrics_summary.csv
│ ├── vdj_b
│ └── web_summary.html
└── vdj_reference
├── fasta
│ ├── donor_regions.fa
│ └── regions.fa
└── reference.json
Next steps
- Check the multi web_summary.html page to see results of the experiment.
- Load the cloupe.cloupe file into the Loupe Browser and start an analysis.
- Load the vloupe.vloupe file into the Loupe V(D)J Browser and start an analysis.
- Refer to the cellranger multi Understanding Outputs section for detailed explanation of output files.