Software  ›   pipelines
If your question is not answered here, please email us at:  ${email.software}

10x Genomics
Chromium Single Cell Immune Profiling

V(D)J T Cell and B Cell Analysis with cellranger vdj

Cell Ranger's pipelines analyze sequencing data produced from Chromium single cell 5′ RNA-seq libraries. This involves the following steps:

  1. Run cellranger mkfastq on the Illumina BCL output folder to generate FASTQ files.

  2. Run cellranger vdj on FASTQ files produced by cellranger mkfastq.

For the following example, assume that the Illumina BCL output is in a folder named /sequencing/140101_D00123_0111_AHAWT7ADXX.

Run cellranger mkfastq

First, follow the instructions on running cellranger mkfastq to generate FASTQ files. For example, if the flowcell serial number was HAWT7ADXX, then cellranger mkfastq will output FASTQ files in HAWT7ADXX/outs/fastq_path.

Run cellranger vdj

To generate single-cell V(D)J sequences and annotations for a single library, run cellranger vdj with the following arguments. For a complete list of command-line arguments, run cellranger vdj --help. More options are described below this section.

ArgumentDescription
--idA unique run ID string: e.g. sample345
--fastqsPath of the FASTQ folder generated by cellranger mkfastq
e.g. /home/jdoe/runs/HAWT7ADXX/outs/fastq_path
Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flowcells.
Doing this will treat all reads from the library, across flowcells, as one sample.
If you have multiple libraries for the sample, you will need to run cellranger vdj using a custom MRO file as detailed on the Multi-Library Samples page.
--referencePath to the Cell Ranger V(D)J compatible reference e.g. /opt/refdata-cellranger-vdj-GRCh38-alts-ensembl-3.1.0. If --denovo is specified, this argument is optional.
--sampleSample name as specified in the sample sheet supplied to mkfastq.
Can take multiple comma-separated values, which is helpful if the sample was sequenced on multiple flowcells and the sample name used (and therefore fastq file prefix) is not identical between them.
Doing this will treat all reads from the library, across flowcells, as one sample.
If you have multiple libraries for the sample, you will need to run cellranger vdj using a custom MRO file as detailed on the Multi-Library Samples page.

Optional Arguments Intended for Use with Special Species

ArgumentDescription
--denovoDo not use the V(D)J reference during the assembly process. If specified, --reference is optional, however if --denovo is specified but --reference is not, then --inner_enrichment_primers must be specified. The --denovo option is most useful for full de novo assembly without a V(D)J reference. If you have a V(D)J reference, using --denovo will typically yield similar but slightly degraded results.
--inner-enrichment-primersName of a file containing primer sequences, one per line, that were used to enrich cDNA for V(D)J sequences. If there are two sets of primers, that should be the innermost reverse PCR primers, that are complementary to a constant region. For example for human TCR, the file having two lines:
AGTCTCTCAGCTGGTACACG
TCTGATGGCTCAAACACAGC

would be equivalent to the default primers (if this option were not specified). However normally this option is used only for species other than human or mouse for which primers are not provided by 10x Genomics. All the provided primers may be found here.

Optional Arguments That Throttle Compute Resources

ArgumentDescription
--localcoresRestricts cellranger to use the specified number of cores to execute pipeline stages. By default, cellranger will use all of the cores available on your system.
--localmemRestricts cellranger to use the specified amount of memory (in GB) to execute pipeline stages. By default, cellranger will use 90% of the memory available on your system.

Optional Arguments That Restrict the Input Dataset

ArgumentDescription
--lanesLanes associated with this sample
--indices(Deprecated. Only used for output from cellranger demux) Sample indices associated with this sample. Comma-separated list of:
  1. index set plate well: SI-3A-A1
  2. index sequences: TCGCCATA,GTATACAC

Optional Expert Arguments

ArgumentDescription
--force-cellsHere cells means targeted cells. If --force-cells is set to n, and more than n cells were detected, use only the n cells having the largest numbers of filtered UMIs. Use this in rare cases where the number of detected cells greatly exceeds the number of inputted cells, and is inconsistent with the barcode rank plot.

After determining these input arguments, run cellranger:

$ cd /home/jdoe/runs
$ cellranger vdj --id=sample345 \
                 --reference=/opt/refdata-cellranger-vdj-GRCh38-alts-ensembl-3.1.0 \
                 --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
                 --sample=mysample \
                 --localcores=8 \
                 --localmem=64 

Following a set of preflight checks to validate input arguments, cellranger vdj pipeline stages will begin to run:

Martian Runtime - v3.2.3
 
Running preflight checks (please wait)...
2017-04-15 14:23:52 [runtime] (ready)           ID.sample345.SC_VDJ_ASSEMBLER_CS.SC_VDJ_ASSEMBLER.SETUP_CHUNKS
2017-04-15 14:23:55 [runtime] (split_complete)  ID.sample345.SC_VDJ_ASSEMBLER_CS.SC_VDJ_ASSEMBLER.SETUP_CHUNKS
2017-04-15 14:23:55 [runtime] (run:local)       ID.sample345.SC_VDJ_ASSEMBLER_CS.SC_VDJ_ASSEMBLER.SETUP_CHUNKS.fork0.chnk0.main
...

By default, cellranger will use all of the cores available on your system to execute pipeline stages. You can specify a different number of cores to use with the --localcores option; for example, --localcores=16 will limit cellranger to using up to sixteen cores at once. Similarly, --localmem will restrict the amount of memory (in GB) used by cellranger.

The pipeline will create a new folder named with the sample ID you specified (e.g. /home/jdoe/runs/sample345) for its output. If this folder already exists, cellranger will assume it is an existing pipestance and attempt to resume running it.

Output Files

A successful cellranger vdj run should conclude with a message similar to this:

2017-04-15 14:32:18 [runtime] (join_complete)   ID.sample345.SC_VDJ_ASSEMBLER_CS.VLOUPE_PREPROCESS
 
Outputs:
- Run summary HTML:                                  /home/jdoe/runs/sample345/outs/web_summary.html
- Run summary CSV:                                   /home/jdoe/runs/sample345/outs/metrics_summary.csv
- All-contig FASTA:                                  /home/jdoe/runs/sample345/outs/all_contig.fasta
- All-contig FASTA index:                            /home/jdoe/runs/sample345/outs/all_contig.fasta.fai
- All-contig FASTQ:                                  /home/jdoe/runs/sample345/outs/all_contig.fastq
- Read-contig alignments:                            /home/jdoe/runs/sample345/outs/all_contig.bam
- Read-contig alignment index:                       /home/jdoe/runs/sample345/outs/all_contig.bam.bai
- All contig annotations (JSON):                     /home/jdoe/runs/sample345/outs/all_contig_annotations.json
- All contig annotations (BED):                      /home/jdoe/runs/sample345/outs/all_contig_annotations.bed
- All contig annotations (CSV):                      /home/jdoe/runs/sample345/outs/all_contig_annotations.csv
- Filtered contig sequences FASTA:                   /home/jdoe/runs/sample345/outs/filtered_contig.fasta
- Filtered contig sequences FASTQ:                   /home/jdoe/runs/sample345/outs/filtered_contig.fastq
- Filtered contigs (CSV):                            /home/jdoe/runs/sample345/outs/filtered_contig_annotations.csv
- Clonotype consensus FASTA:                         /home/jdoe/runs/sample345/outs/consensus.fasta
- Clonotype consensus FASTA index:                   /home/jdoe/runs/sample345/outs/consensus.fasta.fai
- Clonotype consensus FASTQ:                         /home/jdoe/runs/sample345/outs/consensus.fastq
- Concatenated reference sequences:                  /home/jdoe/runs/sample345/outs/concat_ref.fasta
- Concatenated reference index:                      /home/jdoe/runs/sample345/outs/concat_ref.fasta.fai
- Contig-consensus alignments:                       /home/jdoe/runs/sample345/outs/consensus.bam
- Contig-consensus alignment index:                  /home/jdoe/runs/sample345/outs/consensus.bam.bai
- Contig-reference alignments:                       /home/jdoe/runs/sample345/outs/concat_ref.bam
- Contig-reference alignment index:                  /home/jdoe/runs/sample345/outs/concat_ref.bam.bai
- Clonotype consensus annotations (JSON):            /home/jdoe/runs/sample345/outs/consensus_annotations.json
- Clonotype consensus annotations (CSV):             /home/jdoe/runs/sample345/outs/consensus_annotations.csv
- Clonotype info:                                    /home/jdoe/runs/sample345/outs/clonotypes.csv
- Barcodes that are declared to be targeted cells:   /home/jdoe/runs/sample345/out/cell_barcodes.json
- Loupe V(D)J Browser file:                          /home/jdoe/runs/sample345/outs/vloupe.vloupe
 
Pipestance completed successfully!

The output of the pipeline will be contained in a folder named with the sample ID you specified (e.g. sample345). The subfolder named outs will contain the main pipeline output files.

Once cellranger vdj has successfully completed, you can browse the resulting summary HTML file in any supported web browser, open the .vloupe file in Loupe V(D)J Browser, or refer to the Understanding Output section to explore the data by hand.