StereoMap v3

StereoMap is a HD visualization desktop application intended for displaying Stereo‑seq analysis results. It is designed to let users effortlessly explore data generated by STOmics products. Users can quickly and interactively visualize and mine the spatial data using built‑in widgets. SAW outputs such as gene expression matrix GEF file, image RPI and IPR files, clustering results can be visualized via StereoMap.

Entrance to StereoMap

Entrance to StereoMap in Task

This system provides project data accessible to users. Through the DCS Cloud Platform: (https://cloud.stomics.techopen in new window)‑>Task, click on a chip to access the task list related to the chip number. In the task list, select the taskID starting with T whose "Task Status" is "Complete" to access the data.

Entrance to StereoMap in Tool

Select a project on the DCS Cloud Platform and click the "StereoMap" module of "Tools".

Click StereoMap and select the data you want to open.

Click the Open button and select the data. Supports directory and single file selection.

Note

Users can directly open the visual display of the task directory,and the effect is the same as entering the visualization in the task list..

Supports adding or opening new files.

Tips

File Formats Supported by StereoMap

GEF: Read this file to display the expression heatmap of gene/protein binN. Multiple files of the same format can be included.

LABEL.GEF: The naming rule is "{SN}.{label}.label.gef", where <label> is the customized name of the area. Displayed in the layer panel of StereoMap, the layer name is "Gene/Protein Heatmap_<label>". Multiple files of the same format can be included. For example: "SS200000059_NC.1234.label.gef" will be displayed as "Gene Heatmap_1234" in the layer panel.

CELLBIN.GEF: Read this file to display gene/protein expression matrix Heatmap or cell clustering results at cellbin resolution. Only one file of the same format can be included, such as transcriptomics or proteomics.

RPI: Read this file to display image layers, such as ssDNA, DAPI, IF, H&E, etc. Only one file of the same format can be included.

FOV_STITCHED.RPI / FOV_STITCHED_TRANSFORMED.RPI: Contains the image before registration. It is necessary to open this file and the GEF file simultaneously when using manual registration tool. Only one file of the same format can be included.

.SPATIAL.CLUSTER.H5AD: Contains the cluster and UMAP layer of binN. Multiple files of the same format can be included, but there can be only one transcriptomics or proteomics file of the same binsize.

IPR: Contains the trackline template of the expression matrix and other image information. Reading this file can display the registration template, so as to check whether the image has been registered with the expression matrix. It is recommended to open it with both GEF and RPI files at the same time. Only one file of the same format can be included.

For more information, please refer to: https://github.com/STOmics/SAWopen in new window

Visualization Page

Layout and functionality of the page:

System parameter area: from left to right, there are resolution, image center position coordinates, current mouse position in image coordinates.
Menu bar area: from left to right, there are gene/protein panel, layer panel, binsize panel, manual tools, clustering panel.
Canvas toolbar area: from top to bottom, there are zoom bar, image state operations (save, load, export).
Canvas area: visualize the spatial information of gene expression.
Legend area: display gene/protein/cluster legend and clustering parameter.

System Parameters

Resolution: Physical pitch (nm) between neighboring spots.
Center: The coordinate of image center.
Mouse position: The coordinate of the mouse on the image.

From left to right there are: Gene/Protein Panel, Layer Panel, Binsize Panel, Manual Tools, and Clustering Panel.

Gene/Protein panel

Click the Gene/Protein panel in the menu bar to expand/collapse the panel. It displays the gene/protein expression information of the current main analysis layer. Only when the "Gene/Protein Heatmap" layer is checked, can the corresponding data be displayed on the panel, otherwise the panel will be empty.

Header: "Gene/Protein" is the gene name, "MIDCount" is the MID number of the gene or protein, and "E10" is the score of the gene's or protein's spatial enrichment.
Sorting: Click the small arrow on the right of the table header to sort in ascending or descending order. By default, the list is sorted in descending order by MID number.
Searching: Enter the gene/protein name in “Please enter /Protein…” to search for genes or proteins in the table (The inputs are case‑insensitive, supporting fuzzy & multi‑name search. Please separate names by English commas).
Select gene/protein: Check the check box (in front of the gene/protein name), and the "Selected" group will appear. Heatmap or Multi‑colored display scheme can be chosen on the layer control panel of "Gene Heatmap". For tutorial details, see chapter Transcriptome Data Visualization.
Statistics: In "Gene Heatmap" layer, selects genes/proteins and double‑clicks a bin, statistical information can be displayed.

Page turning: Click "Previous" or "Next" button to turn the page, or enter the page number and press Enter to jump to the page.
Gene/Protein multi‑colored graph palette

It contains the following five parameters: opacity, normalization, brightness, contrast, color picker.

Opacity: Slide to adjust the opacity of the image.

Normalization: Normalize the image data, slide left or right or input a value to adjust its maximum and minimum values. Normalization formula:

Brightness: slide left or right or input a value to adjust the brightness.

Contrast: slide left or right or input a value to adjust the contrast.

Color Picker: Select the color of the gene/protein. Drag the small circle on the color picker or drag the rainbow band to modify the color. Clicking on the common colors can also change the color.

Gene/Protein multi‑colored graph palette

Layer Selection

Click the button to expand the layer panel and click again to collapse it. The layer panel displays all kinds of images including: Image Layer (ssDNA/DAPI, IF, CellMask, TissueMask, etc.), Main Analysis Layer (Gene/Protein Heatmap, Clustering, UMAP).

Click the layer name or the expand arrow to open the layer control panel.
The contents displayed in different control panels are different.
Check the box before the layer name: show/hide the image by checking/unchecking it.

Note

Main analysis layer of different binsizes may be different：

When the .CELLBIN.GEF file is loaded, the Cluster layer can be displayed when the binsize is cellbin;

When the .SPATIAL.CLUSTER.H5AD file of binN is loaded , the Cluster and UMAP layer can be displayed when the binsize is binN

Image Control Panel

For single‑channel layers: Click the layer name to adjust parameters such as color, opacity, normalization, brightness, and contrast.

For multi‑channel layers: Click the layer name to adjust opacity, brightness, and contrast.

Image Control Panel

Gene Heatmap Control Panel

Color Scheme：Provide four color schemes of heatmap to choose from.
Spot Size：Slide or enter the value to adjust the size of the heatmap dots.
Opacity: Slide or enter the value to adjust the opacity of the heatmap.
Color Bar: Control the color bar switch, automatically calculate the range or manually set the range value.
Display Schemes：This option is only displayed after checking the gene/protein, and it is used to select the display scheme of single/multiple genes/proteins. Heatmap is displayed in the form of "Heatmap". Multi‑colored image is displayed in the form of "Multi‑colored", and the color of each gene/protein in the "Selected" group of gene/protein panel can be modified in the "Color" column.

Gene Heatmap Control Panel

Clustering Layer Control Panel

Opacity: Slide to adjust the opacity of the displaying clustering results.
Form of Cells: Contains three options: Filled, Outlined, Both. Users can choose any one to display.
Outlined Color: Adjust the outline color, including four options: white, black, green and cluster color.

Clustering Layer Control Panel

Binsize Selection

Display all resolutions of the current Stereo‑seq Chip data, including bin1, bin10, bin20, bin50, bin100, bin200, bin500, and cellbin (only applicable for Stereo‑seq Chip data that contains cellbin.gef output file). Select the desired resolution in the binsize panel, or hold "Ctrl" while wheeling the mouse to switch.
Auto‑binsize Mode：When this mode is turned on, the binsize size will be automatically switched according to the canvas magnification factor.Bin50 is displayed when the canvas size is <15%, bin20 is displayed when the canvas size is between 15% and 40%, bin10 is displayed when the canvas size is between 40% and 100%, and bin1 is displayed when the canvas size is greater than 100%.

Note

If binsize is too small (such as bin1), the loading speed of the page might slow down due to large amount of data. Please wait patiently. It is recommended to zoom in to a part of the image before switching to a smaller binsize in non‑Auto‑binsize mode.

Comparison of Heatmap with Different Binsize

Comparison of Multi‑colored Graph with Different Binsize

Manual Tools

Setting

Click to open the setting panel, including switches and adjustments for the following components: Scale Bar, Floating Info, Legend, Statistics, Thumbnail and Resolution.

Setting Panel

Undo

Click the icon to return to the previous step, up to 10 steps are supported or use the shortcut key ctrl+z

Reset

Click the icon to clear all current operations and return to the initial state when the file was opened.

Cursor

Click the icon to exit manual tool mode.

Manual Registration

Click the icon to enter the manual registration mode, and click it again to exit.

For detailed tutorial, please refer to Manual Registration.

Lasso

Click the icon to enter lasso mode, and click again to exit.

For detailed tutorial, please refer to Lasso.

Registration template

Click the icon to open the registration template of the expression matrix, which can be used as a reference for image registration.

For detailed tutorial, please refer to Registration Template.

Measure

Click the icon to open the measurement widget, which can measure the distance between any two points.

For detailed tutorial, please refer to Measure__.

Clustering Panel

Clustering panel displays the clustering analysis results. Click the button to expand clustering panel, click again to collapse it.

Optimization：If one or more clusters are selected, the transparency of the image layer is automatically multiplied by this value to highlight the cluster layer when the cluster layer is displayed at the same time as the image layer.
Check box: Click the check box, then the canvas area will display the selected clustering data.
Name: The name of the selected cluster can be modified in clustering panel.
Color: Click the colored circle on the right to open the palette, then selected clustering color by color picker or the color code.

Clustering Panel

Zoom bar: Zoom in or zoom out of the image by dragging the slider, using the mouse wheel, or clicking the zoom in/out button as shown in Figure.

Zoom Bar

Saving status button: Save the current canvas status to check the status later.

Operation: Click the button to open the pop‑up window, input the label of the saving status and click the submit button to save. The status file will be named "Status_<Timestamp>_<Label>" and saved in the "Status" folder under the ManualData/StereoMap data path, such as "Status_202301011010_mousebrain".

Note

A maximum of 10 status records can be saved. After 10 records are saved, the oldest file will be overwritten each time it is saved.

Loading status button: Load a status that has already been saved. Support for importing status files or lasso files.

Operation:

① When loading a status record, click "Load a Status File", select the status file to be loaded in the "Status" folder, and click "Open".

②When loading a lasso record, click "Load a Lasso File", select the lasso file to be loaded in the "Lasso" folder, click "Open" and continue to modify the lasso area.

Image export button: Save the image displayed on the current canvas to the local computer, the file name can be customized.

Screenshot image: A screenshot of the current canvas.
HD image: High definition image of the current canvas. If the legend is displayed, it will be saved as a separate image.

Image Exporting

Canvas

The canvas area displays the tissue's image and spatial expression distribution information.

Zoom in/out: Scroll the mouse wheel to zoom in/out of the canvas.
Move the canvas: Left click and hold the mouse on the canvas and drag to move the canvas.
Floating Info: Hover the mouse on the canvas, it will display the coordinate position (x, y), the number of gene types, the total MID count, etc. Show/hide it through the "Floating Info" switch in "Setting" panel.

Scale bar: Shows the physical scale of the tissue and the selected binsize. . Show/hide it through the "Scale Bar" switch in the layer panel.

Color bar: Assign different colors to the points based on MID count. Show/hide it through the "Color Bar" switch in the control panel of "Gene Heatmap" layer. The range can be customized by users.

Legend

Legend area consists of two parts: the upper part is Legend of Image/Cluster, and the lower part is Statistics.

Legend of Image/Cluster: Show/hide it through the "Legend" switch in "Settings" panel. The legend of image/cluster can be switched.
When there is no "Cluster" layer on the canvas, check~~ing~~ the image layer, or check~~ing~~ the gene/protein list and display in "Multi‑colored" scheme, "Legend of Image" will be displayed automatically.
When there is "Cluster" layer on the canvas, "Legend of Cluster" is displayed by default. If the image layer is checked, or the genes/proteins are checked and displayed in "Multi‑colored" scheme, it can also be manually switched to "Legend of Image".
Statistics: Overall statistics for the current main analysis layer. Show/hide it through the "Statistics" switch in "Settings" panel.
- For "Gene/Protein Heatmap": Includes "Gene/Protein Type" and "MID Count".
- For "Cluster" of cellbin: Includes "Cell Count", "Cluster Count", "Gene/Protein Type" and "MID Count".
- For "Cluster" of binN: Includes "Bin Count", "Cluster Count", "Gene/Protein Type" and "MID Count".

Operating Demonstration

Transcriptome Data Visualization

Check ”Gene/Protein Heatmap" layer: Select a "Gene/Protein Heatmap" or "Gene/Protein Heatmap_<label>" layer in the layer panel.
Expand Gene/Protein Panel: Click to expand gene panel.
Gene/Protein Heatmap of single/multiple gene(s) or protein(s): Click the check box in front of the gene/protein name in the gene/protein panel to display the heatmap of the selected gene(s) or protein(s) by default.

Statistics: In "Gene/Protein Heatmap" layer, selects genes/proteins and double‑clicks a bin, statistical information can be displayed.

Multi‑colored image of single/multiple gene(s) or protein(s): After checking gene(s)or protein(s) in the gene/protein panel, switch "Display Schemes" to "Multi‑colored" in the control panel of "Gene/Protein Heatmap" layer, as shown in the figure below.

Multi‑colored Image of Single/Multiple Gene(s)

Open the layer control panel: When the "Display Schemes" of current layer is "Heatmap", parameters such as Color Scheme, Spot Size, Opacity and Color Bar can be adjusted in the control panel of "Gene Heatmap" layer.

Layer Control Panel

Switch binsize: Expand the binsize panel and click to switch

Note

Switch Binsize

Gene panel operation:
Sorting: Click the small arrow on the right of the table header to sort in ascending or descending order. By default, the list is sorted in descending order by MID number.
Searching: Enter the gene/protein name in “Please enter Gene/Protein…”to search for genes or proteins in the table (The inputs are case‑insensitive, supporting fuzzy & multi‑name search.Please separate names by English commas).
Page turning: Click "Previous" or "Next" button to turn the page, or enter the page number and press Enter to jump to the page.

Gene Panel Operation

Note

The Headmap under Cellbin is only for full gene display for the time being and does not support other operations such as checking genes above.

Color Bar Customization

Click the corresponding "Gene/Protein Heatmap" layer name to open the control panel, and set the "Color Bar".

Color Bar Setting

Color bar setting mode:
Default: Automatic calculation mode. Image color is automatically calculated by software. If this mode is selected, the input boxes of manual setting mode are invalid.
Customized: Manual setting mode. After clicking, you can input the minimum and maximum values in the boxes below. The settings will be applied immediately after clicking "Confirm" button.

Note

In manual setting mode:

Only positive integers can be entered.
The minimum value is not greater than the maximum value.
The upper limit of the maximum value is 50,000,000.
The maximum and minimum values cannot be equal.
This mode ends after selecting automatic calculation.

Automatic Calculation Mode

Manual Setting Mode

Cellbin Data Visualization

Click the binsize panel and select "cellbin".
Cellbin Heatmap:
- Click "Gene Headmap" in the layer panel.
- Click on the gene list: you can view the number of cells in each gene and the MID of the gene.

Cellbin Headmap Operation Guide

Cellbin.
- Click "Cluster" in the layer panel.
- Select the corresponding checkbox in the clustering pan
Exit cellbin: Select other binsize in the binsize panel.

Cellbin Operation Guide

Manual Registration

Click the manual registration tool button to enter manual registration mode.

Select the image to be registered in "Registration layer".
Pan: Enter the number of units to pan in "Step size". Setting 500 units in this example. Tap the up/down/left/right direction buttons, and with each click, the image pans 500 units in that direction.
Feature point: The intersection point of the X and Y axis is the feature point. Rotation and Scale‑X/Y will take the feature point as the origin for transformation, which means the coordinates of feature points remain unchanged. Double‑clicking with the mouse can change the position of feature point.

Flip: Click the flip button to flip the image horizontally around the Y axis.

90° rotation: Click this button to rotate 90 degrees counterclockwise around the feature point.

Normalization: Normalize the image data, slide left or right or input a value to adjust its maximum and minimum values.
Rotation: Rotate the image around the feature point with a small angle. Enter the number, or click the up and down arrow, or drag the slider to adjust the angle. The minimum angle adjustment is 0.01°.
Scale‑X/Y: Take feature points as the center and scale the image in the X/Y axis direction. Input the number or click the up and down arrows to adjust the scale. The minimum adjustment scale is 0.01% of the image length in this direction.
Reset: Click the "Reset" button, the image will then reset to the initial state, that is, pan 0 units, flip 0 times, rotate 0°.
Generate registration result file: Click "Submit" button to generate a registration result file.

How to run the workflow of registration
- If you use data from tasks starting with T: Click Submit after manual registration, and the system will automatically run the registration process.
- If you use data from the "SAW‑ST" standard workflow: After manual registration, click Submit, the system will trigger the registration workflow, fill in the parameters and submit.
- If you use other data:
  - After manual registration is completed, click Submit. The system will generate a json file to store the registration adjustment parameters, which can be viewed in Data.

Tips

Due to network problems, there may be a 5~10min delay in the JSON file displayed in Data. It is recommended to run the workflow every few minutes after submission.

Search for the registration process in the workflow module, fill in the parameters, and click "Next" to run.

Exit manual registration mode: Click the manual registration tool button again to exit. (Clicking the cursor could also work.)

Lasso

Enter lasso mode: Click the lasso tool button to enter lasso mode, and click again to exit.

Enter lasso mode

Add lasso area: Hold down Ctrl, left click the mouse and move to add lasso area. Click the "Add" button and repeat the above operations to add a lasso area again.

Add lasso area

Check/Uncheck lasso area: Double-click the lasso area or click the name to select the corresponding lasso area, then the area can be modified, the canvas cannot be dragged. Double-click the other area or click the name in the window again to deselect it, and the canvas can be dragged when all lasso areas are unselected.
Modify:
- Modify the lasso area: If the area is selected, you can modify it. Hold down Ctrl/Alt to expand/erase the area, right-click to add new outline points, and hold down the right mouse button to drag existing outline points.
- Rename the area: If the area is selected, click "Rename" on the right to change the name. When the system detects an area with the same name, the system will prompt the user whether to merge the area. Click "Yes" to merge the area with the same name.
Delete lasso area: Hold down Alt, left click the mouse and move to delete the lasso area.
Run the lasso workflow:
- If you use data from tasks starting with T: Click Submit after lasso, and the system will automatically run the lasso process.
- If you use data from the "SAW‑ST" standard workflow: After lasso is completed, click Submit, the system will trigger the lasso workflow, fill in the parameters and submit.
- If you use other data:
  - After completing the lasso, click Submit, and the system will generate a json file of the outline area of the lasso, which can be viewed under the "ManualData/StereoMap" path inData module.

Tips

Due to network problems, there may be a 5~10min delay in the GEOJSON file displayed in Data. It is recommended to run the workflow every few minutes after submission.

Search for the "SAW-ST-lasso" in the workflow module, fill in the parameters, and click "Next" to run.
Run the differential analysis workflow: Select the "lasso_markergene" workflow and enter the parameters.

Tips

The difference analysis workflow can only be submitted when you select cellbin, otherwise only the lasso workflow can be submitted.

Import lasso record: Click "Import" button, select "Import Lasso Record", the list will be displayed

Import lasso record

Tips

A maximum of 10 lasso records can be saved, any more will delete the earliest record.

Exit lasso mode: Click the lasso tool button again to exit. (Clicking the cursor could also work.)

Registration Template

The registration template is the trackline template of the expression matrix, which can be used to confirm whether the image layer has been registered with the matrix. This information is stored in IPR file, and this file must be loaded if the template needs to be displayed.

Open registration template: Click the button to open the registration template (consisting of multiple yellow crosshairs).
Zoom in: Wheel the mouse in the canvas area to zoom in until the yellow crosshairs are clearly visible.
Adjust image contrast (take ssDNA as an example): Expand the layer panel, click the layer name to open the layer control panel, adjust Normalized so that a clear trackline can be seen, and observe if the trackline and the registration template fit well. As shown in Figure.
Close the registration template: Click the tool button again to close it. (Clicking the cursor could also work.)

IF Layer Visualization

IF layer can only be displayed when there is corresponding data in RPI file.

Show IF layer: Check the layer of IF protein ("Image" corresponds to the original image, "TissueMask" corresponds to the tissue segmentation area of the protein, and "CellMask" corresponds to the cell segmentation area of the protein). The protein name will be shown in the legend. As shown in Figure .
Change the color: Different colors can be selected for different IF layers. Click the layer name to open the layer control panel and the panel style is the same as that Gene/Protein multi‑colored graph palette.
Exit IF layer: Uncheck the layer name to exit.

Measure

The gadget mainly measures the distance between two points in PX (pixel), and the applicable layers include Image Layer and Analysis Layer (Heatmap and Clustering layer).

Open measure: Click the "Measure" button to enter the operation page of the ranging gadget.
New measure: Left‑click anywhere to add the starting point of measurement, then left‑click again to add the end point of measurement. The operation can be repeated to add multiple measurement distances. As shown in Figure.

Add multiple measurement distances

Delete measure: Place the mouse on a certain line to be deleted. When the mouse icon changes into a hand shape, left‑click and press "Del" on the keyboard to delete a certain line.
Move the measured distance: Place the mouse on a certain line where the distance has been measured. When the mouse changes to a hand shape, the left mouse button can move a certain line where the distance has been measured.
Exit measurement: Click "Cursor" to exit measurement mode.

Run the registration and Lasso

Registration

Enter visualization from tasks starting with T: Click Submit after manual registration, and the system will automatically run the registration process.

Enter StereoMap from Tool:

After manual registration is completed, click Submit. The system will generate a json file to store the registration adjustment parameters, which can be viewed in Data.

Note

Due to network problems, there may be a 5~10min delay in the json file displayed in Data. It is recommended to run the workflow every few minutes after submission.

If the entered data is running a standard process, you need to do the following operations after manual registration: search for the registration process in the workflow module, fill in the parameters, and click Next to run.

If the input data is running the SAW‑ST prefix process, after manual registration, click Submit, the system will call the registration workflow, fill in the parameters and submit.

Note

If the input data is the output of a standard process, the registered input parameters will be filled in automatically; otherwise, the user needs to fill them in manually.

Lasso

Enter visualization from tasks starting with T: Click Submit after lasso, and the system will automatically run the lasso process.

Enter StereoMap from Tool:

After completing the lasso, click Submit, and the system will generate a json file of the outline area of the lasso, which can be viewed in the Data module.

Note

Due to network problems, there may be a 5~10min delay in the geojson file displayed in Data. It is recommended to run the workflow every few minutes after submission.

If the input data is running a standard process, after lasso is completed, click Submit, and the system will automatically start the lasso process and generate the corresponding task order number. (Same as T task logic)

If the input data is running the SAW‑ST prefix process, after lasso is completed, click Submit, the system will call the lasso workflow, fill in the parameters and submit.

Note

If the input data is the output of a standard process, the input parameters will be filled in automatically; otherwise, the user needs to fill them in manually.

View the status of the task

Check the running task status in the task module.

StereoMap v3

# StereoMap v3

# Entrance to StereoMap

# Entrance to StereoMap in Task

# Entrance to StereoMap in Tool

# Visualization Page

# System Parameters

# Menu Bar Area

# Gene/Protein panel

# Layer Selection

# Binsize Selection

# Manual Tools

# Canvas Toolbar

# Canvas

# Legend

# Operating Demonstration

# Transcriptome Data Visualization

# Color Bar Customization

# Cellbin Data Visualization

# Manual Registration

# Lasso

# Registration Template

# IF Layer Visualization

# Measure

# Run the registration and Lasso

# Registration

# Lasso

# View the status of the task

StereoMap v3

Entrance to StereoMap

Entrance to StereoMap in Task

Entrance to StereoMap in Tool

Visualization Page

System Parameters

Menu Bar Area

Gene/Protein panel

Layer Selection

Binsize Selection

Manual Tools

Canvas Toolbar

Canvas

Legend

Operating Demonstration

Transcriptome Data Visualization

Color Bar Customization

Cellbin Data Visualization

Manual Registration

Lasso

Registration Template

IF Layer Visualization

Measure

Run the registration and Lasso

Registration

Lasso

View the status of the task