Cell Ranger is delivered as a single, self-contained tar
file that can be unpacked anywhere on your system. It bundles all of its required software dependencies, which are pre-compiled to run on a wide range of Linux distributions. For convenience, the reference data package required for Cell Ranger is provided as a separate download.
The Cell Ranger tarball comes in two compression formats, .tar.gz
and .tar.xz
. Choose either format to install. The .xz
compressed file is smaller, which may speed up download times.
Here is a quick start guide to installing Cell Ranger. For detailed instructions, please refer to the tutorial section below.
Step 1 – Download and unpack the cellranger-x.y.z.tar.gz
tar file in any location. In this example, we unpack it in a directory called /opt
.
cd /opt
# [ download file from downloads page ]
tar -xzvf cellranger-x.y.z.tar.gz
If you downloaded Cell Ranger in the .xz
compression format, be sure to use the correct file extension tar.xz
and tar flags to unpack:
cd /opt
# [ download file from downloads page ]
tar -xvf cellranger-x.y.z.tar.xz
This unpacks Cell Ranger, its dependencies, and the cellranger
script into a new directory called cellranger-x.y.z
.
Step 2 – Download and unpack any of the reference data files in a convenient location:
# [ download file from downloads page ]
# Example human reference transcriptome
tar -xzvf refdata-gex-GRCh38-2020-A.tar.gz
This creates a new directory called refdata-gex-GRCh38-2020-A
that contains a single reference (in this case, GRCh38). Each reference contains a set of pre-generated indices and other data required by Cell Ranger.
Step 3 – Prepend the Cell Ranger directory to your $PATH. This will allow you to invoke the cellranger command.
If you unpacked both Cell Ranger and the reference data into /opt, then you would run the following command:
export PATH=/opt/cellranger-x.y.z:$PATH
You may wish to add this command to your .bashrc
for convenience.
Here is a detailed tutorial on installing Cell Ranger.
- 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
- Sometimes you are prompted for a password. When you type in your password, usually no characters are displayed. This is normal, just keep typing.
user.name@jabberwocky's password:
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.
- We will call our working directory the yard. Make a new directory with the following command:
mkdir yard
- 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.
- Go into that directory using the command,
cd
(change directory), and make a folder usingmkdir apps
to install Cell Ranger.
cd /mnt/home/user.name/yard
mkdir apps
cd apps
-
Go to the Cell Ranger Download page and fill out the "10x Genomics End User Software License Agreement" information. Select either the Gzip or Xzip tarball to download. Be sure to copy the whole command from the Downloads page.
-
Some systems do not have the command,
curl
(client url) installed. An alternative command provided on the Downloads page iswget
. Note: You do not need to do this if thecurl
command worked for you.
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
- 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-x.y.z.tar.gz
- Unpack the tarball using the
tar
command:
tar -zxvf cellranger-x.y.z.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-x.y.z.tar.xz
The output looks similar to this:
cellranger-x.y.z/
cellranger-x.y.z/.env.json
cellranger-x.y.z/.version
cellranger-x.y.z/LICENSE
cellranger-x.y.z/builtwith.json
cellranger-x.y.z/sourceme.bash
cellranger-x.y.z/sourceme.csh
cellranger-x.y.z/bin/
cellranger-x.y.z/bin/_cellranger_internal
cellranger-x.y.z/bin/cellranger
cellranger-x.y.z/bin/rna/
...
A large amount of information is printed on 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.
- List the contents of the Cell Ranger directory:
ls -l
The output looks similar to this:
cellranger-x.y.z
cellranger-x.y.z.tar.gz
- 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 thecellranger-x.y.z
directory and enterpwd
.
cd cellranger-x.y.z
pwd
The output looks something like this:
/mnt/home/user.name/yard/apps/cellranger-x.y.z
- Then use the
export
command to add it to the\$PATH
variable.
export PATH=/mnt/home/user.name/yard/apps/cellranger-x.y.z:$PATH
- Then enter
which cellranger
to see if we have successfully addedcellranger
to the $PATH.
which cellranger
The output looks similar to this:
~/yard/apps/cellranger-x.y.z/cellranger
Note that the "tilde" symbol, , is the same as $HOME, which is the same as /mnt/home/user.name/
.
-
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. -
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-x.y.z
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
...
To confirm your installation worked correctly, 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 is completed 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.