ST Spot Detector Usage Guide - SpatialTranscriptomicsResearch/st_spot_detector GitHub Wiki

A Guide to Using the Spatial Transcriptomics Spot Detector 2.0

This tool allows, through a smooth, neat and intuitive web interface, the detection and export of the spot coordinates of a ST Dataset for correct visualization of the data.

NOTE: A modern browser with HTML5 support is required. Latest versions of Chrome, Firefox and Safari should work. JavaScript must be enabled. Firefox is recommended.

NOTE: A mouse is preferred over a trackpad for better usability, but is not required.

Step One: Uploading Images

NOTE: This tool has been optimized to work on images taken directly from the ST protocol. The images must be rotated so that the frame cluster appears at the top left of the images. They may also be cropped, as long as the outer frame is intact. Images that have been scaled down up to 40% from the original may work but can not be guaranteed to provide results.

  1. Select the desired Cy3 fluorescent image to undergo spot detection.

  2. An HE bright field image may also be uploaded if tissue detection is desired. This step is optional.

  3. Click "Upload Image" (takes few minutes since all the computation and spot detection will be performed in the background. The ST Spot detector will show the operation being performed and the remaining time).

images/menu.png images/upload.png

Step Two: Image Alignment

NOTE: If a HE image was not uploaded and/or the images are previously aligned then this step may be skipped.

The idea in this step is to find reference points (spots in the HE image or tissue overlay in the Cy3 image) so to be able to align both images.

  1. Selected layer adjustment:

    1. Select which layer to adjust by clicking on the desired layer button (HE is chosen by default)
    2. Move the selected layer around with left-click.
    3. Pan around the images with right-click (or Ctrl+click). Use the scroll-wheel or the zoom buttons to zoom.
    4. Select the type of transformation to apply in "Tools" (Move or rotate).
    5. Adjustments will be layered and they can be disabled/enabled.
    6. Add adjustments (opacity, brightness, contrast, etc..) trough the Adjustments tool box so to be able to see the reference points better.

  2. Click on the spot adjustment tab button (tab and pen icon) when finished.

images/alignment.png

Step Three: Spot Adjustment

Here you can remove wrongly detected spots, add manually un-detected spots and change any spot assignation if the assignation is wrong or more than one spot is assigned to the same grid (array) position. The grid can be seen in white and you can switch between the HE and Cy3 images using the control on the bottom left. A spot that has a wrong assignation will have a red line.

images/adjustment.png

  1. The detected spots are initially shown in semi-transparent blue.

  2. Navigation:

    1. Move around the image with Ctrl + left-click. Use the scroll-wheel or the zoom buttons to zoom.
    2. Select spots with left-click. Multiple selections will be added automatically.
    3. Deselect spots with right-click or pressing the "Clear selection" button.
    4. Delete selected spots using the "Delete selected spots" button.
    5. Move/relocate spots with left or right click.

  3. If the HE image has been uploaded, then spots within the tissue boundaries can be automatically selected by clicking on the "Select spots within tissue" button.

  4. Missing spots may be added by clicking the "Add Spots" button and left-clicking where they should be placed. Return to the selection mode by clicking on the "Go back" button.

  5. Change spots assignation by using the "Edit assignments" button. Wrongly assigned spots will have a red line. Sometimes more than one spot is detected in the same position so they must be deleted and then add the correct spot manually. Sometimes a spot has a wrong assignation so its assignation can be changed in the Edit assignment menu by dragging and dropping to the correct position.

  6. Export the spot values:

    1. Click on the "Data export" tab.
    2. Choose whether to export all spots or only the current selection.
    3. Choose whether to include a flag indicating if the export is selected or not (under the tissue).
    4. Click "Export Spot Data" button.
    5. Click "Export Alignment Matrix" button.

    images/export.png

Output Data Formats

The exported data is available a tab-delimited file formatted as so (for the selected spots):

x   y   new_x   new_y   pixel_x pixel_y

x and y are the original spot coordinates new_x and new_y are numbers with positions relative to where they should be in the array. pixel_x and pixel_y are the pixel coordinates of the spot on the image.

Alternatively, if you chose to include the selection flag the format will be:

x   y   new_x   new_y   pixel_x pixel_y   selected_flag

selected_flag is not present if only the selection has been exported. In the case that all spots have been exported, the flag 1 if the spot has been selected; 0 otherwise.

For example:

For the spot in the array at (3, 4) its x coordinate is actually located 10% closer to the x coordinate 4, whereas its y coordinate is 5% closer to the y coordinate 3. On the image it is located at the pixel coordinates 510, 780.

3   4   3.1 3.95  510   780

It is also possible to export a file that contains a 3x3 affine transformation matrix that allows to convert array coordinates to pixel coordinates. This matrix is useful for plotting the data onto the HE image.

a11 a12 a13 a21 a22 a23 a31 32 a33

Each element correspond to a cell of the 3x3 affine matrix transformation to go from array coordinates to pixel coordinates

Final Step: Data conversion and visualization

The exported adjusted array coordinates of the selected spots (for instance under the tissue) can be used to adjust a ST Dataset generated with the ST Pipeline.

The script "adjust_matrix_coordinates.py" of the ST Pipeline package can be used to adjust the output of the ST Pipeline (matrix in TSV format) as follows:

adjust_matrix_coordinates.py --coordinates-file new_array_coordinates.txt --outfile new_stdata.tsv --counts-matrix stdata.tsv

This will generate a new matrix (new_stdata.tsv) that only contain the spots present in the output of the ST Spots detector (in array coordinates) and with the adjusted coordinates.

One can then use the 3x3 affine matrix file to plot the data onto the tissue image (HE) using the ST Viewer, the ST Analysis or your own scripts.