10x Genomics
Chromium Genome & Exome

Long Ranger2.0, printed on 04/26/2024

Running Multi-Flowcell Samples

The longranger run command provides the means to define samples according to the output of a single longranger demux's output FASTQs. While this sample specification (i.e., one flowcell per sample) is the most common, high-depth sequencing often involves sequencing a single sample using multiple flowcells. To this end, the longranger run pipeline allows complex sample construction such as combining sample indices from multiple flowcells into a single sample.

To create complex sample specifications, you will have to write your own MRO file for the longranger run pipeline. MRO is the language used to define pipelines to the Martian pipeline framework which is responsible for managing pipeline execution. The longranger run command is simply a shell script that converts command line arguments into an MRO file which is passed to the Martian pipeline execution command, mrp, and writing MROs directly allows you to access the full range of options available for each pipeline.

Understanding the Pipeline Invocation MRO

The easiest way to write your own MRO is to start with the MRO from a previous pipeline. Assuming you have already run a single-flowcell sample (e.g., sample345) from the same run mode (e.g., Whole Genome Mode) you will be using for your multi-flowcell sample, examine the _invocation file contained in its output directory:

$ cat sample345/_invocation
 
@include "phaser_svcaller_cs.mro"
 
call PHASER_SVCALLER_CS(
    fastq_mode = "BCL_PROCESSOR",
    sample_id = "sample345",
    sample_def = [
        {
            "bc_in_read": 1,
            "bc_length": 16,
            "gem_group": null,
            "lanes": null,
            "read_path": "/home/jdoe/runs/HBA2TADXX",
            "sample_indices": [ "any" ]
        }
    ],
    reference_path = "/opt/refdata-hg19-2.0.0",
    sample_desc = "",
    sex = "f",
    targets = null,
    vc_mode = "freebayes",
    vc_ground_truth = null,
    restrict_locus = null,
)

The sample_def argument controls the parameters used to define this sample and is a JSON-encoded list of maps that define:

• read_path - a directory containing FASTQs from a single flowcell
• lanes - a list of lanes from this flowcell to be included in this sample (e.g., [ 1, 2 ], [ 2 ], etc) or null to use all lanes
• gem_group - set this to null
• sample_indices - a list of sample indices from the 8-bp I7 read
• bc_in_read - which read (R1 or R2) contains the Chromium barcode. Should always be 1 for Chromium.
• bc_length - the length of the barcode in the embedded read. Should always be 16 for Chromium.

Make a copy of this _invocation file; this will be the MRO from which we will build our multi-flowcell invocation MRO.

Combining Multiple Flowcells

Continuing with the example MRO above, we would make the following changes:

1. Give this sample a new sample_id.
2. Duplicate the dict contained in the sample_def definition as a second item in the sample_def list
3. Change the read_paths for each of these sample_def objects to point to the HAWT7ADXX and HAWPUADXX FASTQ output directories
4. Change lanes and/or sample_indices to reflect the flowcell configuration used in sequencing, if necessary

For example, the two-flowcell MRO may appear as

$ cp sample345/_invocation sample345-multi.mro
$ nano sample345-multi.mro
...
 
$ cat sample345-multi.mro
 
@include "phaser_svcaller_cs.mro"
 
call PHASER_SVCALLER_CS(
    fastq_mode = "BCL_PROCESSOR",
    sample_id = "sample345-multi",
    sample_def = [
        {
            "bc_in_read": 1,
            "bc_length": 16,
            "gem_group": null,
            "lanes": null,
            "read_path": "/home/jdoe/runs/HAWT7ADXX",
            "sample_indices": [ "any" ]
        },
        {
            "bc_in_read": 1,
            "bc_length": 16,
            "gem_group": null,
            "lanes": null,
            "read_path": "/home/jdoe/runs/HAWPUADXX",
            "sample_indices": [ "any" ]
        }
    ],
    reference_path = "/opt/refdata-hg19-2.0.0",
    sample_desc = "",
    sex = "f",
    targets = null,
    vc_mode = "freebayes",
    vc_ground_truth = null,
    restrict_locus = null,
)

where the changes from the original MRO are highlighted.

Once you have this multi-flowcell MRO, confirm that its syntax is valid with mrc, the MRO compiler included with Long Ranger:

$ mrc sample345-multi.mro
Successfully compiled 1 mro files.

Then run the MRO file using longranger run command's alternate MRO-mode syntax:

$ longranger run sample345-multi sample345-multi.mro --uiport=3600
Martian Runtime - 2.0.1
Serving UI at http://localhost:3600                                             
 
Running preflight checks (please wait)...
2016-05-01 12:00:00 [runtime] (ready)           ID.sample345-multi.PHASER_SVCALLER_CS.PHASER_SVCALLER._ALIGNER.SETUP_CHUNKS
2016-05-01 12:00:00 [runtime] (run:local)       ID.sample345-multi.PHASER_SVCALLER_CS.PHASER_SVCALLER._SNPINDEL_PHASER.SORT_GROUND_TRUTH
2016-05-01 12:00:00 [runtime] (run:local)       ID.sample345-multi.PHASER_SVCALLER_CS.PHASER_SVCALLER._SNPINDEL_PHASER.SORT_GROUND_TRUTH.fork0.chnk0.main

where

• The first argument (sample345-multi) is the name of the run/sample.
• The second argument (sample345-multi.mro) is the custom MRO file you just created.
• Additional optional parameters (e.g., --uiport=3600) can be added to the end of the longranger run command.