Cell Ranger7.1, printed on 12/21/2024
In this tutorial, you will:
To follow along, you must:
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.
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
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.
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
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.
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.
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
....
| 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 |
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!
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