FAQ - STOmics

Q Why does the microscope image appear misaligned and mirrored relative to the gene expression heatmap in my SAW report?

Causes:

The short answer: SAW's input microscope image is not in correct orientation, leading to a failed image registration.

Here are the detailed explanations:

A normal SAW's image registration process is that the microscope image and gene expression heatmap are compared and aligned, resulting in a complete match. A prerequisite is that input microscope image should be oriented in the same direction as the actual sample on the Stereo-seq chip.
The generated gene expression matrix inherently has a mirror-image relationship with the original sample morphology due to the Stereo-seq chip design. To correct this, SAW automatically flips the microscope image once during the image processing.
However, some microscope systems output images that are already mirrored compared to the actual sample. In this scenario, SAW's automatic flipping step will flip the image and the resulting image could not be aligned with the gene expression heatmap, leading to misaligned mirroring in the final registration.

Solutions:

1. For existing SAW analysis with mirroring issues:

Use ImageJ to manually perform a horizontal (or vertical) flip on the original image.
Then use the flipped image for QC and re-run the SAW analysis.

2. Preventive measures:

Check your microscope's default output orientations. Make sure the image orientation matches the acutal sample on the chip.
If the microscope output image appears mirrored compared to original sample, adjust the microscope settings to disable any mirroring options.

flip-EN

Q Why does the StereoMap software (on Windows 11) become unresponsive when uploading images in the Image Processing module?

Cause: The WMIC tool (Windows Management Instrumentation Command-line) is disabled by default in Windows 11 24H2 and later versions. When starting StereoMap while calling WMIC fails, the system will get stuck.

Solution: Manually install WMIC components via the following steps:

"Win + I" to open System Settings → Enter "System"→ Click "Optional features"
Click "View features" → Enter "WMIC" in the search box
Check "WMIC "→ Click "Next" to install
Restart the computer after installation (required)

Repair verification:

After restarting, Press "Win + R" and enter "cmd" to open the command prompt
Enter the command: "wmic diskdrive get caption"
Correct result: Display disk model list information (for example: 'SSD Device 512GB')
Failure result: prompt "Unknown Command",'Wmic' is not an internal or external command'

Note: Starting from StereoMap v4.2, the software has removed the dependency on WMIC, and no additional configuration is required after installation. It is recommended to upgrade to the latest version for a better experience.

EN step1

EN step2

Q Is Bin a square area or a circular area? How to choose the proper Binsize when analyzing?

Bin is a regular NxN square area on the chip. The summary of expression information in the area is the expression information of Bin.
The values of Bin20, 50, 100 and 200 can be adjusted several times according to the cell size of different tissue types and the downstream analysis effect. Where Bin20 is similar to the size of animal cells, Bin50 and Bin100 are Binsize sizes commonly used for analysis. Bin200 is generally used for quick visualization.

Q Why can I get two versions of spatial expression heatmaps for the same sample in StereoMap?

Since StereoMap v4.0, the default display uses the count data of the tissue region. If no microscope image is input during the analysis using SAW v8.0 software, the program will perform tissue segmentation based on the expression information. If the analyst is dissatisfied with the matrix derived from the automatically identified tissue, it may be necessary to reselect the tissue region based on the expression heatmap for the complete chip (using the lasso tool). In this case, StereoMap can plot two count heatmaps for the whole chip and the tissue region respectively.

Q Why is there a slight change in the MID statistical data before and after applying StereoMap lasso?

The main reason is that the calculating logic of the statistical information differs between StereoMap and SAW lasso.

To analyze lasso statistics, first determine if the specified areas contains the center of a given bin. If they do, the data from that bin is statistically counted; otherwise, it is not counted.
SAW extracts the sub-matrix of target by transforming the specified contour region into bin 1 (finest granularity) and then to larger bins.

Screenshot 2025-05-16 at 15.39.04

Screenshot 2025-05-16 at 15.39.14

Q Is it normal for gene expression to be observed outside the chip boundaries during visualization of results in StereoMap under automatic registration?

There are a few reasons that can justify this observation. In the above example, when the visualization shows a combination of the image and the count heatmap, this phenomenon is mostly attributable to two factors：

Since the sample slices are situated at the chip's edges, the tissue segmentation will extend beyond the matrix, creating the illusion of "spillover".
Second, when showing the spatial expression distribution, bin sizes such as bin20 or bin50 are commonly used (used as different resolutions to define a single bin of the analysis unit). The coordinates of these bins are primarily dictated by the bin1 point in the top-left corner of the bin areas. Although the net expression are actually arised from a small fraction of the total capture spots within a given bin, the bin will nevertheless be significantly colored to represent the aggregated expression, resulting in the appearance of "expansion" of expression beyond the chip boundaries.

Q As SAW generates multiple GEF files, what information do they store respectively? Do they support visualization?

GEF is a hierarchical data file format (essentially an HDF5 file) that allows you to flexibly store dense matrices and sparse visualization matrices of different bin sizes to adapt to multiple scenarios of data archiving and visualization. Depending on the usage scenario and frequency, each GEF may not contain the sparse matrix necessary for visualization to reduce storage pressure.

SAW >= 8.0

For more information, please see the [SAW User Manual> Analysis> Outputs > Matrices].

SAW < 8.0

Screenshot 2025-05-16 at 15.33.49

Q How to parse GEF format files?

The use of this function needs to be differentiated according to the SAW version.

SAW >= 8.0:

For format conversion, use SAW convert. Refer to [SAW User Manual > Tutorials > Format conversion].
More details regarding the GEF format and other expression matrix formats, refer to [SAW User Manual > Advanced > Expression Matrix Format]

SAW < 8.0:

Option1: geftools compiled with C ++:

https://github.com/STOmics/geftools

Option2: Use the python package gefpy (e. G. v0.6.1):

https://pypi.org/project/gefpy/
https://gefpy.readthedocs.io/en/latest/index.html
pip install gefpy==0.6.1

Option3: If SAW sif is installed (e. G. v5.1.3):

https://hub.docker.com/repository/docker/stomics/saw
singularity exec SAW_v5.1.3.sif cellCut
Please use singularity 3.8 and above

export HDF5_USE_FILE_LOCKING=FALSE
## gef2gem using geftools
geftools view -i <SN>.gef -o <SN>.gem -s <SN>
# -i input square bin GEF, e.g.SN.raw.gef or SN.gef
# -o output GEM
# -s SN

## gef2gem using gefpy
python
>>> from gefpy.bgef_reader_cy import BgefR
>>> bgef=BgefR(filepath='<SN>.gef',bin_size=200,n_thread=4)
>>> bgef.to_gem('<SN>.bin200.gem')

## gef2gem using SAW sif
## export SINGULARITY_BIND="/path/to/input/dir,/path/to/output/dir"
singularity exec SAW_v5.1.3.sif cellCut view -i <SN>.gef -o <SN>.gem -s <SN>

## cgef2cgem
geftools view -i <SN>.cellbin.gef -o <SN>.cellbin.gem -d <SN>.raw.gef -s <SN>
# -i input cellbin GEF
# -o output cellbin GEM
# -d input square bin GEF, e.G. sn. raw. GEF or Sn. GEF
#-S SN

# # Gem2gef
GEF tools bgef -i <SN>.gem-O <SN>. GEF-B 1,20,50 -O Transcriptomics
#-I input square bin gem
#-O output Square bin GEF
#-B bin sizes seqarate by comma, default: 1,10,20,50,100,200,500
# -O OMICS name

Q How to perform clustering analysis of a gene expression data at a specific bin size?

The use of this function needs to be differentiated according to the SAW version:

SAW >= v8.0:

Use the 'SAW reanalyze cluster' process to set the parameter '-- bin-size' to perform cluster analysis of the specified bin size.
Please refer to the [SAW User Manual > Tutorials > Secondary analysis > Clustering].

SAW < v8.0:

Different binsize options can be set through the '-s' parameter in the spatialCluster pipeline. However, note that the clustering results directly output by SAW only support Bin200 result display by default, which is only used as a rough reference.
If you want to do more precise clustering, recommend you use Stereopy for downstream analysis, this part of the analysis is outside the SAW.

Q If the SAW analysis task is interrupted unexpectedly, can it be resumed from where it left off?

For SAW count pipelines using SAW >= v8.0, if the HPC shuts down unexpectedly, the run is killed, or the job queue runs out of memory, you can restart the cluster/server and resubmit the task. The program will rerun the analysis, but it requires that the command parameters for the two analysis tasks are exactly the same, without any changes. The program will verify this and if there are any differences, it will treat it as a different task for the second time.

Note: This feature is not applicable to issues caused by human factors such as incorrect parameter settings or input data errors.