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

10x Genomics
Chromium Genome & Exome

Long Ranger Installation

Long 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, hg19 and b37-style reference packages required for Long Ranger are provided as separate downloads.

Download and Install

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

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

This unpacks Long Ranger, its dependencies, and an environment setup script into a new directory called longranger-2.0.1.

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

[ download file from downloads page ]
$ tar -xzvf refdata-hg19-2.0.0.tar.gz

This creates a new directory called refdata-hg19-2.0.0 that contains the hg19 reference and a set of pre-generated indices and other data required by Long Ranger.

Step 3 – Prepend the Long Ranger directory to your $PATH. This will allow you to invoke the longranger commands.

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

$ export PATH=/opt/longranger-2.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 Long Ranger will run smoothly once you have generated your own Chromium data. Assuming you have installed and entered the 10x environment as described above, please run the following commands:

$ longranger sitecheck > sitecheck.txt
$ longranger upload [email protected] sitecheck.txt

If you plan to run Long 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 [email protected].

Verify Installation

We provide two small tests that you can use to verify that the longranger demux and longranger run pipelines are working correctly on your system.

Verify longranger demux with tiny-bcl

To ensure that the longranger demux pipeline is working:

  1. Download the tiny-bcl tar file.
  2. Untar the tiny-bcl tar file in a convenient location. This will create a new tiny-bcl subdirectory.
  3. Run longranger 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 Long Ranger and the 10x refdata package into /opt, the necessary commands would look like:

$ wget https://cf.10xgenomics.com/supp/genome/tiny-bcl-2.0.0.tar.gz
$ tar -xzvf tiny-bcl-2.0.0.tar.gz
$ export PATH=/opt/longranger-2.0.1:$PATH
$ longranger demux --run=./tiny-bcl-2.0.0
 
#############################################################################
longranger demux 2.0.1
Copyright (c) 2016 10x Genomics, Inc.  All rights reserved.
#############################################################################
Martian Runtime - 2.0.1
 
Running preflight checks (please wait)...
2016-05-01 12:00:00 [runtime] (ready)           ID.H77WWBBXX.BCL_PROCESSOR_CS.BCL_PROCESSOR.BARCODE_AWARE_BCL2FASTQ
2016-05-01 12:00:00 [runtime] (run:local)       ID.H77WWBBXX.BCL_PROCESSOR_CS.BCL_PROCESSOR.BARCODE_AWARE_BCL2FASTQ.fork0.split
...
2016-05-01 12:03:19 [runtime] (run:local)       ID.H77WWBBXX.BCL_PROCESSOR_CS.BCL_PROCESSOR.GZIP_FASTQ.fork0.join
2016-05-01 12:03:19 [runtime] (join_complete)   ID.H77WWBBXX.BCL_PROCESSOR_CS.BCL_PROCESSOR.GZIP_FASTQ
 
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 longranger run with --test mode

To ensure that the longranger pipeline is working, you will use the longranger run command in --test mode. This test can take up to 60 minutes on a sixteen-core workstation. Assuming you have installed Long Ranger and the 10x refdata package into /opt, the necessary commands would look like:

$ export PATH=/opt/longranger-2.0.1:$PATH
$ longranger run --test --id=tiny
 
#############################################################################
longranger run 2.0.1
Copyright (c) 2016 10x Genomics, Inc.  All rights reserved.
#############################################################################
Martian Runtime - 2.0.1
 
Running preflight checks (please wait)...
2016-05-01 12:00:00 [runtime] (ready)           ID.tiny.VCALLER_CS.VCALLER.CANONICALIZE_GROUND_TRUTH
2016-05-01 12:00:00 [runtime] (run:local)       ID.tiny.VCALLER_CS.VCALLER.CANONICALIZE_GROUND_TRUTH.fork0.split
...
2016-05-01 12:39:09 [runtime] (chunks_complete) ID.tiny.VCALLER_CS.VCALLER.SUMMARIZE_REPORTS
2016-05-01 12:39:09 [runtime] (join_complete)   ID.tiny.VCALLER_CS.VCALLER.SUMMARIZE_REPORTS
 
Pipestance completed successfully!

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

Saving diagnostics to tiny/tiny.mri.tgz

This tiny.mri.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:

$ longranger upload [email protected] tiny/tiny.mri.tgz

If your system does not have direct Internet connectivity, you can also send the file as an attachment to [email protected].