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

10x Genomics
Visium Spatial Gene Expression

Space Ranger Installation

Space 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 Space Ranger is provided as a separate download.

Download and Install

Step 1 – Download and unpack the Space Ranger file in any location. This example uses /opt.

$ cd /opt
[ download file from downloads page ]
$ tar -xzvf spaceranger-1.2.2.tar.gz

This unpacks Space Ranger, its dependencies, and the spaceranger script into a new directory called spaceranger-1.2.2.

Step 2 – Download and unpack any of the reference data files in a convenient location:

[ download file from downloads page ]
$ 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 Space Ranger.

Step 3 – Prepend the Space Ranger directory to your $PATH. This allows you to invoke the spaceranger command.

If you unpacked both Space Ranger and the reference data into /opt, then run the following command:

$ export PATH=/opt/spaceranger-1.2.2:$PATH

For convenience, add this command to your .bashrc

Site Check Script

Next, run the bundled site check script and send the output to 10x. If requested, we will review the information to ensure that Space Ranger runs smoothly once you have generated your own Visium data. Assuming you have installed Space Ranger as described above, run the following commands:

$ spaceranger sitecheck > sitecheck.txt
$ spaceranger upload [email protected] sitecheck.txt

If you plan to run Space Ranger on a cluster, run and send us the output twice, once on a submit host and once on a cluster node.

If your system does not have direct Internet connectivity, send the output files as attachments to [email protected].

Verify Installation

To ensure that the spaceranger pipeline is installed correctly, use spaceranger testrun. This test can take up to 60 minutes on a sixteen-core workstation. Assuming you have installed Space Ranger into /opt, the command to run the test looks like:

$ export PATH=/opt/spaceranger-1.2.2:$PATH
$ spaceranger testrun --id=tiny
 
spaceranger testrun 1.2.2
Copyright (c) 2016 10x Genomics, Inc.  All rights reserved.
-----------------------------------------------------------------------------
Martian Runtime - 4.0.2
 
Running preflight checks (please wait)...
Checking sample info...
Checking FASTQ folder...
Checking reference...
Checking reference_path (/opt/spaceranger-1.0.0/bin/../external/spaceranger_tiny_ref/1.0.0)
Checking chemistry...
Checking optional arguments...
mrc: v3.2.5
mrp: v3.2.5
Anaconda: Python 2.7.15 :: Anaconda, Inc.
numpy: 1.14.2
scipy: 1.0.1
pysam: 0.14.1
h5py: 2.8.0
pandas: 0.22.0
STAR: STAR_2.5.1b
samtools: samtools 1.7
Using htslib 1.7
Copyright (C) 2018 Genome Research Ltd.

2019-11-21 14:36:29 [runtime] (ready)           ID.tiny.SPATIAL_RNA_COUNTER_CS.SPATIAL_RNA_COUNTER.SPATIAL_RNA_ANALYZER.CHOOSE_DIMENSION_REDUCTION
2019-11-21 14:36:29 [runtime] (run:local)       ID.tiny.SPATIAL_RNA_COUNTER_CS.SPATIAL_RNA_COUNTER.SPATIAL_RNA_ANALYZER.CHOOSE_DIMENSION_REDUCTION.fork0.chnk0.main
2019-11-21 14:36:29 [runtime] (ready)           ID.tiny.SPATIAL_RNA_COUNTER_CS.SPATIAL_IMAGING_CS.STANDARDIZE_IMAGES
2019-11-21 14:36:29 [runtime] (run:local)       ID.tiny.SPATIAL_RNA_COUNTER_CS.SPATIAL_IMAGING_CS.STANDARDIZE_IMAGES.fork0.split
2019-11-21 14:36:29 [runtime] (ready)           ID.tiny.SPATIAL_RNA_COUNTER_CS.SPATIAL_RNA_COUNTER_PREP.CHEMISTRY_DETECTOR.DETECT_CHEMISTRY
...
 
Pipestance completed successfully!

Whether the test pipestance succeeds or fails, you will see:

Saving diagnostics to tiny/tiny.mri.tgz

This tiny.mri.tgz file contains diagnostic information 10x can use to help resolve any problems. It is generated whether the pipeline succeeds or fails. If the pipeline fails and you need troubleshooting assistance, you can send this file directly to us from the command line:

$ spaceranger upload [email protected] tiny/tiny.mri.tgz

If your system does not have direct Internet connectivity, you can also send the file as an attachment to [email protected].