Cell Ranger4.0, printed on 11/05/2024
In this tutorial, you will learn how to:
ssh user.name@jaberwocky
user.name@jaberwocky'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@jaberwocky ~]$
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 could 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 get 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 availalbe, 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.
mkdir yard
pwd
The yard is located here: /mnt/home/user.name/yard. Yours may be located in a different location, depending on your system.
cd /mnt/home/user.name/yard mkdir apps cd apps
curl -o cellranger-3.1.0.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-3.1.0.tar.gz?Expires=1568276695&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2NmLjEweGdlbm9taWNzLmNvbS9yZWxlYXNlcy9jZWxsLWV4cC9jZWxscmFuZ2VyLTMuMS4wLnRhci5neiIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTU2ODI3NjY5NX19fV19&Signature=FLKeP1u95hziLa8ViQywYlipCeuTvdecksuVu~JIVsUcy7pev8VfwSwQ5kdst4hWB641KuD2qSM-5meVgCLOwE1h50oiEqYHlFfZ9XT30bAOb74cT5amOGX6HrX5nBGocLrH~gymixrkEU-z9v22TYGdHMAiqV84qvWZYKOUPZsrLR3umQuT2uF19xxbaXbUCKsVfrCSAY~0AVfEyyFYYiKnmANtEOZ1FNM0Lr6LoSq4a8o9wU9YyMYJCOfYm6JqP5QYnXUHxUMzMM4j3vJ-zASLuXito0RvrxYzgM~zNRRFwGjvr98o0xkKZ6EzGXmunA08aPlgRMG6J9t1b02NMg__&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA"
Note: You do not need to do this if the curl command above worked for you.
wget -O cellranger-3.1.0.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-3.1.0.tar.gz?Expires=1568198894&Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cDovL2NmLjEweGdlbm9taWNzLmNvbS9yZWxlYXNlcy9jZWxsLWV4cC9jZWxscmFuZ2VyLTMuMS4wLnRhci5neiIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTU2ODE5ODg5NH19fV19&Signature=MAsku-zG5j7hV9svst0pxw9WTJk3ilq3DmLb1obNHmjsOcIL8CF2T0UzYpiGQ2lTQraiPNQ2nzhLgH1liGP~7JjoZ~HousFx1w7POggIWYkhDu7ktlGQCVvjxBqZvfoWpgVvi1U4lpy7Ud2c0Hq1r3HphUH-ZiHqiGSKfTarUZEQOLLx~5CXz~moIM~TwAF0KDLwbAPkceylZUOTcdzBAH~IsD-LBXK-7WbBA5ZOFOXhAtrLWQnzCRU0HjnkXRUNtKGAJO7ApXkg8PcNQaEWBGiJ6hrnCsbPdjaVFhOcRd-6mtV-zg2WTt1kVcd8UjA4GAQ42mm1SIw5xgTkWc-~cw__&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 954M 100 954M 0 0 59.6M 0 0:00:16 0:00:16 --:--:-- 56.1M
ls -1
The output looks similar to this:
cellranger-3.1.0.tar.gz
tar -zxvf cellranger-3.1.0.tar.gz
The output looks similar to this:
cellranger-3.1.0/
cellranger-3.1.0/cellranger-tiny-fastq/
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L001_I1_001.fastq.gz
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L002_R1_001.fastq.gz
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L001_R1_001.fastq.gz
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L002_R2_001.fastq.gz
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L002_I1_001.fastq.gz
cellranger-3.1.0/cellranger-tiny-fastq/3.0.0/tinygex_S1_L001_R2_001.fastq.gz
...
... wait for the command to finish ...
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, bcl2fastq (version 2.2.0) 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. But, if you do need bcl2fastq, download then follow these install instructions.
ls -1
The output looks similar to this:
cellranger-3.1.0 cellranger-3.1.0.tar.gz
cd cellranger-3.1.0 pwd
The output looks something like this:
/mnt/home/user.name/yard/apps/cellranger-3.1.0
export PATH=/mnt/home/user.name/yard/apps/cellranger-3.1.0:$PATH
which cellranger
The output looks similar to this:
~/yard/apps/cellranger-3.0.2/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, a special script that runs every time you login 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:
/mnt/home/user.name/yard/apps/cellranger-3.1.0/cellranger-cs/3.1.0/bin cellranger (3.1.0) Copyright (c) 2019 10x Genomics, Inc. All rights reserved.
The usage statement contains a list of cellranger commands. We will run two of them now.
cellranger sitecheck > sitecheck.txt
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:
less sitecheck.txt
...
=====================================================================
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 = 2,640,000 < 26216544.
The next section is User Limits, also called ulimits.
... ===================================================================== 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 = 4096 < 1031684. But, it does not meet the max open file requirement of 16000. 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.
Our software support team can review your sitecheck results. Send it to us using cellranger upload from the command line.
cellranger upload [email protected] sitecheck.txt
The output looks something like this:
/mnt/home/user.name/yard/apps/cellranger-3.1.0/cellranger-cs/3.1.0/bin cellranger upload (3.1.0) Copyright (c) 2019 10x Genomics, Inc. All rights reserved. ------------------------------------------------------------------------------- Getting upload information... Uploading file... Size: 35,903 bytes 100% [=================================>] 35,903 5.71Mb/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.
Once the user limit for open files is adjusted, run cellranger testrun.
cellranger testrun --id=check_install
The output looks something like this:
/mnt/home/user.name/yard/apps/cellranger-3.1.0/cellranger-cs/3.1.0/bin cellranger testrun (3.1.0) Copyright (c) 2019 10x Genomics, Inc. All rights reserved. ------------------------------------------------------------------------------- Running Cell Ranger in test mode... ...
This process takes about five minutes to run and completes with the following statement:
Pipestance completed successfully! 2019-09-11 15:49:00 Shutting down. Saving pipestance info to "check_install/check_install.mri.tgz"
This indicates a successful testrun and, by extension, a successful Cell Ranger install.