10x Genomics Support/Cell Ranger/Tutorials/

Running Cell Ranger vdj

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

In this tutorial, we will work with the Human B cells dataset from a Healthy Donor (1k cells).

Watch a short video tutorial or follow the text instructions below.

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-vdj-practice/ and cd into that folder:

mkdir dataset-vdj-practice/ cd dataset-vdj-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.

Decompress 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 right place by running the ls command; the working directory should have a folder called sc5p_v2_hs_B_1k_multi_5gex_b_Multiplex_fastqs )

Download the V(D)J reference in the working directory:

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

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 vdj in the runs/ directory.

After downloading the FASTQ files and a V(D)J reference transcriptome, you are ready to run cellranger vdj.

Print the usage statement to get a list of all the options:

user_prompt$ cellranger vdj --help cellranger-vdj Assembles single-cell VDJ receptor sequences from 10x Immune Profiling libraries USAGE: cellranger vdj [FLAGS] [OPTIONS] --id FLAGS: --denovo Run in reference-free mode (do not use annotations) --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: ] --reference Path of folder containing 10x-compatible VDJ reference. Optional if '--denovo' is specified --fastqs ... Path to input FASTQ data --project Name of the project folder within a mkfastq or bcl2fastq-generated folder from which to pick FASTQs ....

Options used in this tutorial

This tutorial assumes that the cellranger vdj run is being executed in the working-directory/runs/ directory. Maintaining the folder structure described in this tutorial is essential to execute code without path modifications.
--idThe id argument must be a unique run ID. We will call this run HumanB_Cell based on the sample type in the example dataset.
--referencea path that points at the V(D)J reference transcriptome. Path can be absolute or relative. In this example, the V(D)J reference is in the refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0/ directory located within the working directory. The relative path to the V(D)J reference from the runs directory should look like this ../refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0
--fastqsthe fastqs argument requires a path to the directory containing FASTQ files. In this example, the FASTQs are in the dataset-vdj-practice/sc5p_v2_hs_B_1k_multi_5gex_b_fastqs/ directory. The relative path to this directory should be ../dataset-vdj-practice/sc5p_v2_hs_B_1k_multi_5gex_b_fastqs/sc5p_v2_hs_B_1k_b_fastqs
--samplethe sample name as specified in the sample sheet supplied to mkfastq. Typically, it is the prefix string common to all FASTQ files for one sample. In this example, the sample name should be sc5p_v2_hs_B_1k_b
--localcoresthe localcores flag tells cellranger vdj to use a specified number of cores. We will use 8 cores in this example.
--localmemthe localmem flag specifies the amount of memory (in GB) for cellranger vdj to allocate to this run. We will ask for 64 GB for this example run.

To learn more about all the cellranger vdj arguments, refer to the Running Pipelines section.

Watch a short video tutorial or follow the text instructions below.

Before running cellranger vdj, verify your directory structure:

. ├── dataset-vdj-practice │ └── sc5p_v2_hs_B_1k_multi_5gex_b_fastqs │ ├── sc5p_v2_hs_B_1k_5gex_fastqs │ └── sc5p_v2_hs_B_1k_b_fastqs ├── refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0 │ ├── fasta │ │ ├── regions.fa │ │ └── supp_regions.fa │ └── reference.json └── runs

From within the working-directory/runs/ directory, run cellranger vdj. If you have the same directory structure as this tutorial, you should be able to copy and paste this code into your command prompt (no need to type it out!). If you need to change file paths, the easiest way to customize code is by first pasting it into a text editor (e.g. TextEdit for MacOS). Then, you can copy and paste the customized code into your command prompt.

cellranger vdj --id=HumanB_Cell \ --reference=../refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0 \ --fastqs=../dataset-vdj-practice/sc5p_v2_hs_B_1k_multi_5gex_b_fastqs/sc5p_v2_hs_B_1k_b_fastqs \ --sample=sc5p_v2_hs_B_1k_b \ --localcores=8 \ --localmem=64 \

Refer to the Set up section above to understand the specific flags.

The run begins similar to this:

Serving UI at http://bespin1.fuzzplex.com:45033?auth=o5bjTf5rSJ1HDx-hX-bIBcMS4_7w9agaXXFcDNj1ulY Running preflight checks (please wait)... Checking sample info... Checking FASTQ folder... Checking reference... Checking reference_path (working-directory/refdata-cellranger-vdj-GRCh38-alts-ensembl-5.0.0) Checking inner enrichment primers... Checking chain... mrc: v4.0.6 mrp: v4.0.6 Anaconda: Python 3.8.2 numpy: 1.19.2 scipy: 1.6.2 pysam: h5py: 3.2.1

When the output of the cellranger vdj command says, “Pipestance completed successfully!”, the job is done:

Outputs: - Run summary HTML: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/web_summary.html - Run summary CSV: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/metrics_summary.csv - Clonotype info: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/clonotypes.csv - Filtered contig sequences FASTA: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/filtered_contig.fasta - Filtered contig sequences FASTQ: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/filtered_contig.fastq - Filtered contigs (CSV): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/filtered_contig_annotations.csv - All-contig FASTA: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig.fasta - All-contig FASTA index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig.fasta.fai - All-contig FASTQ: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig.fastq - Read-contig alignments: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig.bam - Read-contig alignment index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig.bam.bai - All contig annotations (JSON): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig_annotations.json - All contig annotations (BED): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig_annotations.bed - All contig annotations (CSV): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/all_contig_annotations.csv - Barcodes that are declared to be targetted cells: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/cell_barcodes.json - Clonotype consensus FASTA: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/consensus.fasta - Clonotype consensus FASTA index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/consensus.fasta.fai - Contig-consensus alignments: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/consensus.bam - Contig-consensus alignment index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/consensus.bam.bai - Clonotype consensus annotations (CSV): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/consensus_annotations.csv - Concatenated reference sequences: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/concat_ref.fasta - Concatenated reference index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/concat_ref.fasta.fai - Contig-reference alignments: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/concat_ref.bam - Contig-reference alignment index: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/concat_ref.bam.bai - Loupe V(D)J Browser file: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/vloupe.vloupe - V(D)J reference: fasta: regions: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/vdj_reference/fasta/regions.fa donor_regions: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/vdj_reference/fasta/donor_regions.fa reference: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/vdj_reference/reference.json - AIRR Rearrangement TSV: /mnt/deck7/working-directory/runs/HumanB_Cell/outs/airr_rearrangement.tsv - All contig info (ProtoBuf format): /mnt/deck7/working-directory/runs/HumanB_Cell/outs/vdj_contig_info.pb Waiting 6 seconds for UI to do final refresh. Pipestance completed successfully!

Watch a short video tutorial or follow the text instructions below.

A successful cellranger vdj run produces a new directory called HumanB_Cell/ (based on the --id flag specified during the run). The contents of the HumanB_Cell/ directory:

── runs └── HumanB_Cell ├── _cmdline ├── _filelist ├── _finalstate ├── _invocation ├── _jobmode ├── _log ├── _mrosource ├── outs ├── _perf ├── SC_VDJ_ASSEMBLER_CS ├── _sitecheck ├── _tags ├── _timestamp ├── _uuid ├── vdj_test.mri.tgz ├── _vdrkill └── _versions

The outs/ directory contains all important output files generated by the cellranger vdj pipeline.

── runs └── HumanB_Cell └──outs ├── airr_rearrangement.tsv ├── 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 ├── cell_barcodes.json ├── clonotypes.csv ├── concat_ref.bam ├── concat_ref.bam.bai ├── concat_ref.fasta ├── concat_ref.fasta.fai ├── consensus_annotations.csv ├── consensus.bam ├── consensus.bam.bai ├── consensus.fasta ├── consensus.fasta.fai ├── filtered_contig_annotations.csv ├── filtered_contig.fasta ├── filtered_contig.fastq ├── metrics_summary.csv ├── vdj_contig_info.pb ├── vdj_reference │ ├── fasta │ │ ├── donor_regions.fa │ │ └── regions.fa │ └── reference.json ├── vloupe.vloupe └── web_summary.html