CellRanger 2016

Introduction

Cell Ranger is a set of analysis pipelines that process Chromium single-cell data to align reads, generate feature-barcode matrices, perform clustering and other secondary analysis, and more. Cell Ranger includes five pipelines relevant to the 3' and 5' Single Cell Gene Expression Solutions and related products:

• cellranger mkfastq demultiplexes raw base call (BCL) files generated by Illumina sequencers into FASTQ files. It is a wrapper around Illumina's bcl2fastq, with additional features that are specific to 10x libraries and a simplified sample sheet format.
• cellranger count takes FASTQ files from cellranger mkfastq and performs alignment, filtering, barcode counting, and UMI counting. It uses the Chromium cellular barcodes to generate feature-barcode matrices, determine clusters, and perform gene expression analysis. The count pipeline can take input from multiple sequencing runs on the same GEM well. cellranger count also processes Feature Barcode data alongside Gene Expression reads.
• cellranger aggr aggregates outputs from multiple runs of cellranger count, normalizing those runs to the same sequencing depth and then recomputing the feature-barcode matrices and analysis on the combined data. The aggr pipeline can be used to combine data from multiple samples into an experiment-wide feature-barcode matrix and analysis.
• cellranger reanalyze takes feature-barcode matrices produced by cellranger count or cellranger aggr and reruns the dimensionality reduction, clustering, and gene expression algorithms using tunable parameter settings.
• cellranger multi is used to analyze Cell Multiplexing data. It inputs FASTQ files from cellranger mkfastq and performs alignment, filtering, barcode counting, and UMI counting. It uses the Chromium cellular barcodes to generate feature-barcode matrices, determine clusters, and perform gene expression analysis. The cellranger multi pipeline also supports the analysis of Feature Barcode data. ¹

Installed version(s)

The following version is currently available...

... on environment hpc-env/8.3:

• CellRanger/6.1.1
• CellRanger/7.1.0

... on environment hpc-env/6.4:

• CellRanger/6.1.1
• CellRanger/7.1.0

... on environment hpc-uniol-env:

• CellRanger/6.1.1
• CellRanger/7.1.0

Loading / Using CellRanger

To load the desired version of the module, use the module load command, e.g.

module load hpc-env/8.3
module load CellRanger/6.1.1

Always remember: this command is case sensitive!

To find out on how to use CellRanger you can just type in cellranger -h to print out a help text to get you started:

$ cellranger -h
cellranger cellranger-6.1.1
Process 10x Genomics Gene Expression, Feature Barcode, and Immune Profiling
data

USAGE:
    cellranger <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    count               Count gene expression (targeted or whole-
                        transcriptome) and/or feature barcode reads from a
                        single sample and GEM well
    multi               Analyze multiplexed data or combined gene
                        expression/immune profiling/feature barcode data
    vdj                 Assembles single-cell VDJ receptor sequences from
                        10x Immune Profiling libraries
    aggr                Aggregate data from multiple Cell Ranger runs
    reanalyze           Re-run secondary analysis (dimensionality
                        reduction, clustering, etc)
    targeted-compare    Analyze targeted enrichment performance by
                        comparing a targeted sample to its cognate parent
                        WTA sample (used as input for targeted gene
                        expression)
    targeted-depth      Estimate targeted read depth values (mean reads
                        per cell) for a specified input parent WTA sample
                        and a target panel CSV file
    mkvdjref            Prepare a reference for use with CellRanger VDJ
    mkfastq             Run Illumina demultiplexer on sample sheets that
                        contain 10x-specific sample index sets
    testrun             Execute the 'count' pipeline on a small test
                        dataset
    mat2csv             Convert a gene count matrix to CSV format
    mkref               Prepare a reference for use with 10x analysis
                        software. Requires a GTF and FASTA
    mkgtf               Filter a GTF file by attribute prior to creating a
                        10x reference
    upload              Upload analysis logs to 10x Genomics support
    sitecheck           Collect linux system configuration information
    help                Prints this message or the help of the given
                        subcommand(s)

Additionally, we included some reference files (References - 2020-A (July 7, 2020)) which you can find inside the folder called data which can be found at software path $EBROOTCELLRANGER.
To make the file access easier for you, we created the environment variable $CELLRANGER_DATA which leads to the files directory:

$ ls $CELLRANGER_DATA 
chromium-shared-sample-indexes-plate.csv
chromium-shared-sample-indexes-plate.json
chromium-single-cell-sample-indexes-plate-v1.csv
chromium-single-cell-sample-indexes-plate-v1.json
gemcode-single-cell-sample-indexes-plate.csv
gemcode-single-cell-sample-indexes-plate.json
refdata-gex-GRCh38-2020-A
refdata-gex-GRCh38-and-mm10-2020-A
refdata-gex-mm10-2020-A

A simple test command can be executed with

cellranger testrun --id=tiny

which runs for a few minutes and creates a directory tiny containing the results from the test run.

Job Script vs. Cluster Mode

There are in principle two options to run CellRanger on the cluster:

1. Using a Job Script As explained in the documentaion, you can use a standard Slurm job script to run CellRanger on a compute node. For the test run above the job script could look like this:

#!/usr/bin/env bash
# =============================================================================
# Slurm Options (mmodify to your needs)
# =============================================================================
#SBATCH -J CellRangerTestrun
#SBATCH --partition carl.p
#SBATCH --time 0-24:00:00             # time format d-hh:mm:ss
#SBATCH --nodes=1 --ntasks=1          # do not change
#SBATCH --cpus-per-task=4             # adjust as needed
#SBATCH --signal=2
#SBATCH --no-requeue
#SBATCH --mem=20G                     # adjust as needed
#SBATCH -o CellRanger_%j.out          # log file for STDOUT, %j is job id
#SBATCH -e CellRanger_%j.err          # log file for STDERR

# calculate memory limit in GB 
MEM_GB=$((9*SLURM_MEM_PER_NODE/10240))

# pipeline command (replace with the command you would like to run)
# keep the options --jobmode and --local*
cellranger testrun --id=tiny --jobmode=local --localcores=${SLURM_CPUS_PER_TASK} --localmem=${MEM_GB}

The job script above can be saved e.g. as CellRanger_testrun.sh and then submitted with

sbatch CellRanger_testrun.sh

For real applications you can replace the testrun command with the pipeline command you want to run. The --jobmode and the --local* options allow CellRanger to use the resources allocated for the job. The values are taken automatically from the SBATCH-options for --cpus-per-task and --mem and can be adjusted there as needed. Note, that you may need to find an optimal number of --cpus-per-core for different steps of a pipeline by running some benchmark tests.

2. Using the Cluster Mode

Instead of writing a job script, you can also use CellRanger's built-in cluster mode. Here you execute the following commands on a login node:

screen                         # start a screen terminal (it allows you to disconnect from the cluster while the pipeline is running)
module load CellRanger         # maybe specify the version as well
cellranger testrun --id=tiny --jobmode=slurm

This will start the testrun pipeline but now instead of running it locally, it will create around 200 smaller jobs which are submitted to the cluster. The job submission is done with a template in /cm/shared/uniol/scripts/CellRanger and CellRanger automatically sets the number of cores and memory to use. The example runs for almost an hour because of the overhead created from submitting the 200 jobs and the extra time it takes Slurm to manage the jobs. In real applications this might still be beneficial because several jobs can run in parallel with this approach, while in the job script above all steps are taken one after another.

While the pipeline is running, you can check the status in the terminal. You can also use the screen-mechanism to detach your session (press CTRL-A-D and logout from the cluster, but you need to remember which hpcl00x-login node you are connected to. When you login back to the cluster to the same login node, you can reattach you screen-session (screen -r) and check the progress).

If you want, you can also modify the template script. Copy the script from the location above to e.g. your $HOME, modify it and use the option --jobmode=$HOME/slurm.template. That way, you can for example use a different partition.

Documentation

More information and a tutorial can be found here.