Space Ranger4.0, printed on 12/26/2024
The Space Ranger pipeline uses automatic image detection algorithms to calculate the location of the fiducial markers, and find the boundaries of the tissue. 10x Genomics tested the algorithms on a wide variety of images, tissues and samples, and found the detection algorithms to be robust. However, there may be cases where the fiducial markers are obscured, or the detected outline is not exactly where the tissue boundary lies. Also, certain tissues, particularly those with holes or gaps, may require more fine-tuning to avoid including background spots in downstream analysis.
Loupe Browser 4.0 and later provide the Visium Manual Alignment Wizard for cases where more manual intervention is required. The wizard makes it possible to interactively align an image to a slide’s Fiducial Marker locations, perform fine-grained tissue selection with a suite of tools, and export the manual alignment into a Space Ranger run. This tutorial walks through this process step-by-step.
The Visium Manual Alignment Wizard can be found on the Loupe Browser start page, at the bottom left, under Align a Visium Image.
Clicking on the link starts the wizard. The wizard’s first page shows a schematic of a Visium slide, including the location of the serial number on the slide, and the location of each capture area on the slide.
Since spot locations can vary subtly between different slides and different capture areas, providing the correct slide and capture area information for the image ensures the most accurate alignment and spot locations possible.
Next, click on Input Alignment Data to bring up the Input Data page, which contains prompts to load an image, and enter slide and capture area information.
The rest of the tutorial assumes the following resources:
The Visium Manual Alignment Wizard accepts the same types of image files as Space Ranger including:
Clicking on Open Image opens a file dialog that filters the current filesystem for compatible image files. Selecting a file triggers a brief loading process. If the computer running the wizard has insufficient RAM to efficiently load the image, the wizard requires confirmation to continue. This is only likely to happen for very large BigTIFF images.
Once the image is loaded, a preview image appears, as shown below.
There are three options for entering slide information.
The Align Image wizard step uses the spot location information from the image and the spot offset file loaded in the previous step to enable interactive manual alignment, using the Fiducial Markers as a visual guide. The spots are aligned with the image, first in a coarse-grained manner through identification of the centers of the Fiducial Markers then in a fine-grained manner by dragging to make small adjustments.
| Fiducial Markers | Shape |
|---|---|
 |
Hourglass |
 |
Filled Hexagon |
 |
Open Hexagon |
 |
Triangle |
Alignment instructions are located on the left side of the page, and the alignment tool is on the right. It is important to follow the instructions carefully, as prompts change subtly at each step. Complete alignment instructions aren’t repeated here, but here are some notes for success:
If one of the corner shapes is obscured by tissue, do a best guess. Fine-grained alignment with three corners should still yield satisfactory results.
If one corner X is not centered, proceed with the remaining corners first, then click Clear Centers to reset.
After selecting and fine-tuning, a red Fiducial Frame is overlaid on top of the image, and the Fiducial Markers should be in alignment, as shown below.
Clicking Continue to move to the next step, Identify Tissue.
Accurate tissue boundary selection yields higher-quality data, lessens the likelihood of background-driven clusters, and provides accurate spot counts for fine-tuning sequencing parameters. When starting on the Identify Tissue page, the barcoded spots, with location inferred from the previous alignment step, are drawn on top of the image, as shown below.
A toolbar to the left of the image provides a variety of tools to perform both coarse-grained and fine-grained tissue selection. The tools are described in the table below.
| Tool | Description |
|---|---|
 |
Zoom In |
 |
Zoom Out |
 |
Move Image - right and left, or up and down |
 |
Lasso |
 |
Label as Tissue Brush (size adjustable) |
 |
Label as Background Eraser (size adjustable) |
 |
Size Adjuster |
A typical tissue selection workflow starts by with the lasso tool. By dragging the lasso around the tissue, it is possible to broadly select the area corresponding to the tissue. Currently selected spots appear to be darker than unselected spots, as shown below. When the drag is complete, a prompt appears. The selected spots can be Label as Tissue, Label as Background, or select Clear Selection to cancel the drag.
The above selection roughly corresponds to the location of the tissue, so Label as Tissue is the appropriate choice. Spots labeled as tissue appear green, and spots labeled background remain gray, as shown below.
In this manner, the Lasso tool can be used to create large areas as tissue, large background areas, or holes in the tissue.
Because of the approximate nature of Lasso tool, there may still be spots labeled as tissue outside the tissue boundary. Use the Zoom tool and more precise label-as-background Eraser tool to refine the boundary. Zooming in two levels, and adjusting the eraser size to approximately two spots wide, provides a good level of control for refining the previous selection.
Both the label-as-tissue Brush and label-as-background Eraser have adjustable sizes, which can be configured through the slider beneath the toolbar. When complete, zooming out should yield a satisfactory tissue boundary.
Return to previous steps in the wizard to fine-tune, make adjustments, restart alignment, restart tissue detection, or enter different data. Once the alignment is satisfactory, the last step is to export the alignment file to Space Ranger. Click Continue from the Identify Tissue step.
The final step, Export to Space Ranger, shows the complete fiducial spot alignment and tissue selection, as shown below.
This image roughly mirrors the alignment preview shown in a Space Ranger web summary. Clicking on the camera icon generates a screenshot of the alignment for record-keeping purposes. Click Export to generate a JSON file, which is named after the slide and capture area, if it was supplied in the Input Data step.
This file is used in the spaceranger pipeline to override automatic fiducial and tissue detection. The pipeline operator needs to run the pipeline with the loupe-alignment argument, with a path to the generated file. For more information, consult the Manual Alignment instructions in the Space Ranger documentation.
Note: It is important to make the alignment file available to both the computing environment where the pipeline is run, and to the pipeline operator.
