# Nuclei-staining + Immunofluorescence Image ## Why Nuclei-staining + Immunofluorescence Image? Immunofluorescence (IF) is a widely used image-based technique to visualize the subcellular distribution of the proteome in cells. For instance, nuclei can be stained with DAPI, while T cells can be identified using CD3. Multiplex IF (mIF) can be tagged on the tissue section and scanned by the fluorescence microscope simultaneously. Stereo-seq experiments and bioinformatics analysis tools are compatible with DAPI and up to 6 user-defined IFs, enabling spatial discovery across a tissue sample. ## Considerations for Nuclei-staining Images and Immunofluorescence Images Since each of the selected IFs has a specific fluorescence spectrum and all of them are applied together on the same tissue slice, there are several challenges to consider, especially in the IF selection and imaging platform. Each IF has a specific fluorescence spectrum and it's essential to manage the degree of spectral overlap among the IFs you choose. Additionally, it is crucial to consider the available emission and excitation filters of your imaging platform. The fluorescence microscope scans tissue areas with IF tags either by switching the filter at the same scan area until the whole tissue area has been reached or by switching the filter after scanning the entire tissue area. Both methods require keeping the chip in place without any movement between each scan to ensure the tissue position in the IF images remains consistent in terms of both scale and orientation. Processing nuclei-staining + mIF images in StereoMap and SAW requires a set of individual acquisitions stored in a single-page grayscale file at 8 or 16-bit depth. (See [Image Types and Format](/stereomap-user-manual-v4.2/tutorials/navigation-for-image-processing.md#image-types-and-format) for more information)

Fluorescence Image	Data Type and File Format
Grayscale image	Multiple 8 or 16-bit grayscale single-page image files

## Step 1: Upload Image

Click on **Choose file** in the drag-and-drop box to upload a compatible image file from your file system, or drag and drop the file(s) into the box. If your input image file is either a `.tar.gz` or a `.stereo` file, drag and drop it only once to the left-side box. However, if your input file format is `.tif` or `.tiff`, you need to drop your nuclei-staining DAPI image to the left-side box and select and drop all your IF images to the right-side box together. Please visit [**Image Processing Input Files**](/stereomap-user-manual-v4.2/getting-started.md#image-processing-input-files) for detailed image file information.

After selecting a file, the system will parse the image and extract necessary data. Parsing time may vary depending on the file type and size. Stereo-seq chip serial number (SN) and microscope setting provide important information in the image processing steps. The `.tar.gz` or `.stereo` the input file contains these data, so the parsing process will start directly.

If your input file is is `.tif` or `.tiff`, you'll need to manually enter the required information specified in this step and click **Confirm** to begin parsing and quality check. Once parsing and quality checks are complete, click **Next** to proceed to Step 2. ## Step 2: Image Registration In this step, you will need to adjust the orientation, position, and scale of the image to align each of them with the spatial feature expression matrix. StereoMap provides two registration approaches for aligning images in the context of Stereo-seq data analysis. 1. [**Morphology Registration**](#morphology-registration): Aligns image with matrix based on the similarity of their morphology. 2. [**Feature Point Registration**](#feature-point-registration): Aligns image to the trackline template deduced from the Stereo-seq chip SN by marking a key point. There’s no need to bring in a spatial feature expression matrix generated by SAW, but some prerequisites should be taken into account.

### Morphology Registration If you upload the `.stereo` file in step 1, you can see the image and the spatial feature expression matrix once enter step 2. For `.tar.gz` or `.tif/.tiff` image file, you will need to add a `.stereo` file for specifying a spatial feature expression matrix as the reference. Click

to select the `.stereo` file. Or, if your images are in the `.stereo` file, but you want to change the reference expression matrix, you can click the

and load a new file. This action will reload the matrix, but use the images from step 1.

The registration process involves two stages, roughly matching the orientation of the image based on the morphology and finely adjusting the position and scale for exact overlap with the the spatial feature expression map. You can also choose "Chip tracklines" to display tracklines that are derived from the spatial feature expression matrix to help with fine alignment. To roughly align the image, you need to match the microscope image and the feature density map in orientation. * Use the **Flip tool**

to mirror the image. * Click on

and use the **Control knob**

to rotate the image in the same direction. Once the orientation of the image and the spatial feature expression matrix have matched, you can move on to the fine-alignment steps. In the fine-alignment stage, you will need to move the image to the place where the tissue can overlap. * Use the **Move panel**

by setting the step size and pan move in four directions. * The dimension of the microscope image might differ from the spatial feature expression map, you can adjust scales using the **Scale tool**

. You can align the image by checking "Chip tracklines" to show the reference trackline template and let the tracklines fall directly overlapped. At this time, the chip trackline template is a representation of the matrix. If the tracklines are dim, the **Normalization**

, **Contrast**

, **Brightness**

, and **Opacity**

of the image can be adjusted manually. In the case of IF images, the tracklines might not be visible directly from the image. However, altering the matrix color could help to bring out some hidden patterns.

{% hint style="info" %} The images are adjusted to optimize the visibility of tracklines. {% endhint %}

{% hint style="info" %} Adjusting **Saturation**

will not affect the grayscale image. {% endhint %} For IF images in which the tracklines cannot be seen, we assume that the IFs were taken in exactly the same orientation as the nuclei-staining image. Since StereoMap >=4.1, the parameters from the nuclei-staining image will be automatically applied to all the IFs. {% hint style="info" %} After the image has been aligned with the matrix, steps 3 and 4 can be bypassed. You can export the semi-processed `.tar.gz` image directly and feed this output to SAW for automatic segmentation. In addition, a `*regist.tif` image file will be provided. This is a reoriented image that matches the shape and orientation of its corresponding feature expression matrix. This image serves as the starting point for tissue and cell segmentation. **If you’re considering using other external segmentation tools or algorithms, it’s strongly advised to utilize this `*regist.tif` file as the input.** {% endhint %} ### Feature Point Registration Registration with feature points involves aligning images without the need for a feature expression matrix. It uses tracklines detected from the image and lines from the chip mask according to predefined rules. {% hint style="info" %} **Prerequisite to accessing this approach:** 1. Image must pass QC: this ensures the tracklines are visible. 2. Valid Stereo-seq chips that follow the predefined rules: Stereo-seq N FFPE V1.0, Stereo-seq T FF V1.3, or Stereo-CITE T V1.1 chips. {% endhint %} To ensure that the two sets of lines match, you must also identify a specific point to indicate the orientation of the image; otherwise, the auto-alignment may fail. **Requirements to select the correct feature point and get the correct registration result:** 1. The tissue's orientation in the image matches its placement on the slide, with the slide's engraved label on the right. The maximum tilting angle allowed is less than 15°.

2. The four chip edges/corners can be seen from the image. 3. The imaging process has strictly followed the instructions specified in [**Microscope Assessment Guideline**](https://enfile.stomics.tech/STUM-PE001%20Microscope%20Assessment%20Guideline_ver%20C.pdf) **- Chapter 3 Microscope Imaging Guidelines - 3.2.2. Precautions for Experimental Operations**. You can access it from [STOmics](https://en.stomics.tech/) -> [Resources Documents](https://en.stomics.tech/resources/documents/list.html). {% hint style="warning" %} If your image cannot fulfill **all the requirements**, we highly recommend you perform the [**Morphology Registration**](#morphology-registration). {% endhint %}

{% hint style="info" %} Feature point registration begins with an image that has been adjusted for rotation and scaling. {% endhint %} The process of feature point registration involves two stages: * **Adjusting Image Visibility**: To ensure all four edges and corners of the chip are clearly visible. * **Selecting a Reference Point**: To set it as the reference.

To ensure all four sides of the chip are visible, you can manually adjust the image's **Normalization**

, **Contrast**

, **Brightness**

, and **Opacity**

Once you can see the chip, identify a predetermined point **within the chip region that is nearest to the bottom-left corner**. Click on this point to select it, and then click **Next** to complete the registration.

Once the reference point is selected, the system will automatically adjust the image's orientation. The aligned result will be displayed in [**Step 3: Tissue Segmentation**](#step-3-tissue-segmentation). {% hint style="info" %} Once the image is aligned with the matrix, **Steps 3 and 4 can be skipped**. You can export the semi-processed **`.tar.gz`** file and use it as input for SAW to perform automatic segmentation. Additionally, a **`_regist.tif`** file will be generated. This reoriented image is adjusted to match the shape and orientation of its corresponding feature expression matrix, serving as the starting point for tissue and cell segmentation. **If you plan to use other segmentation tools or algorithms, it is strongly recommended to use the `_regist.tif` file as input**, as other **`.tif`** files may fail to import due to discrepancies in image and matrix dimensions. {% endhint %} ## Step 3: Tissue Segmentation {% hint style="info" %} **Tissue Segmentation** is a skippable step. {% endhint %} In this step, you will define the tissue regions. Precisely identifying tissue boundaries helps minimize background interference, improving the accuracy of clustering results. The segmented tissue regions from the image will be mapped onto the sequencing-based spatial feature expression matrix, generating a feature density map for the tissue. For **IF images**, focus on regions with **strong immunofluorescence intensity** rather than strict tissue boundaries.

{% hint style="info" %} If you upload the `.stereo` file in step 1, you can see a semi-transparent mask overlapped on the registered microscope image. For `.tar.gz` or `.tif/.tiff` image file, you will need to use tools to draw the tissue region. {% endhint %} ### Segmentation of the Nuclei-staining image In the Tissue Segmentation step, you can edit the recorded mask or create a new one. The panel of tissue identification for the nuclei-staining image is under the **Tissue Seg** tab. The tissue mask recorded in the `.tar.gz` or `.stereo` file appears as "**RECORD**" in the **Segmentation mask** dropdown, while manually drawn or imported masks are labeled as "**CUSTOM**". Select a mask from the dropdown to update the canvas display.

To select or edit the tissue region, use a combination of **Lasso**

, **Brush**

, and **Eraser**

tools. * **Lasso** **Tool**: This tool is typically used for selecting or deselecting large areas. It allows you to draw a freehand selection around the region of interest. * **Brush** **Tool**: This tool is more suitable for smaller areas, such as regions around tissue or fill in small holes in the tissue. It allows you to paint over specific areas to include or exclude them from the selection. * **Eraser** **Tool**: Similar to the Brush tool, the Eraser tool is used for smaller areas. It allows you to remove or deselect specific regions within the larger selection.

If you have created a `.tif` format binary mask file using a third-party tool, you can import it by: * Click on the **Segmentation Mask** dropdown menu on the right panel. * Select **Add Mask**

in the **CUSTOM** category to import mask. * Navigate to your `.tif` binary mask file from your file system and click **Open** to import it. If the imported result is unsatisfactory, you can replace it with a new mask * Click on the **Segmentation Mask** dropdown menu again. * Select the **option with**

in the **CUSTOM** category to replace mask. * Navigate to your `.tif` binary mask file from your file system and click **Open** to import it.

### Segmentation of the IF images To identify regions where the protein is actively expressed from the IF images, go to the **Gray Scale** tag. First, select the active IF image from the **Immunofluorescence image** dropdown.

Then, adjust the sliders for the **Fluorescence intensity threshold**. The pixels in the image whose values fall within the selected range will be kept as the region of the IF.

## Step 4: Cell Segmentation {% hint style="info" %} **Cell Segmentation** is a skippable step. {% endhint %} Cell segmentation is a key step in generating single-cell spatially resolved feature expression data.

{% hint style="info" %} In the current version, cell segmentation is only performed on the nuclei-staining image. If you upload the `.stereo` file in step 1, you can see the red outlines of the cells/nuclei on the registered microscope image. For `.tar.gz` or `.tif/.tiff` image file, you will need to use tools to label cells. Cell segmentation is applicable only within the tissue region. Therefore, the areas not encompassed in the Step 3 Tissue Segmentation will appear as a black background.

{% endhint %} Similar to Tissue Segmentation, you have the option to edit the mask that was previously recorded (tagged with "**RECORD**") or create a new one (tagged with "**CUSTOM**"). Change the active mask by selecting from the **Segmentation mask** dropdown.

StereoMap offers three ways to refine your cell segmentation: 1. [**Import a Cell Segmentation Mask**](#import-a-cell-segmentation-mask)\ Use third-party tools or algorithms to segment cells on your registered image and import the result for Stereo-seq analysis. This method is **best if you have high-quality segmentation results from third-party tools and want to seamlessly integrate them into your Stereo-seq analysis.** It is ideal for large datasets or when using advanced segmentation models. 2. [**Parameter-Adjustable Semi-Automatic Tool**](#parameter-adjustable-semi-automatic-tool)\ This method allows you to apply automated segmentation across the entire tissue or within a selected region, with adjustable parameters for optimization. It is recommended when you **need a quick and efficient way to refine segmentation while maintaining flexibility**. This approach works well when the initial segmentation is decent but requires parameter tuning to improve accuracy, especially in cases with variable cell density. 3. [**Manual Refinement with Drawing Tools**](#manual-refinement-with-drawing-tools)\ Using drawing tools like the **lasso, brush, and eraser** for precise manual cell segmentation adjustments. This method is most suitable for **precise corrections in small regions**, such as separating clustered cells, correcting segmentation errors, or handling complex regions where automated methods struggle. It is ideal for small datasets or cases requiring detailed, cell-by-cell refinement. ### Import a Cell Segmentation Mask If you have already segmented cells using external tools, you can easily import the `.tif` format segmentation mask generated from the registered image and use it directly in your Stereo-seq analysis. 1. Click on the **Segmentation Mask** dropdown menu again. 2. Select the **option with**

in the **CUSTOM** category to replace mask. 3. Navigate to your `.tif` binary mask file from your file system and click **Open** to import it. If the imported result is unsatisfactory, you can replace it with a new mask 1. Click on the **Segmentation Mask** dropdown menu on the right panel. 2. Select **Add Mask**

in the **CUSTOM** category to import mask. 3. Navigate to your `.tif` binary mask file from your file system and click **Open** to import it.

### Parameter-Adjustable Semi-Automatic Tool The [**parameter-adjustable semi-automatic tool**](#parameter-adjustable-semi-automatic-tool) provides a balance between automation and control, allowing you to refine segmentation by adjusting key parameters to better fit your tissue sample. 1. Click on the **Automated Segmentation** dropdown menu on the right panel, and choose **Watershed**. Once selected, the **Box select** ![](/files/VZT2CW5Ym1hLSF5a4FpT) **mouse tool** will be activated and ready for use.

2. Use the **Box select** ![](/files/VZT2CW5Ym1hLSF5a4FpT) **mouse tool** to select your region of interest (ROI) area where you want to fine-tune the segmentation. This will trigger the **Watershed Parameters** settings dialog to pop up.

3. In the pop-up **Watershed Parameters** settings dialog, modify key parameters to optimize segmentation for your ROI. Refer to [**Understanding Segmentation Parameters**](/stereomap-user-manual-v4.2/tutorials/navigation-for-image-processing/parameter-adjustable-semi-automatic-tool.md#understanding-segmentation-parameters) and [**Tips to Optimizing Segmentation Results**](/stereomap-user-manual-v4.2/tutorials/navigation-for-image-processing/parameter-adjustable-semi-automatic-tool.md#tips-to-optimizing-segmentation-results) for more information.

4. After adjusting the parameters, click **Apply** to implement the changes. Wait for the segmentation outcome to process and review the results.

5. If you are satisfied with the segmentation of most cells, you can further refine any misclassified cells using the [**drawing tools**](#manual-refinement-with-drawing-tools) (lasso, brush, or eraser). Alternatively, if you're satisfied with the segmentation, click **Next** to proceed to the final step. {% hint style="info" %} Be aware that the automated tool **only updates the segmentation within your selected region**, so cells at the edges of the selection box will have **rigid boundaries**. To avoid this issue, you can either select the entire tissue region to ensure smooth segmentation across the tissue, or **use the drawing tools** to fix any misclassified cells while maintaining the accuracy of the rest of the segmentation. {% endhint %} ### Manual Refinement with Drawing Tools For the highest level of precision, manually edit the segmentation using **Lasso**

, **Brush**

, and **Eraser**

tools to fine-tune individual cell boundaries. * **Lasso:** Best for deselecting large areas, such as the background. * **Brush & Eraser:** Ideal for refining smaller areas, such as marking cells, or separating cell clusters.

## Step 5: Export The final step is to export the results of image registration, tissue segmentation, and cell segmentation. Click **Export image processing record** to generate a `.tar.gz` file.

Click on the export will open your file system, and you will be allowed to select a saving path.

There are two types of export files: * **`*.tar.gz` File**: This file stores your original image along with all manual adjustments you made. It’s essential for SAW to combine sequencing data with image analysis. The internal structure of the `.tar.gz` is fixed, therefore to keep everything working smoothly, modifying it is not recommended. * **`*regist.tif` File**: If you manually adjusted the image alignment, this file will be saved in your output folder (or in the `/outs/` directory of SAW). The TIFF format makes it easy to use in third-party tools. This image has been cropped and resized to match the feature expression matrix dimensions, ensuring that any data generated from it using external tools can also be re-imported into StereoMap for further analysis.

## Pass the TAR.GZ to SAW Pipeline There are two options for transferring the output of Image Processing to SAW. 1. Using `--image-tar` in the `SAW count` Pipeline * This option is to use the `--image-tar` argument to feed the `.tar.gz` file into the `SAW count` pipeline * This will process the `.tar.gz` file along with the Stereo-seq FASTQ files. * The final output includes an HTML summary report with integrated sequencing and imaging data. ```bash cd /saw/runs saw count \ --id= \ --sn= \ --omics= \ --kit-version= \ --sequencing-type= \ --chip-mask=/path/to/chip/mask \ --organism= \ --tissue= \ --fastqs=/path/to/fastq/folders \ --reference=/path/to/reference/folder \ --image-tar=/path/to/image/tar ``` 2. Using `--realigned-image-tar` in the `SAW realign` Pipeline * This option is to use the `--realigned-image-tar` argument to input the `.tar.gz` file into the `SAW realign` pipeline * `SAW realign` skips CID mapping and genome alignment. * It re-generates aligned images and extracts the feature expression matrix at both tissue and cell level * The pipeline produces an updated HTML report with refined segmentation and spatial expression data. ```bash cd /saw/runs saw realign \ --id= \ --sn= \ --count-data=/path/to/previous/SAW/count/task/folder/id \ --realigned-image-tar=/path/to/realigned/image/tar ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://stereotoolss-organization.gitbook.io/stereomap-user-manual-v4.2/tutorials/navigation-for-image-processing/nuclei-staining-+-immunofluorescence-image.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.