Read trimming

Alignment for polyA-based assays (Visium v1 and Visium HD 3')

Alignment for probe-based assays (Visium v2 & Visium HD)

Barcode correction

Probe filtering for FFPE tissues

Count UMIs

Binning

Selecting barcodes or bins under tissue

Secondary analysis

Dimensionality reduction

Clustering

Differential expression

Spatial enrichment

LDA-based spot deconvolution

Cell type annotation

Protein expression

References

Read Processing Algorithms

Space Ranger

Visium

Gene Expression

Protein co-detection

Visium Spatial Gene Expression is a next-generation molecular profiling solution for classifying tissue based on total mRNA. Map the whole transcriptome with morphological context in FFPE or fresh frozen tissues to discover novel insights into normal development, disease pathology, and clinical translational research.

Immunofluorescence protein co-detection

Visium CytAssist Gene and Protein Expression

Map the whole transcriptome within the <em>tissue context</em>

Visium CytAssist

Compact instrument designed to simplify the Visium workflow by facilitating the transfer of analytes from standard glass slides to Visium slides.

Spatial Gene Expression

Spatial gene expression profiling and imaging data of fresh frozen or FFPE tissues.

Analyze your Visium Spatial data with microscope images.

Read processing and secondary analysis steps for Visium data

Space Ranger Algorithms: Read Processing & Secondary Analysis

<LinkableSection id={"overview"} title={"Overview"}>

Space Ranger relies on image processing algorithms to solve two key problems with respect to the slide image: deciding where tissue has been placed and aligning the printed fiducial spot pattern. Tissue detection is needed to identify which barcodes/bins will be used for analysis. Fiducial alignment is needed so Space Ranger can know where in the image an individual barcode or bin resides.

These problems are made difficult by the fact that the image scale and size are unknown, an unknown subset of the fiducial frame may be covered by tissue or debris, each tissue has its own unique appearance, and the image exposure may vary from run to run.

If either of the procedures described here fail to perform adequately, users can turn to manual alignment in Loupe Browser. In most cases, the pipeline is not able to indicate that a failure has occurred, and the user is encouraged to check the quality control image in the Summary tab of the [web_summary.html that Space Ranger outputs](/support/software/space-ranger/latest/analysis/outputs/space-ranger-web-summary). Note that the user-supplied full resolution original image is used for downstream visualization in Loupe Browser.

</LinkableSection>

<LinkableSection id={"fiducial-alignment"} title={"Fiducial alignment"}>
Visium contains a system for identifying the slide-specific pattern of invisible capture spots printed on each slide and how these relate to the visible fiducial spots that form a frame around each capture area. The output of this process is a coordinate transform that relates the Visium barcoded slide pattern to the user's tissue image.

From Space Ranger v2.0 onwards, the `spaceranger count` pipeline is run with `--reorient-images=true` by default, which removes the constraint of the hourglass fiducial marker needing to be in the upper-left corner. This is accomplished by running the alignment algorithm against each of the eight possible fiducial frame transformations (all rotations by 90 degrees plus mirroring) and choosing among those the alignment with the best fit.
</LinkableSection>

<LinkableSection id={"fiducial-alignment-v1-v2"} nested={true} title={"Visium v1/v2 fiducial alignment"}>
In Visium, the fiducial frame has unique corners and sides that the software attempts to identify. The alignment process first extracts features that "look" like fiducial spots and then attempts to align these candidate fiducial spots to the known fiducial spot pattern. The spots extracted from the image will necessarily contain some misses, for instance in places where the fiducial spots were covered by tissue, and some false positives, such as where debris on the slide or tissue features may look like fiducial spots.

After extraction of putative fiducial spots from the image, this pattern is aligned to the known fiducial spot pattern in a manner that is robust to a reasonable number of false positives and false negatives.
</LinkableSection>

<LinkableSection id={"fiducial-alignment-HD"} nested={true} title={"Visium HD fiducial alignment"}>

In Visium HD, the capture area is framed by unique concentric ring fiducials. The positions of these fiducials are identified by the pipeline (Calvet et al., 2016) and used for alignment. Some of these fiducials may be missed due to e.g. tissue coverage or debris, but the pipeline requires only a fraction of fiducials to be detected for successful alignment. After extraction of putative fiducial rings from the image, this pattern is aligned to the known fiducial ring pattern.

<SupportCallout>The Space Ranger algorithm was optimized for cases where at least 25% of fiducials are uncovered by tissue. If less than 25% of fiducials are exposed, this may increase the chances that users will need to run manual alignment. </SupportCallout>

</LinkableSection>

<LinkableSection id={"tilt-correction"} title={"Tilt correction"}>
Visium HD requires a high degree of accuracy in the image alignment process. Minor tilting of the CytAssist camera can add a noticeable increase in tissue alignment errors. To correct for this issue, the Visium HD pipeline computes a perspective correction during the fiducial alignment process. This correction is then applied to the CytAssist image to ensure accurate gene expression to tissue alignment.
</LinkableSection>

<LinkableSection id={"tissue-detection"} title={"Tissue detection"}>

In order to restrict Space Ranger's analysis to only those spots or squares where tissue was placed, Space Ranger uses an algorithm to identify tissue in the input brightfield image. This is always performed on the same image as fiducial detection, either the CytAssist image (Visium HD and Visium v2) or the microscope image (Visium v1). Using a grayscale, downsampled version of the input image while maintaining the original aspect ratio, multiple estimates of tissue section placement are calculated and compared. These estimates are used to train a statistical classifier to label each pixel within the capture area as either tissue or background.

In order to achieve optimal results, the algorithm expects an image with a smooth, bright background and darker tissue with a complex structure. Check the web_summary.html. If the area drawn in blue does not coincide with the tissue, you can perform manual alignment and tissue selection in Loupe Browser before running Space Ranger.
</LinkableSection>

<LinkableSection id={"image-registration"} title={"Image registration"}>

Support for CytAssist enabled Gene Expression analysis was introduced in Space Ranger v2.0. This workflow includes the use of CytAssist image which has the fiducial frame and optionally, a microscope image (brightfield or fluorescence image types) of the same tissue section on the standard glass slide. When the two image inputs are provided, the images need to be registered for downstream visualization. Additionally, users can optionally provide the pixel size in microns per pixel (using the command line option `--image-scale`). This helps improve the success rate of tissue registration.

The targeted transformation of the image registration process is the 2D similarity transformation, which includes homogeneous scaling, translation, rotation, and mirroring. Space Ranger v3.1 introduced a new feature matching (FM) algorithm for CytAssist image to microscope image registration, with the objective of improving automatic alignment results in challenging cases where the two images differ significantly. These differences could be multiple imaging modalities (immunofluorescence and H&E), in scaling or unknown scale, reflections, and disjunct tissue regions, such as tissue microarrays.

The FM algorithm attempts to automatically find and match homologous features between the microscope and CytAssist images. Successful FM yields a coarse similarity transform. We have observed that high-contrast distinct local morphological patterns produce the highest quality features for matching. If scale is not provided, Space Ranger makes multiple attempts of FM in parallel, each with a different estimate of the microscope image scale, and retains the best FM registration result. If FM is successful, the Max Mutual Info (MMI) method, which iteratively maximizes the [mutual information metric](https://itk.org/Doxygen/html/classitk_1_1MattesMutualInformationImageToImageMetric.html) from the open source software [ITK](https://itk.org), refines that initial transform to obtain the final transform for full-resolution images. If FM fails, Space Ranger defaults back to the earlier initialization scheme for MMI, described below.

In the absence of a provided initial transform, the pipeline first estimates the proper scaling and translation so the two tissue sections in the images can be roughly overlaid together. If the `--image-scale` is provided, then Space Ranger will use this option without attempting to do additional estimation. Since the correct rotation and mirroring are hard to estimate, the pipeline addresses this by testing eight possible transformations (all rotations by 90 degrees plus mirroring). The estimated scaling, translation, and rotation are used as the initialization to start the registration process. When optimization of all different initializations are complete, the pipeline chooses the best combination based on the smallest metric (entropy) of MMI to output as the final registration results.

</LinkableSection>

<LinkableSection id={"UMI-refinement"} title={"UMI-based refinement"}>

In addition to the steps described above, for Visium HD and HD 3’ data, Space Ranger v4.0 introduced a UMI-based registration algorithm to align the microscope image (H&E) with the underlying UMI count data. Subsequently, v4.1 expanded this capability to support DAPI-stained images. A corresponding CytAssist image and a known slide ID are required. This refinement uses a phase correlation method to ensure that gene expression information is accurately mapped to the tissue morphology. The algorithm works by finding the optimal horizontal (x) and vertical (y) shift to maximize the similarity (computed as cross-correlation) between the microscope image and the UMI count image, both at 2 µm/pixel resolution. The refinement only adjusts the position (maximum +/- 20 µm in each dimension), not scale or rotation. You can disable the UMI registration algorithm using the `--umi-registration` parameter, which is set to `true` by default. This algorithm will not be enabled if `--unknown-slide` is set.

</LinkableSection>

<LinkableSection id={"cell-segmentation"} title={"Cell segmentation"}>

Space Ranger v4.0 introduced cell segmentation for H&E images using the `spaceranger segment` pipeline, and for Visium HD data with H&E images using the `spaceranger count` pipeline. For cell segmentation in Visium HD analysis, Space Ranger utilizes a custom implementation of StarDist (Schmidt et al., 2018), a deep learning model well-suited for the instance segmentation of star-convex shapes, such as cell nuclei. StarDist uses a convolutional neural network (CNN) with a U-Net-like encoder-decoder architecture to extract relevant features from the input image patch. The result is a set of labeled instance masks, represented as star-convex polygons, delineating individual cells. StarDist was chosen because internal testing on a variety of human and mouse tissues demonstrated that StarDist outperformed comparable methods. In particular, StarDist excels at accurately separating closely clustered cells and segmenting cells in highly crowded environments due to its unique approach of predicting radial distances.

10x Genomics trained and benchmarked Space Ranger's StarDist v6 model in house on >17,000 image patches coming from >150 H&E tissue images. Preservation methods tested include FFPE, fresh frozen, and fixed frozen. Tissue types used for training, testing, and benchmarking include:

- Human: thymus, skin (melanoma), prostate, colon, colon cancer, breast, breast cancer, tonsil, thymus, brain, brain cancer, lung, lung cancer, and spleen
- Mouse: brain, bone, testes, small intestine, spleen, embryo, liver, lung, kidney, and thymus

<SupportCallout>10x Genomics expects Space Ranger's cell segmentation algorithm to perform well on species with cell morphologies similar to the human and mouse tissues listed above. However, for species with considerably different cell morphologies (e.g., plants), performance may be poor. In such cases, consider working with the binned data instead.</SupportCallout>

Space Ranger's segmentation model follows a two-step algorithm:

- The custom StarDist model is used to segment nuclei. A mask of the nucleus segmentation is output.
- Visium HD squares are assigned cell IDs. Each barcode is assigned to the closest nucleus up until a maximum distance specified by `--nucleus-expansion-distance-micron`.
  - In some tissues, such as connective tissue or neurons, where nuclei are far from the cell's center or cytoplasm projects extensively, not all squares will be assigned to cells. Consequently, you may observe a lower percentage of reads assigned to cells compared to the corresponding binned data.
- The `spaceranger segment` pipeline, which only has the H&E image as input, skips the second step.

Downstream analysis in `spaceranger count` is then performed on the feature-cell matrix using inferred cell boundaries.

</LinkableSection>

<LinkableSection id={"fluor-intensity"} title={"Fluorescence intensity"}>

This section does not apply to Visium HD. From Space Ranger 2.0 onwards, for Visium v1/v2 data with fluorescence images, the fluorescence intensity in the image at every barcoded location is quantified and is captured in the `barcode_fluorescence_intensity.csv` file. Each page of an input grayscale image is downsampled to the same dimensions as the `tissue_hires_image.png` image that can be found in the `outs/spatial` directory. From there, the pixels are assigned to each barcoded-spot for each page. The location and size of each spot is defined in `tissue_positions.csv` and `scalefactors_json.json`. Space Ranger then calculates the mean and standard deviation of the intensities from pixels that are entirely within the area of the known barcoded-spot location for each page.
</LinkableSection>

<LinkableSection id={"references"} title={"References"}>

Calvet, L., Gurdjos, P., Griwodz, C. & Gasparini, S. (2016). Detection and accurate localization of circular fiducials under highly challenging conditions. _Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition_.

Schmidt, U., Weigert, M., Broaddus, C., & Myers, G. (2018). Cell Detection with Star-Convex Polygons. In _International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI)_ (pp. 265-273). Springer, Cham.

</LinkableSection>


Overview

Fiducial alignment

Visium v1/v2 fiducial alignment

Visium HD fiducial alignment

Tilt correction

Tissue detection

Image registration

UMI-based refinement

Cell segmentation

Fluorescence intensity

Image Processing Algorithms

Steps involved in processing microscope and CytAssist images

Space Ranger Algorithms: Image Processing

10x Genomics Visium Spatial Software Suite

Getting Started

Download Center

Cloud Analysis

Analysis

Tutorials

Algorithms

Advanced

Release Notes

Datasets

Developer Datasets

Loupe Browser

Install Space Ranger and perform a test run

Set up Space Ranger

Learn how to analyze fresh frozen (FF) samples with spaceranger count

Running spaceranger count (FF)

Space Ranger for FF

Learn how to analyze formalin fixed paraffin embedded (FFPE) samples with spaceranger count

Running spaceranger count (FFPE)

Space Ranger for FFPE

Learn how to analyze tissue microarray (TMA) samples with spaceranger count

Analyzing CytAssist Tissue Microarray Data with spaceranger count

Space Ranger for CytAssist TMA

Learn how to use protein expression to filter and visualize your data

Protein Expression Visualization and Thresholding with Loupe Browser

Protein Expression and Thresholding

Learn how to perform reference-free spot deconvolution using a public mouse brain dataset

Spot Deconvolution

Understand pipeline telemetry data collection and learn how to disable it if needed

Space Ranger Pipeline Telemetry

Pipeline Telemetry

View all tutorials

We provide resources from protocols, user guides, and free-to-use analysis tools.

Learn about input files required to run Space Ranger

Inputs

Generating FASTQs

Specifying FASTQs

Image Recommendations

Slide Parameters

Manual Alignment

Segmentation Inputs

Feature Reference

Running Pipelines

Computing Options

Space Ranger Commands

Count

Segment

Annotate

Aggr

Troubleshooting

Learn about the output files generated by Space Ranger

Outputs

Web Summary

Segmented Outputs

Secondary Analysis

Cell Type Annotations

Matrices

Spatial Outputs

Molecule Info (H5)

Feature Slice (H5)

Protein Expression

Metrics Summary

Space Ranger is a set of analysis pipelines that process 10x Genomics Visium data with brightfield or fluorescence microscope images, allowing users to map the whole transcriptome in a variety of tissues.

What is Space Ranger?

<Flex style={{
  flexDirection: 'column',
  gap: '0.5rem'
}}><div><Text as={'span'} size={'small'} weight={'medium'}>{'Starting with v4.0, anonymized telemetry data is collected and sent to 10x Genomics. '}</Text><Anchor href={'https://www.10xgenomics.com/support/software/space-ranger/latest/tutorials/sr-pipeline-telemetry'}><Text as={'span'} color={'inherit'} size={'small'} weight={'medium'}>{'Learn how to disable.'}</Text></Anchor></div><Text as={'p'} size={'small'} weight={'medium'}>The spaceranger mkfastq pipeline is deprecated and will be removed in a future release. Please use Illumina’s BCL Convert to generate Space Ranger-compatible FASTQ files.</Text></Flex>

Algorithms overview

Advanced pipeline content for Space Ranger

Browse Q&As from the 10x Genomics support team

Access free public Visium data from 10x Genomics

A collection of introductions, tutorials, and blogs for data analysis beyond software

Analysis Guides

Loupe Browser is a desktop application for interactive data visualization

Algorithms Overview