10x Genomics
Chromium Single Cell Immune Profiling

Cell Ranger3.1, printed on 11/14/2024

The Cell Ranger User Interface

Specifying the --uiport=3600 option when using cellranger will enable the pipeline's visual user interface (UI). This UI is accessible through a web interface that runs on the given port (3600 when using --uiport=3600) on the machine where the pipeline was started.

Understanding the UI

While a pipeline is running with the UI enabled, you can open http://localhost:3600/ in your web browser (assuming you are browsing from the same workstation that is running Cell Ranger) to view the pipeline process graph:

Clicking on any of the graph's nodes will reveal more information about that stage in the right pane. This info pane is broken into several sections, and the topmost shows high-level details about the stage's execution. For example, the RUN_KMEANS stage would show:

This includes the state of the stage (running, failed, or complete), the fully-qualified stage name (FQName), the directory in which the stage is running (Path), the stagecode that is being run (the location of the Python package being run in the above example), and any information about parameter sweeping that may apply to this stage.

Clicking the arrow next to the stage name (← RUN_KMEANS in the above example) will return to the pipeline-level metadata view.

The Sweeping section allows you to view the MRO call used to invoke this stage (invocation) and information about the split and join components of the stage if it was parallelized.

The Argument Bindings and Return Bindings sections display the inputs and outputs of the stage:

In general, only top-level pipeline stages (those represented by rectangular nodes in the process graph) contain return bindings.

The Chunking section displays information about the parallel execution of the stage:

Many stages are automatically parallelized and process different pieces (chunks) of the same input dataset in parallel. In the above example, the input dataset (the BAM file from the SORT_BY_BC stage according to the Argument Bindings section above) was split into 39 chunks for this stage. Chunks 0-30 already completed, 31-35 are in flight, and 36-38 are waiting for CPU and/or memory to become available before running.

Clicking on an individual chunk exposes additional options for viewing metadata about that chunk's execution (Chunk Def) including how much RAM (__mem_gb) and how many cores (__threads) it requests. As with the Sweeping section, additional metadata associated with the chunk execution can also be viewed.

Launching the UI for Existing Pipelines

You can also examine pipestances that have already completed using the Cell Ranger UI. Assuming your pipestance output directory was /home/jdoe/runs/sample345, simply re-run the cellranger command with the --noexit option passed along with --uiport to re-attach the UI:

$ cellranger vdj --id=sample345 \
                 --reference=/opt/refdata-cellranger-vdj-GRCh38-alts-ensembl-3.1.0 \
                 --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
                 --indices=SI-3A-A1 \
                 --uiport=3600 \
                 --noexit
 
Martian Runtime - v3.2.3
Serving UI at http://localhost:3600
2012-01-01 12:00:00 [runtime] Reattaching in local mode.
 
Running preflight checks (please wait)...
Pipestance completed successfully, staying alive because --noexit given.

Alternately, you can re-attach using cellranger's MRO-mode syntax detailed in the Multi-Library Samples page. Because the _invocation metadata file contains the MRO used to invoke the stage, you can simply pass it to the cellranger command (e.g., sample345/_invocation) along with the pipestance output directory's name (which is the same as the sample name; e.g., sample345):

$ cellranger vdj sample345/_invocation sample345 \
                 --uiport=3600 \
                 --noexit
 
Martian Runtime - v3.2.3
Serving UI at http://localhost:3600
2012-01-01 12:00:00 [runtime] Reattaching in local mode.
 
Running preflight checks (please wait)...
Pipestance completed successfully, staying alive because --noexit given.

Because cellranger assumes it is resuming an incomplete pipeline job when re-attaching, the pipeline must be valid and preflight checks must still be passed. As such, relocating a complete pipeline may prevent the UI from re-attaching.

Accessing the UI Through a Firewall

If you run pipelines on a server that blocks access to all ports except SSH, you can still access the Cell Ranger UI using SSH forwarding. Assuming you have a cellranger pipeline running with --uiport=3600 on cluster.university.edu, you can type the following from your laptop:

$ ssh -NT -L 9000:cluster.university.edu:3600 jdoe@cluster.university.edu
jdoe@cluster.university.edu's password:

Upon entering your password (assuming you are jdoe@cluster.university.edu), the command will appear to hang. However, in the background it has mapped port 9000 on your laptop to port 3600 on cluster.university.edu through the ssh connection for which you just entered your password.

This allows you to go to http://localhost:9000/ in your web browser and access the UI running on cluster.university.edu:3600. Once you are done examining the UI, use Ctrl+C in your ssh -NT -L ... terminal window to terminate this SSH forwarder.

A full explanation of SSH forwarding is beyond the scope of this guide, please see SSH/OpenSSH/PortForwarding.