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

Space Ranger


Loupe

10x Genomics
Visium Spatial Gene Expression

Space Ranger4.1, printed on 12/22/2024

Manual Alignment

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 H&E images, tissues and samples, and found the detection algorithms to be robust. However, for immunofluorescent images, or in cases where the fiducial markers are obscured or tissue boundaries are unclear, manual fiducial alignment and tissue outlining will be required.

Loupe Browser 4.0 and later provide the Visium Manual Alignment Wizard for immunofluorescent images and other 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.

Entering Alignment Information

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:

Opening an Image

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.

Immunofluorescent/Multi-Channel Image Support

For multi-channel immunofluorescent images, the fiducial markers may only be visible in a single channel. Select one of the pages from the "Page Containing Fiducials" selector to preview other channels. Continue to the next step when fiducial markers are visible in the preview image.

Entering Slide Information

There are three options for entering slide information.

  1. The default mechanism, direct entry of the slide serial number and capture area from which the image was taken, is the preferred mechanism. This option requires an internet connection, as up-to-date slide information is downloaded from 10x. (For offline options, continue reading.) Entering a serial number in the Slide Serial Number text box (V19L29-035 for this tutorial) and pressing Download validates the serial number and loads slide information. The wizard shows a prompt if the slide number is invalid, or the machine does not have an internet connection. A capture area selector is visible after a successful entry. Selecting a capture area unlocks the Start Alignment Process button, and the next step.
  2. The second option is better suited to offline mode, if a spot offset file for the imaged slide is available locally. Clicking on Open Slide File prompts such files, which have the format slide serial.gpr, such as V19L29-035.gpr. Once the file is loaded and validated, a capture area selector is visible. Selecting a capture area unlocks the Start Alignment Process button, and the next step.
  3. Finally, if the serial number and capture area of the image is unknown or the spot offset file is not available, it is still possible to proceed with manual alignment using the third option. Instead of a slide-specific spot offset file, the Visium Manual Alignment Wizard uses an idealized grid layout in the alignment step. The per-spot delta from the ideal grid to the actual slide position is likely to be within 5-15 microns, significantly smaller than the width of each spot. There is some loss of spot precision, but the relationship between spots and the underlying image is still coherent.

Aligning Spots to the Image

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.

Immunofluorescent Image Support

If the fiducial marker channel is dim, it is possible to adjust the appearance of the image while manually aligning by clicking on the "Adjust Image Settings" link at the top of the window. It is possible to adjust the brightness and contrast of the grayscale image, which may make it easier to identify fiducial markers or tissue boundaries.

Clicking Continue to move to the next step, Identify Tissue.

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.

NOTE: For multi-channel fluorescent images, the channel that contains the clearest tissue boundaries may be different from the channel that most clearly shows the fiducial markers. The active channel can be changed by clicking on the Page dropdown under the tissue alignment instructions.

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.

Exporting the Alignment

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.