Format conversion

This tutorial will show how to implement basic format conversions using the complementary pipeline SAW convert. To make this utility more straightforward and concise, several pipelines have been created under SAW convert. The sub-pipeline is usually named as "A2B", which signifies the switching from A-form to B-form (or from A-dimension to B-dimension).

Select the one you need for format conversion.

To make this pipeline more intuitive and user-friendly, the examples based on real demo datasets are given after the function description individually. Please do not restrict yourself to the files and their filenames used in the examples, as they are provided for reference purposes only.

Matrix related

gef2gem

Conversion from a bin GEF to a bin GEM.

Bin GEM is a type of text file that primarily contains gene information, spatial coordinates, and MID counts. The feature expression recorded in a GEM file has only one type of bin size, so you have to set --bin-size for the conversion.

saw convert gef2gem \
    --gef=/path/to/input/bin/GEF \
    --bin-size=1 \
    --gem=/path/to/output/bin/GEM
    
##example test
saw convert gef2gem \
    --gef=./C04144D5.tissue.gef \
    --bin-size=20 \
    --gem=./C04144D5.bin20.tissue.gem

Conversion from a cellbin GEF to a cellbin GEM.

During the conversion from a cellbin GEF to cellbin GEM, it is important to note that the corresponding bin GEF is necessary to obtain DNB information.

Due to the format limitations of cellbin GEF, a bare amount of expression information may be lost during the conversion. If you plan to generate a cellbin GEM, please use the improved bin2cell instead.

saw convert gef2gem \
    --cellbin-gef=/path/to/input/cellbin/GEF \
    --gef=/path/to/input/bin/GEF \
    --cellbin-gem=/path/to/output/cellbin/GEM

gem2gef

Conversion from a bin GEM to a bin GEF.

If your input a GEM is of bin1, the output GEF will be a visualization GEF that includes expression counts of [bin1, 5, 10, 20, 50, 100, 150, 200].

If your input GEM is not of bin1, the output GEF will contain the expression counts of that specific bin size.

saw convert gem2gef \
    --gem=/path/to/input/GEM \
    --gef=/path/to/output/GEF
    
##example test
saw convert gem2gef \
    --gem=./C04144D5.tissue.gem \
    --gef=./C04144D5.tissue.gef

Conversion from a cellbin GEM to a cellbin GEF.

saw convert gem2gef \
    --cellbin-gem=/path/to/input/cellbin/GEM \
    --cellbin-gef=/path/to/output/cellbin/GEF
    
##example test
saw convert gem2gef \
    --gem=./C04144D5.adjusted.cellbin.gem \
    --gef=./C04144D5.adjusted.cellbin.gef

bin2tissue

Extract tissue-coverage expression information from a raw bin GEF.

The tissue segmentation mask is essential for defining the tissue boundaries of a sample, enabling the generation of an expression matrix at the tissue dimension.

saw convert bin2tissue \
    --gef=/path/to/input/GEF \
    --image=/path/to/cell/segmentation/image \
    --output=/path/to/output/directory
    
##example test
saw convert bin2tissue \
    --gef=./C04144D5.raw.gef \
    --image=./C04144D5_ssDNA_tissue_cut.tif \
    --output=./tissue_area_result

If microscope images were not captured during the experimental process, this sub-module could still be applied directly to extract tissue segmentation results based on the transcriptomic expression matrix.

saw convert bin2tissue \
    --gef=/path/to/input/GEF \
    --output=/path/to/output/directory
    
##example test
saw convert bin2tissue \
    --gef=./C04144D5.tissue.gef \
    --output=./tissue_area_result

Under the output directory, there are a bin1_img_tissue_cut.tif of tissue segmentation and <SN>.tissue.gef.

bin2cell

Extract cellbin expression information from a raw bin GEF.

A cell segmentation mask is used to delineate the boundaries of individual cells, which is then utilized to generate an expression matrix at the cell dimension.

saw convert bin2cell \
    --gef=/path/to/input/GEF \
    --image=/path/to/cell/segmentation/image \
    --cellbin-gef=/path/to/output/cellbin/GEF

##example test    
saw convert bin2cell \
    --gef=./C04144D5.tissue.gef \
    --image=./C04144D5_ssDNA_mask.tif \  ## or C04144D5_ssDNA_mask_edm_dis_10.tif
    --cellbin-gef=./C04144D5.cellbin.gef   ## or C04144D5.adjusted.cellbin.gef

From SAW 8.2, bin2cell offers an improved method to generate a cellbin GEM directly from a raw bin GEF. It is highly recommended that you prioritize this conversion method.

saw convert bin2cell \
    --gef=/path/to/input/bin/GEF \  ## if concerned about tissue area, use <SN>.tissue.gef
    --image=/path/to/input/cell/segmentation/TIFF \
    --cellbin-gef=/path/to/output/cellbin/GEF \
    --cellbin-gem=/path/to/output/cellbin/GEM

##example test
saw convert bin2cell \
    --gef=./C04144D5.tissue.gef \
    --image=./C04144D5_ssDNA_mask.tif \  ## or C04144D5_ssDNA_mask_edm_dis_10.tif
    --cellbin-gef=./C04144D5.cellbin.gef \  ## or C04144D5.adjusted.cellbin.gef
    --cellbin-gem=./C04144D5.cellbin.gem  ## or C04144D5.adjusted.cellbin.gem

visualization

Conversion from a raw GEF to a visualization GEF.

A raw GEF typically records the spatial expression matrix of bin1 in a sparse matrix format to reduce file size. Due to the 500nm high precision of Stereo-seq chip, the amout of expression matrix data generated is too large. Unless necessary, the software only retains the bin1 dimension data in a shuffle matrix. For GEF to be visualized in StereoMap, it is necessary to have comprehensive information on various bin sizes, usually with a bin list of [ 1, 5, 10, 20, 50, 100, 150, 200].

saw convert visualization \
    --gef=/path/to/input/GEF \
    --bin-size=1,5,10,20,50,100,150,200 \
    --visualization-gef=/path/to/output/visualization/GEF
    
##example test
saw convert visualization \
    --gef=./C04144D5.raw.gef \
    --bin-size=1,5,10,20,50,100,150,200 \
    --visualization-gef=./C04144D5.gef

gef2h5ad

Conversion from a bin GEF to an AnnData H5AD.

AnnData H5AD is a widely used data format for downstream analysis. And AnnData package version >= 0.8.0.

saw convert gef2h5ad \
    --gef=/path/to/input/GEF \
    --bin-size=20 \
    --h5ad=/path/to/output/h5ad
    
##example test
saw convert gef2h5ad \
    --gef=./C04144D5.tissue.gef \
    --bin-size=20 \
    --h5ad=./C04144D5.bin20.h5ad

Conversion from a cellbin GEF to an AnnData H5AD.

saw convert gef2h5ad \
    --cellbin-gef=/path/to/input/cellbin/GEF \
    --h5ad=/path/to/output/h5ad
    
##example test
saw convert gef2h5ad \
    --cellbin-gef=./C04144D5.cellbin.gef \
    --h5ad=./C04144D5.cellbin.h5ad

gem2h5ad

Conversion from a bin GEM to an AnnData H5AD.

saw convert gem2h5ad \
    --gem=/path/to/input/bin/GEM \
    --bin-size=20 \
    --h5ad=/path/to/output/h5ad

##example test
saw convert gem2h5ad \
    --gem=./C04144D5.tissue.gem \
    --bin-size=20 \
    --h5ad=./C04144D5.bin20.h5ad

Conversion from a cellbin GEM to an AnnData H5AD.

saw convert gem2h5ad \
    --cellbin-gem=/path/to/input/cellbin/GEM \
    --h5ad=/path/to/output/h5ad

##example test
saw convert gem2h5ad \
    --cellbin-gem=./C04144D5.cellbin.gem \
    --h5ad=./C04144D5.cellbin.h5ad

gef2rds

Conversion from a bin GEF to a RDS file.

The RDS file format is a serialized data structure that saves and loads Seurat objects in R.

saw convert gef2rds \
    --gef=/path/to/input/bin/GEF \
    --bin-size=20 \
    --rds=/path/to/output/seurat/rds
 
##example test  
saw convert gef2rds \
    --gef=./C04144D5.tissue.gef \
    --bin-size=20 \
    --rds=./C04144D5.bin20.tissue.rds

Conversion from a cellbin GEF to a RDS file, for analysis in Seurat

saw convert gef2rds \
    --cellbin-gef=/path/to/input/cellbin/GEF \
    --rds=/path/to/output/seurat/rds
    
##example test  
saw convert gef2rds \
    --cellbin-gef=./C04144D5.cellbin.gef \
    --rds=./C04144D5.cellbin.rds

gem2rds

Conversion from a bin GEM to a RDS file.

saw convert gem2rds \
    --gem=/path/to/input/bin/GEM \
    --bin-size=20 \
    --rds=/path/to/output/seurat/rds
    
##example test  
saw convert gem2rds \
    --gem=./C04144D5.tissue.gem \
    --bin-size=20 \
    --rds=./C04144D5.bin20.tissue.rds

Conversion from a cellbin GEM to a RDS file, for analysis in Seurat.

saw convert gem2rds \
    --cellbin-gem=/path/to/input/cellbin/GEM \
    --rds=/path/to/output/seurat/rds
    
##example test  
saw convert gem2rds \
    --cellbin-gem=./C04144D5.cellbin.gem \
    --rds=./C04144D5.cellbin.rds

h5ad2rds

Conversion from an AnnData H5AD to a RDS file, for analysis in Seurat.

saw convert h5ad2rds \
    --h5ad=/path/to/input/anndata/h5ad \
    --rds=/path/to/output/rds/file
    
##example test  
saw convert h5ad2rds \
    --h5ad=./C04144D5.cellbin.h5ad \
    --rds=./C04144D5.cellbin.rds

gef2img

Plot a heatmap of a bin GEF.

It supports using the feature expression matrix to generate a grayscale image heatmap of the spatial expression.

saw convert gef2img \
    --gef=/path/to/input/GEF \
    --bin-size=1 \
    --image=/path/to/output/heatmap/TIFF/image

##example test  
saw convert gef2img \
    --gef=./SS200000135TL_D1.raw.gef \
    --bin-size=1 \
    --image=./res_bin1.tif

Image related

tar2img

Extract TIFF images from an image .tar.gz file. Usually including a microscope image aligned with the matrix, a tissue segmentation image and a cell segmentation image, if required algorithmic or manual processing results are recorded in the image .tar.gz file.

saw convert tar2img \
    --image-tar=/path/to/input/image/tar \
    --image=/path/to/output/folder

##example test
saw convert tar2img \
    --image-tar=./SS200000135TL_D1_SC_20240711_105908_4.1.0.tar.gz \
    --image=./SS200000135TL_D1_image_results

img2rpi

Conversion from TIFF images to an RPI file, used in StereoMap.

Layer names can be set arbitrarily, but follow the format of <stain_type>/<image_type>, like DAPI/TissueMask. For the image of cell segmentation, we recommend you setting the layer name with a prefix of "CellMask", so that StereoMap display cell borders directly.

saw convert img2rpi \
    --image=/path/to/input/image1,/path/to/input/image2,/path/to/input/image3... \
    --layers=<stain_type>/Image,<stain_type>/TissueMask,<stain_type>/CellMask... \
    --rpi=/path/to/output/rpi
    
##example test
saw convert img2rpi \
    --image=./SS200000135TL_D1_ssDNA_regist.tif,./SS200000135TL_D1_ssDNA_mask.tif \
    --layers=ssDNA/Image,ssDNA/CellMask... \
    --rpi=./SS200000135TL_D1.rpi

merge

Merge images (up to three) into one image.

Note that the order of the image input represents its color channel, R-G-B.

saw convert merge \
    --image=/path/to/input/image1,/path/to/input/image2,/path/to/input/image3 \ 
    --merged-image=/path/to/output/multichannel/image

##example test 
saw convert merge \
    --image=./SS200000135TL_D1_ssDNA_regist.tif,./SS200000135TL_D1_ssDNA_tissue_cut.tif \ 
    --merged-image=./SS200000135TL_D1.merged.tif

Merged image of microscopy image SS200000135TL_D1_ssDNA_regist.tif and tissue segmentation mask file SS200000135TL_D1_ssDNA_tissue_cut.tif to evaluate the performance of tissue segmentation.

Part of the merged image of the microscopy image SS200000135TL_D1_ssDNA_regist.tif and cell segmentation mask file SS200000135TL_D1_ssDNA_mask.tif to evaluate the performance of cell segmentation.

overlay

Stack the template points onto the image, to check whether the image template crosspoints derived by image QC are accurate.

The matrix template file, <stain_type>_matrix_template.txt, can be found in visualization.tar.gz.

saw convert overlay \
    --image=/path/to/input/image \
    --template=/path/to/input/template/txt \
    --overlaid-image=/path/to/output/overlaid/image
  
##example test  
saw convert overlay \
    --image=./SS200000135TL_D1_regist.tif \
    --template=./ssDNA_matrix_template.txt \
    --overlaid-image=./SS200000135TL_D1.overlay.tif

Stack the matrix template onto SS200000135TL_D1_ssDNA_regist.tif image to verify the registration outcome.