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

10x Genomics
Visium Spatial Gene Expression

Single-Library Analysis with spaceranger count

Table of Contents

Space Ranger's pipelines analyze sequencing data produced from Visium Spatial Gene Expression for fresh frozen (FF) and formalin fixed paraffin embedded FFPE tissue samples. The workflow diagram shows all the required inputs and the corresponding spaceranger flags for FF tissue samples:

Input files

The spaceranger count is run on each individual Capture Area in the Visium slide. The required inputs are

Run spaceranger count

For a list of accepted arguments, see the Command Line Argument Reference below, or run spaceranger count --help.

Select the tab corresponding to the imaging workflow.


To generate spatial feature counts for a single library using automatic fiducial alignment and tissue detection on a brightfield image input, run spaceranger count with the following arguments. The code in red indicates user specific inputs.

$ cd /home/jdoe/runs
$ spaceranger count --id=sample345 \ #Output directory
                   --transcriptome=/opt/refdata/GRCh38-2020-A \ #Path to Reference
                   --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
                   --sample=mysample \ #Sample name from FASTQ filename
                   --image=/home/jdoe/runs/images/sample345.tiff \ #Path to brightfield image 
                   --slide=V19J01-123 \ #Slide ID
                   --area=A1 \ #Capture area
                   --localcores=8 \ #Allowed cores in localmode
                   --localmem=64 #Allowed memory (GB) in localmode

To generate spatial feature counts for a single library using a fiducial alignment and tissue assignment JSON file generated in Loupe Browser on a brightfield image input, run spaceranger count with the following arguments. The code in red indicates user specific inputs.

$ cd /home/jdoe/runs
$ spaceranger count --id=sample345 \ #Output directory
                   --transcriptome=/opt/refdata/GRCh38-2020-A \ #Path to Reference
                   --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
                   --sample=mysample \ #Sample name from FASTQ filename
                   --image=/home/jdoe/runs/images/sample345.tiff \ #Path to brightfield image 
                   --slide=V19J01-123 \ #Slide ID
                   --area=A1 \ #Capture area
                   --loupe-alignment=sample345.json \ #Manual alignment file
                   --localcores=8 \ #Allowed cores in localmode
                   --localmem=64 #Allowed memory (GB) in localmode
The arguments to specify the fluorescence image can be either --darkimage or --colorizedimage depending on the image format. Details about the different supported fluorescence image formats are described in Image Recommendations.

Following a set of preflight checks to validate input arguments, spaceranger count pipeline stages will begin to run:
Martian Runtime - 4.0.5
 
Running preflight checks (please wait)...
Checking sample info...
Checking FASTQ folder...
Checking reference...
Checking reference_path
Checking optional arguments...
...

Output files

A successful spaceranger count run concludes with a message similar to this:

Outputs:
- Run summary HTML:                         /opt/sample345/outs/web_summary.html
- Outputs of spatial pipeline:              /opt/sample345/outs/spatial
- Run summary CSV:                          /opt/sample345/outs/metrics_summary.csv
- BAM:                                      /opt/sample345/outs/possorted_genome_bam.bam
- BAM index:                                /opt/sample345/outs/possorted_genome_bam.bam.bai
- Filtered feature-barcode matrices MEX:    /opt/sample345/outs/filtered_feature_bc_matrix
- Filtered feature-barcode matrices HDF5:   /opt/sample345/outs/filtered_feature_bc_matrix.h5
- Unfiltered feature-barcode matrices MEX:  /opt/sample345/outs/raw_feature_bc_matrix
- Unfiltered feature-barcode matrices HDF5: /opt/sample345/outs/raw_feature_bc_matrix.h5
- Secondary analysis output CSV:            /opt/sample345/outs/analysis
- Per-molecule read information:            /opt/sample345/outs/molecule_info.h5
- Loupe Browser file:                       /opt/sample345/outs/cloupe.cloupe
- Spatial Enrichment using Moran's I file:  /opt/sample345/outs/spatial_enrichment.csv
 
Pipestance completed successfully!

The output of the pipeline is contained in a folder named with the sample ID specified using --id (e.g. sample345). If this folder already exists, in a rerun with the original parameters, spaceranger will assume it is an existing pipestance and attempt to resume running it. The subfolder named outs contains the main pipeline output files.

outs
├── analysis
│   ├── clustering
│   ├── diffexp
│   ├── pca
│   ├── tsne
│   └── umap
├── cloupe.cloupe
├── filtered_feature_bc_matrix
│   ├── barcodes.tsv.gz
│   ├── features.tsv.gz
│   └── matrix.mtx.gz
├── filtered_feature_bc_matrix.h5
├── metrics_summary.csv
├── molecule_info.h5
├── possorted_genome_bam.bam
├── possorted_genome_bam.bam.bai
├── raw_feature_bc_matrix
│   ├── barcodes.tsv.gz
│   ├── features.tsv.gz
│   └── matrix.mtx.gz
├── raw_feature_bc_matrix.h5
├── spatial
│   ├── aligned_fiducials.jpg
│   ├── detected_tissue_image.jpg
│   ├── scalefactors_json.json
│   ├── tissue_hires_image.png
│   ├── tissue_lowres_image.png
│   └── tissue_positions_list.csv
├── spatial_enrichment.csv
└── web_summary.html
File NameDescription
web_summary.htmlRun summary metrics and charts in HTML format
cloupe.cloupeLoupe Browser visualization and analysis file
spatial/aligned_fiducials.jpgAligned fiducials QC image
spatial/detected_tissue_image.jpgDetected tissue QC image
spatial/tissue_hires_image.pngFull resolution input image downsampled to 2000 pixels on the longest dimension
spatial/tissue_lowres_image.pngFull resolution input image downsampled to 600 pixels on the longest dimension
spatial/tissue_positions_list.csvCSV containing spot barcode, if the spot was called under (1) or out (0) of tissue, the array position, image pixel position x, and image pixel position y for the full resolution image
spatial/scalefactors_json.jsonContains spot diameter estimation in pixels for the full resolution original image, tissue_hires_scalef which is the spot position multiplier in pixels for the high resolution image, fiducial spot diameter estimation in pixels for the full resolution original image, and tissue_hires_scalef which is the spot poisition multiplier in pixels for the low resolution image
spatial_enrichment.csvFeature spatial autocorrelation analysis using Moran's I
analysisSecondary analysis data including dimensionality reduction, spot clustering, and differential expression
metrics_summary.csvRun summary metrics in CSV format
possorted_genome_bam.bamReads aligned to the genome and transcriptome annotated with barcode information
possorted_genome_bam.bam.baiIndex for possorted_genome_bam.bam
filtered_feature_bc_matrixFiltered feature-barcode matrices containing only spot barcodes in MEX format
filtered_feature_bc_matrix.h5Filtered feature-barcode matrices containing only spot barcodes in HDF5 format
raw_feature_bc_matricesUnfiltered feature-barcode matrices containing all barcodes in MEX format
raw_feature_bc_matrix.h5Unfiltered feature-barcode matrices containing all barcodes in HDF5 format
molecule_info.h5Molecule-level information used by additional spaceranger pipelines including aggr, targeted-compare and targeted-depth

Once spaceranger count has successfully completed, you can further explore the results by

Command-line argument reference

ArgumentDescription
--idRequired. A unique run ID string (such as sample345).
--fastqsRequired. Either:
Path of the fastq_path folder generated by spaceranger mkfastq
(such as /home/jdoe/runs/HAWT7ADXX/outs/fastq_path). This contains a directory hierarchy that spaceranger count will automatically traverse.
- OR -
Any folder containing fastq files, for example if the fastq files were generated by a service provider and delivered outside the context of the mkfastq output directory structure.
Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flowcells.
Doing this will treat all reads from the library, across flowcells, as one sample.
--sampleOptional. Sample name as specified in the sample sheet supplied to spaceranger mkfastq.
Can take multiple comma-separated values, which is helpful if the same library was sequenced on multiple flowcells and the sample name used (and therefore fastq file prefix) is not identical between them.
Doing this will treat all reads from the library, across flowcells, as one sample.
Allowable characters in sample names are letters, numbers, hyphens, and underscores.
--transcriptomeRequired. Path to the Space Ranger compatible transcriptome reference.
(such as /opt/GRCh38-2020-A)
--imageRequired for brightfield image input. Brightfield tissue H&E image in JPEG or TIFF format.For more information on image file constraints, encoding and formats refer the Image Recommendations.
--darkimageRequired for dark background fluorescence image input. Multi-channel, dark-background fluorescence image as either a single, multi-layer TIFF file or as multiple TIFF or JPEG files (which can provided as a comma separated list or by invoking the --darkimage parameter multiple times). Details on image file constraints, encoding and formats are described in the Image Recommendations section.
--colorizedimageRequired for color composite fluorescence image input. A color composite of one or more fluorescence image channels saved as a single-page, single-file color TIFF or JPEG. Please see the Image Recommendations section for information on input image file formats.
--slide Visium slide serial number. Required unless --unknown-slide is passed.
--area Visium capture area identifier. Required unless --unknown-slide is passed. Options for Visium are A1, B1, C1, D1.
--slidefile Slide layout file indicating capture spot and fiducial spot positions. Required when no internet access unless --unknown-slide is passed.
--reorient-imagesRecommended. Use with automatic image alignment to specify that images may not be in canonical orientation with the hourglass in the top left corner of the image. The automatic fiducial alignment will attempt to align any rotation or mirroring of the image.
--loupe-alignmentRequired for manual alignment. Alignment file produced by the manual Loupe alignment step. A --image, --darkimage or --colorizedimage, the same image(s) that were used for manual alignment, must be supplied in this case.
--unknown-slideOptional. Set this if the slide serial number and area identifier are unknown. Setting this will cause Space Ranger to use default spot positions. Not compatible with --slide, --area, or --slidefile.
--no-bamOptional. Do not generate a BAM file.
--nosecondaryOptional. Disable secondary analysis, such as dimensionality reduction, clustering, spatial enrichment calculation (Moran's I) and visualization.
--r1-lengthOptional. Limit the length of the input R1 sequence to the first N bases where N is the value supplied by the user. Note that the length includes the Barcode and UMI sequences so do not set this below 28. This and --r2-length are useful for determining the optimal read length for sequencing.
--r2-lengthOptional. Limit the length of the input R2 sequence to the first N bases where N is the value supplied by the user.
--lanesOptional. Lanes associated with this sample.
--localcoresRecommended when run in localmode. Restricts spaceranger to use specified number of cores to execute pipeline stages. By default, spaceranger will use all of the cores available on your system.
--localmemRecommended when run in localmode. Restricts spaceranger to use specified amount of memory (in GB) to execute pipeline stages. By default, spaceranger will use 90% of the memory available on your system.