Space Ranger1.3, printed on 12/02/2023
In this tutorial you will:
For successful run of this tutorial, you must:
Spatial gene expression for formalin fixed paraffin embedded (FFPE) tissue is determined using spaceranger count pipeline which takes microscope image of the visium slide (in either
JPEG formats) and sample
FASTQ files as inputs. The pipeline performs alignment, tissue and fiducial detection as well as barcode/UMI counting. Outputs capture the feature-spot matrices, clustering and differential gene expression (DGE) which can be further analyzed and visualized in Loupe Browser.
In this tutorial, we will run spaceranger count pipeline on a mouse brain FFPE section public dataset. Key dataset features are:
|The example dataset includes a brightfield image with clear view of the fiducial frame enabling the use of spaceranger automatic image processing pipeline. The code included in this tutorial reflects this workflow. The image is rotated 90° from the default orientation that spaceranger expects.|
All the following commands will be run in the working directory
spaceranger_tutorial that was used to set up spaceranger on a compatible compute platform.
|We strongly encourage backing up the raw sequencing files generated from your own experiments. As the example dataset and the reference data are publicly available, you will be able to re-download and run the tutorial should the files be deleted from your server.|
Both the raw sequencing files in
FASTQ format, and the image in
TIFF format, are available for batch download on the dataset page. For better organization, we will create a datasets folder prior to downloading the required file.
# Create datasets folder mkdir datasets # Download FASTQ to datasets folder curl https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_FFPE_Mouse_Brain/Visium_FFPE_Mouse_Brain_fastqs.tar -o datasets/Visium_FFPE_Mouse_Brain_fastqs.tar # Download image file to datasets folder curl https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_FFPE_Mouse_Brain/Visium_FFPE_Mouse_Brain_image.jpg -o datasets/Visium_FFPE_Mouse_Brain_image.tif
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 5 4154M 5 218M 0 0 32.7M 0 0:02:06 0:00:06 0:02:00 33.0M
Alternatively, you can also use
wget to download.
# Create datasets folder mkdir datasets # Download FASTQ to datasets folder wget -P datasets/ https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_FFPE_Mouse_Brain/Visium_FFPE_Mouse_Brain_fastqs.tar # Download image file to datasets folder wget -P datasets/ https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_FFPE_Mouse_Brain/Visium_FFPE_Mouse_Brain_image.jpg
Resolving cf.10xgenomics.com (cf.10xgenomics.com)... 126.96.36.199, 188.8.131.52, 2606:4700::6812:1ad, ... Connecting to cf.10xgenomics.com (cf.10xgenomics.com)|184.108.40.206|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 4356188160 (4.1G) [application/x-tar] Saving to: ‘datasets/Visium_FFPE_Mouse_Brain_fastqs.tar’ 37% [=======================> ] 1,649,129,803 207MB/s eta 13s
Since the example dataset is based on mouse tissue section, we can download the latest version of the mouse transcriptome reference available from the Downloads page. Here the
curl download option is highlighted.
# Download mouse reference curl -O https://cf.10xgenomics.com/supp/spatial-exp/refdata-gex-mm10-2020-A.tar.gz
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 1 9835M 1 158M 0 0 34.1M 0 0:04:48 0:00:04 0:04:44 34.1M
Since this is a FFPE tissue sample, the assay uses a pair of oligonucleotide probes targeting protein coding genes. In addition to the reference transcriptome, spaceranger also requires the species specific probe set reference file in
CSV format to enable analysis of FFPE samples. Here the
curl download option is highlighted.
# Download mouse probe set reference curl -O https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_FFPE_Mouse_Brain/Visium_FFPE_Mouse_Brain_probe_set.csv
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 2257k 100 2257k 0 0 5579k 0 --:--:-- --:--:-- --:--:-- 5587k
After successful download of the all the required files, the contents of the tar files need to be extracted before moving onto the next steps.
# Extract sample FASTQ files tar -xvf datasets/Visium_FFPE_Mouse_Brain_fastqs.tar -C datasets/ && rm datasets/Visium_FFPE_Mouse_Brain_fastqs.tar # Extract mouse reference transcriptome tar -xzvf refdata-gex-mm10-2020-A.tar.gz && rm refdata-gex-mm10-2020-A.tar.gz
# Sample FASTQ files Visium_FFPE_Mouse_Brain_fastqs/ Visium_FFPE_Mouse_Brain_fastqs/Visium_FFPE_Mouse_Brain_S3_L002_R1_001.fastq.gz Visium_FFPE_Mouse_Brain_fastqs/Visium_FFPE_Mouse_Brain_S3_L001_I2_001.fastq.gz Visium_FFPE_Mouse_Brain_fastqs/Visium_FFPE_Mouse_Brain_S3_L002_R2_001.fastq.gz ... # Reference mouse transcriptome refdata-gex-mm10-2020-A/ refdata-gex-mm10-2020-A/fasta/ refdata-gex-mm10-2020-A/fasta/genome.fa ...
Successful extraction will create two additional folders, highlighted in bold, within the working directory.
spaceranger_tutorial ├── datasets │ ├── Visium_FFPE_Mouse_Brain │ └── Visium_FFPE_Mouse_Brain_image.jpg ├── refdata-gex-mm10-2020-A ├── Visium_Mouse_Transcriptome_Probe_Set_v1.0_mm10-2020-A.csv └── spaceranger-1.3.1
We now have all the required inputs needed to run the spaceranger count pipeline. To obtain more information about the specifying inputs, print the pipeline specific usage statement.
# Print count usage statement spaceranger count --help
spaceranger-count Count gene expression and feature barcoding reads from a single capture area
USAGE: spaceranger count [FLAGS] [OPTIONS] --id <ID> --transcriptome <PATH> --fastqs <PATH>... <--image <IMG>|--darkimage <IMG>...|--colorizedimage <IMG>> FLAGS: --no-bam Do not generate a bam file --nosecondary Disable secondary analysis, e.g. clustering. Optional --disable-ui Do not serve the web UI --noexit Keep web UI running after pipestance completes or fails --nopreflight Skip preflight checks -h, --help Prints help information ... OPTIONS: --id <ID> A unique run id and output folder name [a-zA-Z0-9_-]+ --description <TEXT> Sample description to embed in output files --image <IMG> Single H&E brightfield image in either TIFF or JPG format --slide <TEXT> Visium slide serial number, for example 'V10J25-015' --area <TEXT> Visium area identifier, for example 'A1' --transcriptome <PATH> Path of folder containing 10x-compatible reference
By default spaceranger expects the hourglass shaped corner fiducial to be in the top left corner.
The input image (top right) is however rotated 90°. To ensure good fiducial alignment and tissue spots detection, it is important to correct for this shift in orientation. There are two ways to achieve this:
--reorient-imagesflag to spaceranger count run which will enable the pipeline to rotate and/or mirror the image
In this tutorial, we will choose the first option of using the
We can now build the spaceranger count command for the example FFPE dataset. We will running the pipeline in our working directory
spaceranger_tutorial assuming the same directory structure as shown previously. The input folder paths below reflect this choice.
In case you have a different setup, amend the paths accordingly prior to running the pipeline to avoid any errors. The easiest method to customize would be to copy the code below in any text editor of your choice (e.g. notepad++), edit and paste it back to the terminal.
spaceranger count --id="Visium_FFPE_Mouse_Brain" \ --description="Adult Mouse Brain (FFPE) using Mouse WTA Probe Set" \ --transcriptome=refdata-gex-mm10-2020-A \ --probe-set=Visium_FFPE_Mouse_Brain_probe_set.csv \ --fastqs=datasets/Visium_FFPE_Mouse_Brain_fastqs \ --image=datasets/Visium_FFPE_Mouse_Brain_image.jpg \ --slide=V11J26-127 \ --area=B1 \ --reorient-images \ --localcores=16 \ --localmem=128For compute platforms connected to the internet, spaceranger uses the value of the
--slideargument to automatically download the slide layout file in
spaceranger count --id="Visium_FFPE_Mouse_Brain" \ --description="Adult Mouse Brain (FFPE) using Mouse WTA Probe Set" \ --transcriptome=refdata-gex-mm10-2020-A \ --probe-set=Visium_FFPE_Mouse_Brain_probe_set.csv \ --fastqs=datasets/Visium_FFPE_Mouse_Brain_fastqs \ --image=datasets/Visium_FFPE_Mouse_Brain_image.jpg \ --slide=V11J26-127 \ --slidefile=V11J26-127.gpr \ --area=B1 \ --reorient-images \ --localcores=16 \ --localmem=128In absence of internet connectivity to the compute platform, you can download this specific slide layout file in
gprformat and provide it to spaceranger using the
Below are brief descriptions of the above command line options.
||The id must be unique string and will be used to name the resulting folder with all of the pipeline outputs. We choose to keep the original dataset name of
||This is sample description included in the output files (e.g.
||The path to the species specific pre-compiled transcriptome files. Note that you can either provide the relative path as shown above or the absolute path to this folder. As the tissue sample was of mouse origin, we provide the path to the mouse reference transcriptome
||The absolute or relative path to the species specific probe set reference file in
||The path to the folder containing sample sequencing files in
||The path to a single brightfield image with H&E staining in either
||The visium slide serial number of which the tissue sample was mounted and the value here is
||The capture area identifier on the visium slide. It can be one of four values: A1, B1, C1 or D1. Here the tissue sample was mounted on
||The slide layout file in
||Flag to allow spaceranger to automatically rotate and/or mirror the image. Useful when the fiducial corners in the input image are not in canonical position (hourglass in top left corner) similar to included image
||The number of CPU cores available to run the spaceranger count pipeline. The maximum upper limit for your specific compute system is determined using the sitecheck subcommand. We will use
||The max memory in GB available to run the spaceranger count pipeline. The maximum upper limit for your specific compute system is determined using the sitecheck subcommand. We will use
When using the |
At the start of the pipeline, you should see the message about the preflight checks printed to the command line.
# Run spaceranger count spaceranger count --id="Visium_FFPE_Mouse_Brain" \ --description="Adult Mouse Brain (FFPE) using Mouse WTA Probe Set" \ --transcriptome=refdata-gex-mm10-2020-A \ --probe-set=Visium_FFPE_Mouse_Brain_probe_set.csv \ --fastqs=datasets/Visium_FFPE_Mouse_Brain_fastqs \ --image=datasets/Visium_FFPE_Mouse_Brain_image.jpg \ --slide=V11J26-127 \ --area=B1 \ --reorient-images \ --localcores=16 \ --localmem=128
# Run spaceranger count spaceranger count --id="Visium_FFPE_Mouse_Brain" \ --description="Adult Mouse Brain (FFPE) using Mouse WTA Probe Set" \ --transcriptome=refdata-gex-mm10-2020-A \ --probe-set=Visium_FFPE_Mouse_Brain_probe_set.csv \ --fastqs=datasets/Visium_FFPE_Mouse_Brain_fastqs \ --image=datasets/Visium_FFPE_Mouse_Brain_image.jpg \ --slide=V11J26-127 \ --slidefile=V11J26-127.gpr \ --area=B1 \ --reorient-images \ --localcores=16 \ --localmem=128
Martian Runtime - v4.0.5 Running preflight checks (please wait)... Checking sample info... Checking FASTQ folder... Checking reference... Checking reference_path... Checking optional arguments... ...
Successful completion of the pipeline is indicated by summary of the output files generated.
Outputs: - Run summary HTML: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/web_summary.html - Outputs of spatial pipeline: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/spatial - Run summary CSV: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/metrics_summary.csv - BAM: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/possorted_genome_bam.bam - BAM index: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/possorted_genome_bam.bam.bai - Filtered feature-barcode matrices MEX: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/filtered_feature_bc_matrix - Filtered feature-barcode matrices HDF5: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/filtered_feature_bc_matrix.h5 - Unfiltered feature-barcode matrices MEX: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/raw_feature_bc_matrix - Unfiltered feature-barcode matrices HDF5: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/raw_feature_bc_matrix.h5 - Secondary analysis output CSV: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/analysis - Per-molecule read information: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/molecule_info.h5 - Loupe Browser file: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/cloupe.cloupe - Target Panel file: null - Probe Set file: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/probe_set.csv - Spatial Enrichment (Moran's I) CSV: /spaceranger_tutorial/Visium_FFPE_Mouse_Brain/outs/spatial_enrichment.csv Waiting 6 seconds for UI to do final refresh. Pipestance completed successfully!
After the run is completed, the working directory will have a new folder named
Visium_FFPE_Mouse_Brain (value provided to
--id argument) that contains all the metadata and outputs generated from the spaceranger count pipeline. We will highlight some key components of this folder (highlighted in bold):
Visium_FFPE_Mouse_Brain ├── _cmdline ├── _filelist ├── _finalstate ├── _invocation ├── _jobmode ├── _log ├── _mrosource ├── outs ├── _perf ├── _sitecheck ├── SPATIAL_RNA_COUNTER_CS ├── _tags ├── _timestamp ├── _uuid ├── Visium_FFPE_Mouse_Brain.mri.tgz ├── _vdrkill └── _versions
outscontains all the final pipeline generated outputs
Visium_FFPE_Mouse_Brain.mri.tgzcontains diagnostic information helpful to 10x Genomics support to resolve any errors
_sitecheckcaptures the system configuration similar to sitecheck subcommand
_timestampcontains information on pipeline runtimes. The runtime for the example dataset with the above configuration was 50:58
_cmdlinecaptures the count command provided to run the pipeline
_versionscontains both the spaceranger and Martian versions used in the run
outs folder contain all the calculated results.
You can further explore and understand these results by
.cloupefile in Loupe Browser for further analysis
Q. I ran spaceranger count with the tutorial example dataset without checking the image orientation. Where would this error be captured ?
After the run is completed, download and open the
web_summary.html file included in the
outs folder using any compatible web browser. For this tutorial dataset, when run without
--reorient-images you will notice two Alerts posted on top of the page: one warning about the low fraction of reads in spots and second suspecting a possible rotated image orientation.