[OLD] ST Spot Detector Usage Guide (OLD version) - SpatialTranscriptomicsResearch/st_spot_detector GitHub Wiki

A Guide to Using the Spatial Transcriptomics Spot Detector

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.

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 a minute or two).

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.

  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. Adjust opacity, brightness, contrast using the sliders or tick the checkbox to apply an equalize filter (may help to see the spots).

  2. Click on the spot detection tab button (eye icon) when finished.

Step Three: Spot Detection

  1. Drag the lines to onto the outer "frame" of the spots, making sure that the lines intersect through approximately the middle of the spots.

    NOTE: Move around the image with right-click (or Ctrl+click). Use the scroll-wheel or the zoom buttons to zoom.

  2. Click "Detect Spots" (takes approximately 15 seconds).

Step Four: Spot Adjustment

  1. The detected spots are initially shown in semi-transparent red. The color and opacity may be adjusted to your preference.

  2. Navigation:

    1. Move around the image with right-click (or Ctrl+click). Use the scroll-wheel or the zoom buttons to zoom.
    2. Select spots with left-click. Add to the current selection by holding in shift and selecting additional spots.
    3. Move selected spots with right click (or Ctrl+click).
    4. Delete selected spots using the "Delete selected spots" button.

  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 (takes a minute or two).

  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 "Finish adding spots" button.

  5. Export the spot values:

    1. Click on the export tab.
    2. Choose whether to export all spots or only the current selection.
    3. Choose whether the coordinates should be in pixel coordinates relative to the HE image, or relative array coordinates.
    4. Click "Export Spot Data".

Step Five: 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, you can export all the spots (whether they are selected or not) so then 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.