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

10x Genomics
Visium Spatial Gene Expression

Setting up Space Ranger

Learning objectives

In this tutorial you will:

Prerequisites

For successful run of this tutorial, you must:

Download and install spaceranger

You can download and install spaceranger in any location. For this tutorial, we will create a working directory spaceranger_tutorial and continue all the remaining steps in it.

# Create working directory
mkdir spaceranger_tutorial
 
# Change directory
cd spaceranger_tutorial

To install the latest version of spaceranger

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload   Total   Spent    Left  Speed
10 1220M   10  125M    0     0  30.9M      0  0:00:39  0:00:04  0:00:35 30.8M

This downloads the spaceranger tarball spaceranger-2.0.0.tar.gz to your working directory. Next, we extract the contents.

# Extract spaceranger tarball
tar -zxvf spaceranger-2.0.0.tar.gz
spaceranger-2.0.0/
spaceranger-2.0.0/.env.json
spaceranger-2.0.0/.version
spaceranger-2.0.0/LICENSE
spaceranger-2.0.0/builtwith.json
spaceranger-2.0.0/sourceme.bash
spaceranger-2.0.0/sourceme.csh
spaceranger-2.0.0/bin/
spaceranger-2.0.0/bin/_spaceranger_internal
spaceranger-2.0.0/bin/spaceranger
spaceranger-2.0.0/bin/rna/
spaceranger-2.0.0/bin/rna/_includes
...

When the extraction process is finished, you will have access to the command prompt and the folder spaceranger-2.0.0 will be created in the working directory.

Familiarize with key components within spaceranger folder

The spaceranger-2.0.0 folder contains the executable and all of the required dependencies. The key folders that you would use are highlighted in bold.

spaceranger-2.0.0
├── bin
├── external
│   ├── anaconda
│   ├── martian
│   │     └── jobmanagers
│   ├── spaceranger_tiny_inputs
│   └── spaceranger_tiny_ref
├── lib
│   ├── bin
│   │     ├── bamtofastq
│   │     ├── redstone
│   │     └── ...
│   └── python
│       └── cellranger
│           └── barcodes
│               ├── visium-v1_coordinates.txt
│               ├── visium-v2_coordinates.txt
│               ├── visium-v4_coordinates.txt
│               ├── visium-v5_coordinates.txt
│               └── ...
├── mro
├── probe_sets
│   ├── Visium_Human_Transcriptome_Probe_Set_v1.0_GRCh38-2020-A.csv
│   ├── Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv
│   └── Visium_Mouse_Transcriptome_Probe_Set_v1.0_mm10-2020-A.csv
├── target_panels
│   ├── gene_signature_v1.0_GRCh38-2020-A.target_panel.csv
│   ├── immunology_v1.0_GRCh38-2020-A.target_panel.csv
│   ├── neuroscience_v1.0_GRCh38-2020-A.target_panel.csv
│   └── pan_cancer_v1.0_GRCh38-2020-A.target_panel.csv
└── THIRD-PARTY-LICENSES.spaceranger.txt    

Add spaceranger to $PATH

spaceranger is now installed. There are two ways to specify spaceranger in the commands.

# Change directory to spaceranger-2.0.0
cd spaceranger-2.0.0
 
# Get the full path
pwd
 
# Change working directory back to spaceranger_tutorial
cd ..
# Get the full path
readlink -f spaceranger-2.0.0
/PATH/TO/WORKING_DIRECTORY/spaceranger_tutorial/spaceranger-2.0.0
The code in red will change depending on the compute setup you are using.
# Get the full path
readlink -f spaceranger-2.0.0
 
# Export PATH by providing the full path
export PATH=/PATH/TO/WORKING_DIRECTORY/spaceranger_tutorial/spaceranger-2.0.0:$PATH
 
# Confirm installation
which spaceranger
# Change directory to spaceranger-2.0.0
cd spaceranger-2.0.0
 
# Export PATH by specifying a shell variable
export PATH=$PWD:$PATH
 
# Confirm installation
which spaceranger
 
# Change working directory back to spaceranger_tutorial
cd ..
~/spaceranger_tutorial/spaceranger-2.0.0
The tilde symbolizes your home directory which will be same as /PATH/TO/WORKING_DIRECTORY as before.

You can now invoke spaceranger at the command prompt to see the usage statement.

# When using full path to the spaceranger folder
/PATH/TO/WORKING_DIRECTORY/spaceranger_tutorial/spaceranger-2.0.0/spaceranger
 
# When adding spaceranger folder to the $PATH variable
spaceranger
USAGE:
    spaceranger <SUBCOMMAND>
 
FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
 
SUBCOMMANDS:
count               Count gene expression and feature barcoding reads
                    from a single capture area
aggr                Aggregate data from multiple 'spaceranger count' runs

... testrun Execute the 'count' pipeline on a small test dataset 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)

For the rest of the tutorial, we will invoke spaceranger assuming addition of the spaceranger-2.0.0 folder to the $PATH variable.

Perform and review sitecheck

spaceranger sitecheck enables you to check your system configuration to ensure it meets the minimum recommended requirements. Run the command and use > to re-direct the output to a text file.

spaceranger sitecheck > sitecheck.txt

Open the file with less and use / (e.g. /CPU Cores) to search for specific sections with the file. Press to quit.

less sitecheck.txt

We will examine some key configuration metrics and compare against the recommended system requirements.

CPU Cores
grep -c processor /proc/cpuinfo
---------------------------------------------------------------------
96
=====================================================================
...

This system has 96 CPUs and is capable of running spaceranger which requires at least 8 CPUs, preferably 32.

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

For direct comparison, let's convert kB to GB. $${\text {RAM in GB}} = \frac{289287896}{1\mathrm{e}{+6}} \approx 289$$

which satisfies the requirement of having at least 64GB RAM, preferably 128.

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) 1520514
max locked memory       (kbytes, -l) 64
max memory size         (kbytes, -m) unlimited
open files                      (-n) 10240
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) 131072
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited
=====================================================================

The two metrics to consider are highlighted in bold.

a. for the max user processes, the recommendation is the limit to be 64 per core. Assuming we use all 96 cores, $96*64 = 6,144 < 131,072$

b. for max open files, the system limit $10,240 < 16,000$ which is the recommendation. While the pipelines may run at lower open file limit, caution is urged. This value is dependent on the system, the sample type and number of samples being run. In case the pipeline errors, it is advisable to increase the user limit ulimit and try again.

Global File Limit
cat /proc/sys/fs/file-{max,nr}
---------------------------------------------------------------------
2921445
68736   0       262144
=====================================================================

The value satisfies the minimum requirement of 10k per GB RAM $10,000*289 = 2,890,000 < 2,921,445$, where 289 GB is the total memory of the system.

The software support team can review your sitecheck results. There are two ways to send it across

spaceranger upload user.email@email.com sitecheck.txt

Perform a testrun

We can verify the installation using spaceranger testrun. This pipeline can be run in two configurations depending on the internet connectivity of the compute platform.

spaceranger testrun --id=verify_install
spaceranger testrun --no-internet --id=verify_install
Martian Runtime - v4.0.5
 
Running preflight checks (please wait)...
Checking sample info...
Checking FASTQ folder...
Checking reference...
Checking reference_path
Checking optional arguments...
 
...
 
Pipestance completed successfully!

Successful completion of the testrun by extension implies successful installation of spaceranger.

FAQs

Q. How can I use multiple versions of spaceranger ?

Sometimes it is useful to have access to older as well as newer versions of spaceranger. There are two suggested ways to achieve this: