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

Cell Ranger


Loupe

10x Genomics
Chromium Single Cell Gene Expression

Installing Cell Ranger

In this tutorial, you will learn how to:

Login to a remote computer

  1. Begin this tutorial by logging in to your remote Linux server. The procedure varies based on the machine, but most likely involves using an ssh command.
ssh user.name@jabberwocky
  1. Sometimes you are prompted for a password:
user.name@jabberwocky's password:

When you type in your password, usually no characters are displayed. This is normal, just keep typing.

After logging in, the command prompt looks similar to this:

[user.name@jabberwocky ~]$

Cell Ranger pipelines must run on a Linux system that meets these minimum requirements. It is common to run Cell Ranger on High Performance Computing clusters (HPCs) or stand alone servers. These resources may be available for you to use through your institution. There are also cloud computing options through service providers such as:

If you are in the U.S. and part of an academic or non-profit institution, you may also be able to request time on a proposal-based resource such as:

Most institutional servers and services have a system administrator tasked with the upkeep of the machine. If available, work with your administrator to log in, identify an appropriate directory to run your analysis, and efficiently allocate system resources for running Cell Ranger.

Sometimes HPC systems have designated compute or interactive nodes for users to log in and monitor output. If available, make sure that Cell Ranger processes do not take up excessive resources and slow down your shared head node for other users.

Note: For the rest of this tutorial, commands are listed for you to copy/paste directly into your command prompt. We alternate between showing you the commands and the expected output.

Set up a directory

  1. We call our working directory the yard. Make a new directory with the following command:
mkdir yard
  1. To keep track of where the yard is located, use the pwd command (print working directory):
pwd

Our yard directory is located here: /mnt/home/user.name/yard. Your directory may be located in a different location depending on your system.

  1. Go into that directory using the command, cd (change directory), and make a folder using mkdir apps to install Cell Ranger.
cd /mnt/home/user.name/yard
mkdir apps
cd apps

Download and extract Cell Ranger

  1. Go to the Cell Ranger Download page and fill out the "10x Genomics End User Software License Agreement" information. Paste the entire command onto your command line. Parts of the download command change periodically, so copying the exact command below may not work. Be sure to copy the whole command from the Downloads page.
curl -o cellranger-6.1.2.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-6.1.2.tar.gz?Expires=1641366506&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9jZi4xMHhnZW5vbWljcy5jb20vcmVsZWFzZXMvY2VsbC1leHAvY2VsbHJhbmdlci02LjEuMi50YXIuZ3oiLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE2NDEzNjY1MDZ9fX1dfQ__&Signature=kaV8~ZabHhyDykUhbN~F78PDQfNZ64IamgsGc1nOSghFKPr0fbZ3WJk-2eWYh7IEt-KupenYP89W1zHi4lrxF~ZBbuP4NTaKEAa-G6ILJoX-VdyFnktkXFYDHgzEJ8ABq-NM6RWn20WD3a9BITNHTIWPtxjM-NaXAuR5uc5PuAEgjSDaQ2QBAQr~1q4aSM-~vJt~ia5e8acTz9RlM24EluLqfO59VCtAorP-5iJRwvLw9DjfrTlDtWfy3M2LSXp5OGmVJH1WUQReLK~0iZX2e8~vrHlAYpuxMa0Lgil6oHQ5s6vc~Dod3Aqpjb9sM~wuVo80zi4EqJ5nq0LU8SNbiQ__&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA"
  1. Some systems do not have the command, curl (client url) installed. An alternative command is wget.

Note: You do not need to do this if the curl command above worked for you.

wget -O cellranger-6.1.2.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-6.1.2.tar.gz?Expires=1641366506&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9jZi4xMHhnZW5vbWljcy5jb20vcmVsZWFzZXMvY2VsbC1leHAvY2VsbHJhbmdlci02LjEuMi50YXIuZ3oiLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE2NDEzNjY1MDZ9fX1dfQ__&Signature=kaV8~ZabHhyDykUhbN~F78PDQfNZ64IamgsGc1nOSghFKPr0fbZ3WJk-2eWYh7IEt-KupenYP89W1zHi4lrxF~ZBbuP4NTaKEAa-G6ILJoX-VdyFnktkXFYDHgzEJ8ABq-NM6RWn20WD3a9BITNHTIWPtxjM-NaXAuR5uc5PuAEgjSDaQ2QBAQr~1q4aSM-~vJt~ia5e8acTz9RlM24EluLqfO59VCtAorP-5iJRwvLw9DjfrTlDtWfy3M2LSXp5OGmVJH1WUQReLK~0iZX2e8~vrHlAYpuxMa0Lgil6oHQ5s6vc~Dod3Aqpjb9sM~wuVo80zi4EqJ5nq0LU8SNbiQ__&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA"

The output looks similar to this:

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                               Dload  Upload   Total   Spent    Left  Speed
100  767M  100  767M    0     0   124M      0  0:00:06  0:00:06 --:--:--  131M
  1. List the contents of the apps directory to see the Cell Ranger "tarball" (archive of files).
ls -1

The output looks similar to this:

cellranger-6.1.2.tar.gz
  1. Unpack the tarball using the tar command:
tar -zxvf cellranger-6.1.2.tar.gz

If you downloaded the .tar.xz format (starting with Cell Ranger v7.1), be sure to change the file extension and omit the -z flag:

tar -xvf cellranger-7.1.0.tar.xz

The output looks similar to this:

cellranger-6.1.2/
cellranger-6.1.2/.env.json
cellranger-6.1.2/.version
cellranger-6.1.2/LICENSE
cellranger-6.1.2/builtwith.json
cellranger-6.1.2/sourceme.bash
cellranger-6.1.2/sourceme.csh
cellranger-6.1.2/bin/
cellranger-6.1.2/bin/_cellranger_internal
cellranger-6.1.2/bin/cellranger
cellranger-6.1.2/bin/rna/
...

A large amount of information is printed to the screen as it unpacks. When it's finished, a directory containing the cellranger executable and all of its dependencies (except bcl2fastq) is included.

The Illumina software, bcl2fastq2 (version 2.20) is required for cellranger mkfastq. If you know that you will not need to demultiplex and generate FASTQ files, you do not need to install bcl2fastq. If you do need bcl2fastq, download the rpm and then follow these install instructions.

  1. List the contents of the Cell Ranger directory:
ls -1

The output looks similar to this:

cellranger-6.1.2
cellranger-6.1.2.tar.gz

Add Cell Ranger to your $PATH

  1. Cell Ranger is now installed. To run it requires entering the path to the executable command on the command line. We want to be able to run Cell Ranger by simply entering the word cellranger on the command line. To accomplish this, we add it to your $PATH variable. Go into the cellranger-6.1.2 directory and enter pwd.
cd cellranger-6.1.2
pwd

The output looks something like this:

/mnt/home/user.name/yard/apps/cellranger-6.1.2
  1. Then use the export command to add it into the $PATH variable.
export PATH=/mnt/home/user.name/yard/apps/cellranger-6.1.2:$PATH
  1. Then enter which cellranger to see if we have successfully added cellranger to the $PATH.
which cellranger

The output looks similar to this:

~/yard/apps/cellranger-6.1.2/cellranger

Note that the "tilde" symbol, , is the same as $HOME, which is the same as /mnt/home/user.name/.

  1. For convenience, you may want to add this command to your .bashrc file, a special script that runs every time you log in to your system.

  2. Now you can enter cellranger on the command line from any directory to see the usage statement.

cellranger

The beginning of the usage statement looks something like this:

cellranger cellranger-6.1.2
Process 10x Genomics Gene Expression, Feature Barcode, and Immune Profiling data
 
USAGE:
    cellranger 
 
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
...

The usage statement contains a list of cellranger commands. We will run two of them now.

Perform a sitecheck

  1. The purpose of sitecheck is to check your system to make sure it meets the system requirements for running the cellranger pipeline. Run the command and use the > symbol to re-direct the output to a text file.
cellranger sitecheck > sitecheck.txt
  1. Now use the less command to take a look at this file. Use the up and down arrow keys to scroll through the file. Or to scroll down by page. Press the key on the keyboard to quit out of the less program.
less sitecheck.txt

We will take a look at the following sections of the sitecheck file to see if they meet the minimum requirements for running Cell Ranger:

  1. Scroll down until you find the parts in the file with the CPU Cores information:
...
=====================================================================
CPU Cores
grep -c processor /proc/cpuinfo
---------------------------------------------------------------------
64
=====================================================================
...

Running Cell Ranger requires at least 8 CPUs, preferably 16, and at least 64GB of RAM, preferably 128. We have 64 CPU available.

The Memory Total looks something like this:

...
=====================================================================
Memory Total
grep MemTotal /proc/meminfo | cut -d ':' -f 2 | sed 's/^[ \t]*//'
---------------------------------------------------------------------
264132348 kB
=====================================================================
...

We need to convert from kB to GB. A quick Google search does that for us. So, we have 264 GB RAM available, which meets the minimum requirements.

The Disk Space looks something like this:

...
=====================================================================
Disk Space
df -Ph | awk '{print $2, $3, $4}'
---------------------------------------------------------------------
Size Used Avail
126G 72K 126G
126G 204K 126G
20G 9.9G 9.7G
50G 1.6G 45G
16T 16T 413G
40T 28T 13T
61G 50G 12G
...

The Global File Limit looks similar to this:

...
=====================================================================
Global File Limit
cat /proc/sys/fs/file-{max,nr}
---------------------------------------------------------------------
26216544
26624   0       262144
=====================================================================
...

This value 26216544 meets the minimum requirements of 10k per GB RAM: (10,000 * 264 GB RAM = 2,640,000) < 26,216,544 .

Next, look for the User Limits section, also called ulimit.

...
=====================================================================
User Limits
bash -c 'ulimit -a'
---------------------------------------------------------------------
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 1031684
max locked memory       (kbytes, -l) 64
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 1031684
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited
=====================================================================
...

Note that this machine does meet the max user processes requirement of 64 times the number of CPUs (1031684): (64 * 64 = 4,096) < 1,031,684. But, it does not meet the max open file requirement of 16,000. Some accounts have permission to adjust user limits using the ulimit -n command.

ulimit -n 16000

This account does not have permission to change user limits.

-bash: ulimit: open files: cannot modify limit: Operation not permitted

In this case, contact your system administrator and ask them to adjust it.

Request a sitecheck review

Our software support team can review your sitecheck results. Send it to us using cellranger upload and your email address from the command line.

cellranger upload your.email@email.com sitecheck.txt

The output looks something like this:

Getting upload information...
Uploading file...
Size: 32,074 bytes
100% [=================================>] 32,074   7.97Mb/s  eta 0m  0s  
Upload complete!

You will receive an email back from support asking what you would like us to do with the file. Reply to that email, and we will review it for you.

Perform a testrun

Once the user limit for open files is adjusted, run cellranger testrun.

cellranger testrun --id=check_install

The output looks something like this:

Martian Runtime - v4.0.6
Serving UI at ...
 
Running preflight checks (please wait)...
Checking sample info...
Checking FASTQ folder...
Checking reference...
...

This process completes with the following statement:

Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
 
2022-01-04 12:51:02 Shutting down.

This output indicates a successful testrun and, by extension, a successful Cell Ranger installation.

Other tutorials in this series