10x Genomics
Visium Spatial Gene Expression

Space Ranger6.1, printed on 12/26/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 onwards provides 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.

Loupe Browser 5.1 onwards includes the option to load an additional overexposed capture to facilitate fiducial selection for immunofluorescent images. This overexposed capture can be included as an additional channel in the same image file, or as a separate image file, depending on imaging system capabilities. This capture is excluded from downstream analysis in Space Ranger and Loupe Browser.

The tutorial below demonstrates the alignment steps for a single-channel brightfield image, and a multi-channel immunofluorescent image for steps that differ.

Table of Contents

• Accessing manual alignment
• Step 1. Upload images
• Step 2. Slide information
• Step 3. Identify fiducials
  • Image settings
  • Select fiducial corners
• Step 4. Adjust fiducials
• Step 5. Identify Tissue
• Step 6. Export

Accessing manual alignment

The Visium Manual Alignment Wizard can be found on the Loupe Browser start page, at the bottom of the main panel.

Clicking on the link starts the wizard in a new window and shows a pop up window listing the steps required for completion. Click Got it! to exit out of the pop up window. Selecting the box for Don't show this again will bypass the pop window the next time the wizard is started.

Step 1. Upload images

The Visium Manual Alignment Wizard accepts the same types of image files as Space Ranger. Refer to the input image recommendations page for more details.

	Image Format
Brightfield Image	24-bit color TIFF/BigTIFF or a JPEG
	16-bit grayscale TIFF/BigTIFF or a JPEG
Fluorescence Image	8 or 16-bit grayscale single, multi-page TIFF/BigTIFF
	8 or 16-bit grayscale multiple single-page TIFF/BigTIFF or a JPEG
	24-bit single colored image TIFF/BigTIFF or a JPEG

Clicking on Upload image under the Image for alignment panel 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. Note that clicking on the How it works on the lower left corner brings up the pop up window.

Select the tab corresponding to the different starting image types.

• Brightfield Image
• Fluorescent Image

Step 2. Slide information

Visium slide serial number and capture areas are important parameters that are specified in this step.

There are three options for entering slide information in the Visium Manual Alignment Wizard.

Loupe Option	Internet Access	Details
	Yes	The wizard will download the layout file associated with the supplied serial number. The wizard shows a prompt if the slide number is invalid, or the machine does not have an internet connection. Capture area selector is visible after a successful entry.
	No	User downloads a layout file in gpr format for a Visium slide before running the manual alignment. Once the file is loaded and validated, the capture area selector is visible. Download Slide Layout File
	Optional	The wizard uses an idealized grid layout in the alignment step. The typical per-spot difference between the default layout and a specific slide is within 5-15 microns, significantly smaller than the width of each spot.

Select the tab corresponding to the different starting image types.

• Brightfield Image
• Fluorescent Image

Step 3. Identify fiducials

This step uses the spot location information from the image and the slide layout 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.

Loupe Browser 6.1 brings many new features and functionality that enhance the manual alignment experience. These are:

• the ability to manually align using any three corner fiducial markers which can also be chosen in any order.
• the ability to zoom into the image using the zoom sliders
• the ability to use keyboard shortcuts for key actions
• the Auto function that apply uniform brightness scaling across all pixels in the image
• the ability to collapse the instruction panel to expand the image window

Image settings

If the fiducial markers or tissue boundaries are dim, it is possible to adjust the brightness, contrast, saturation, and opacity of the image, which may make it easier to identify these features.

When set to on, the Auto toggle adjusts the brightness of the image across all the pixels with the goal to enhance the dark and bright pixels. It does so by mapping the original image brightness values [min, max] to a new range and rescaling it back to the full brightness spectrum [0, 255]. Note that the Auto toggle is independent of the manual image settings and can be used in combination with one or more of the other image settings.

For multi-channel immunofluorescent images or when using an auxiliary image, it is important to begin by selecting a channel where fiducials are most clearly visible. Use the Image Channel dropdown to select the correct channel. This may be an overexposed channel in the same file that you plan to discard downstream in your analysis.

If an auxiliary overexposed image was loaded in the previous step, it will be accessible as an additional option in the Image Channel dropdown at the Identify fiducials step for fiducial selection. This image must have the same resolution as the first image loaded for alignment.

Select fiducial corners

Visium slides have four unique fiducial corner shapes:

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 and it is critical to map each unique shape correctly.

Selection of each fiducial corner results in a colored ＋ on the image and a matching ✓ on the instruction panel. Successful marking of at least three corners results in a red fiducial frame overlaid on top of the image. Click to revert selections at any time. Appearance of the red fiducial unlocks the Next to continue to step 4, Adjust fiducials.

Step 4. Adjust fiducials

While the placement of the red frame usually matches the fiducial frame on the image, in some instances fine-grained tuning may be required. In this step, you can achieve this dragging the corner ＋ shapes to adjust the alignment of the red spot outlines to the fiducial frame in the image. Zoom in over the frame to identify misalignment and correct them by clicking and dragging the ＋. There are three options to zoom into the image using either the mouse wheel, zoom slider or the newly introduced keyboard shortcuts.

While fine-grained tuning is highly recommended to avoid any alignment errors, this step is optional and you can click Next to continue.

Step 5. 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 options to perform both coarse-grained and fine-grained tissue selection.

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 Image Channel dropdown under the tissue alignment instructions. For the tutorial dataset set the channel to 3 for this step.

Key details for when using the tools:

• Zoom can be independently applied in combination with any of the tools
• All the four main tools Pan , Lasso , Brush and Eraser can be operated only one at a time
• Use the Fit in View anytime to restore the image to the default view.

There are two possible ways to select the tissue associated spots which appear green upon selection:

• Use of Select all spots and pruning using a combination of Lasso and the Eraser tool. This is particularly useful when the tissue section occupies a large portion of the capture area.

• Use of a combination of Lasso , Brush and Eraser tools to select the tissue regions. Lasso can be used to select large areas of tissue while precise selection can be achieved using the combination of Brush and Eraser especially around the tissue boundaries.

Note that you can return to previous steps in the wizard to fine-tune, make adjustments, restart alignment, restart tissue detection, or enter different data. If alignment is satisfactory, click Next to continue to the last step in the manual alignment worklfow.

Step 6. Export

The final step shows the complete fiducial spot alignment and tissue selection. Click Export alignment JSON file to generate a JSON file, which is named after the slide and capture area, if it was supplied in Slide information step.

The image roughly mirrors the alignment preview shown in a Space Ranger web summary file. Use Save the summary image option for record-keeping purposes. Click here opens the Space Ranger count page in a new tab in a browser window.

For multi-channel immunofluorescent images where an overexposed capture was added as a channel in the main image file, there is an option to exclude this channel from downstream analysis. This is highly recommended to ensure that the tissue is clearly visible in the web summary and Loupe Browser analysis. Click Select the overexposed channel option and in the pop-up window select the channel and click Save to exit. An auxiliary image will be excluded by default.

The path to the generated JSON file is provided to spaceranger count pipeline via the loupe-alignment argument. 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 spaceranger count and the computing environment where the pipeline is run.