Software  ›   pipelines
If your question is not answered here, please email us at:  support@10xgenomics.com

10x Genomics
Chromium Single Cell Gene Expression

Cell Ranger Installation

Cell Ranger is delivered as a single, self-contained tar file that can be unpacked anywhere on your system. It bundles all of its own required software dependencies, which are pre-compiled to run on a wide range of Linux distributions.

For convenience, the reference data package required for Cell Ranger is provided as a separate download.

Download and Install

Step 1 – Download and unpack the Cell Ranger file in any location. In this example we use /opt.

$ cd /opt
[ download file from downloads page ]
$ tar -xzvf cellranger-1.0.1.tar.gz

This unpacks Cell Ranger, its dependencies, and the cellranger script into a new directory called cellranger-1.0.1.

Step 2 – Download and unpack the reference data file in a convenient location:

[ download file from downloads page ]
$ tar -xzvf refdata-cellranger-1.0.0.tar.gz

This creates a new directory called refdata-cellranger-1.0.0 that contains multiple references, including hg19, mm10, ercc92 and a combined hg19 and mm10 reference for multi-species experiments. Each reference contains a set of pre-generated indices and other data required by Cell Ranger.

Step 3 – Prepend the Cell Ranger directory to your $PATH. This will allow you to invoke the cellranger command.

If you unpacked both Cell Ranger and the reference data into /opt, then you would run the following command:

$ export PATH=/opt/cellranger-1.0.1:$PATH

You may wish to add this command to your .bashrc for convenience.

Site Check Script

Next, please run the bundled site check script and send the output to 10x. We will review the information to ensure that Cell Ranger will run smoothly once you have generated your own Chromium data. Assuming you have installed Cell Ranger as described above, please run the following commands:

$ cellranger sitecheck > sitecheck.txt
$ cellranger upload your@email.edu sitecheck.txt

If you plan to run Cell Ranger on a cluster, please run and send us the output twice, once on a submit host and once on a cluster node.

If your system does not have direct Internet connectivity, please send the output files as attachments to support@10xgenomics.com.

Verify Installation

We provide two small datasets that you can use to verify that the cellranger demux and cellranger run components of Cell Ranger are working correctly on your system.

Verify cellranger demux with tiny-bcl

To ensure cellranger demux is working:

  1. Untar the tiny-bcl tar file in a convenient location. This will create a new tiny-bcl subdirectory.
  2. Prepend the Cell Ranger installation directory to your $PATH.
  3. Run cellranger demux against the tiny-bcl directory you just unpacked.

This test should take under five minutes on a sixteen-core workstation. And assuming you have installed Cell Ranger and the Cell Ranger refdata package into /opt, the necessary commands would look like

$ wget http://cf.10xgenomics.com/supp/cell-exp/cellranger-tiny-bcl.tar.gz
$ tar -xzvf cellranger-tiny-bcl.tar.gz
$ export PATH=/opt/cellranger-1.0.1:$PATH
$ cellranger demux --run=./cellranger-tiny-bcl
 
Martian Runtime - 1.3.0
 
Running preflight checks (please wait)...
2012-01-01 12:00:00 [runtime] (ready)           ID.AHL44.BCL_PROCESSOR_CS.BCL_PROCESSOR.BARCODE_AWARE_BCL2FASTQ
...
2012-01-01 12:03:19 [runtime] (run:local)       ID.AHL44.BCL_PROCESSOR_CS.BCL_PROCESSOR.GZIP_FASTQ.fork0.join
2012-01-01 12:03:19 [runtime] (join_complete)   ID.AHL44.BCL_PROCESSOR_CS.BCL_PROCESSOR.GZIP_FASTQ
 
Outputs:
- Demultiplexed FASTQ folder: /opt/AHL44/outs/fastq_path
 
Pipestance completed successfully!

This test should exit without error. If you encounter:

[error] No bcl2fastq found on path. demux requires bcl2fastq v2.17 or greater for RTA version: 1.18.54

you do not have a working installation of Illumina's bcl2fastq software and will have to reinstall it.

Verify cellranger with tiny-fastq

To ensure cellranger run is working,

  1. Untar the tinyfastq tar file in a convenient location. This will create a new tiny-fastq subdirectory.
  2. Prepend the Cell Ranger installation directory to your $PATH.
  3. Run cellranger run against the tiny-fastq directory you just unpacked.

This test can take up to ten minutes on a sixteen-core workstation. Assuming you have installed Cell Ranger and the Cell Ranger refdata package into /opt, the necessary commands would look like

$ wget http://cf.10xgenomics.com/supp/cell-exp/cellranger-tiny-fastq.tar.gz
$ tar -xzvf cellranger-tiny-fastq.tar.gz
$ export PATH=/opt/cellranger-1.0.1:$PATH
$ cellranger run --id=tinytest --fastqs=./cellranger-tiny-fastq \
                 --transcriptome=/opt/refdata-cellranger-1.0.0/hg19
 
Martian Runtime - 1.3.0
 
Running preflight checks (please wait)...
2012-01-01 12:00:00 [runtime] (ready)           ID.tinytest.CELLRANGER_CS.CELLRANGER.SETUP_CHUNKS
...
2012-01-01 12:10:09 [runtime] (join_complete)   ID.tinytest.CELLRANGER_CS.CELLRANGER.SUMMARIZE_REPORTS
 
Outputs:
- Genome-aligned BAM: /opt/tinytest/outs/possorted_genome_bam.bam
- Genome-aligned BAM index: /opt/tinytest/outs/possorted_genome_bam_index.bam.bai
- Run summary HTML: /opt/tinytest/outs/web_summary.html
- Run summary CSV: /opt/tinytest/outs/metrics_summary.csv
- Unfiltered gene-barcode matrices: /opt/tinytest/outs/raw_gene_bc_matrices
- Filtered gene-barcode matrices: /opt/tinytest/outs/filtered_gene_bc_matrices
- Matrix analysis: /opt/tinytest/outs/analysis
- Per-molecule read information: /opt/tinytest/outs/molecule_info.h5
 
Pipestance completed successfully!

Whether the test pipestance succeeds or fails, you will then see:

Saving diagnostics to tinytest/tinytest.debug.tgz

This tinytest.debug.tgz file contains diagnostic information 10x can use to help resolve any problems. It is generated whether the pipeline succeeds or fails. If the pipeline fails and you need troubleshooting assistance, you can send this file directly to us from the command line:

$ cellranger upload your@email.edu tinytest/tinytest.debug.tgz

If your system does not have direct Internet connectivity, you can also send the file as an attachment to support@10xgenomics.com.