Overview

MSI Segmentation provides capabilities for automated exploration and unsupervised segmentation of 2D mass spectrometry imaging data. There are three processing pages. "Tissue Segmentation" allows for automated segmentation of pixels into clusters based on similar spectral characteristics. "Analyte clustering" allows for automated clustering of entire ion images to explore notable spatial patterns and colocalized ions. "Spectral correlation map" allows for interactive creation of images showing the correlation of all spectra to a given target spectrum. The app takes analyte .txt files from the MaldiChrom utility in HDI as input. Additionally,the app can read .rte files output from the 2D real-time viewer plugin to HDI, or a generic CSV format with columns representing (scan_number, x_pixel_location, y_pixel_location, mz_0, mz_1, ..., mz_N) for N m/z bins.

Try It! | Download Application | Release Notes | License Agreement

Changelog

• Version 2.1.1
  • Fixes bug that caused error loading certain types of analyte text files
• Version 2.1.0
  • Adds support for analyte files with IMS data
  • Reads TIC data from analyte files if present (HDI 1.7)
  • Exports TIC column to analyte file output
  • Fixes bug that broke the average spectrum visualization for any zero-intensity clusters
  • Mass annotation now accounts for the mass of an electron
  • Updated spectrum visualization figure
• Version 2.0.1
  • Fixes bug that caused the correlation image viewer to crash for square images
• Version 2.0.0
  • Major UI updates to group individual visualizations in tabs
  • Adds new "Spectral correlation map" feature to interactive explore relationships between pixels
  • Adds visualization of "tissue segmentation" results in the projected UMAP space to assess clustering quality
  • Adds method to save univariate thresholding mask as a .csv
  • Fixes visualizations for data with nonsquare pixel dimensions
  • Fixes bug that prevented the input of analyte data created in HDI with a target list
• Version 1.0.0
  • Initial release

Installation

MSI Segmentation is bundled with a Windows 10 installer. After downloading, be sure to uninstall any previous versions, then launch the installer by launching "Waters.MsiSegmentation.BundleInstaller.exe" [Note: do not launch "Waters.MsiSegmentation.Deployment.msi"]. After installation, the software will be installed as "Waters MSI Segmentation". This launches a window where the app service can be launched by pressing "Start". The app itself can then be accessed in a browser window at the local URL printed in the "Streamlit output" window. It should open a browser window to this address automatically, but in case it does not, you can manually copy and paste the address. To close, click "Stop" to stop the service, then close the app window.

Loading data

After the file-type extension is selected (.txt, .csv, or .rte), data are loading using the "Load data" form in the sidebar, using the "Browse files" button for local data, or selecting a sample file using the "Select example data" dropdown list. An uploaded local file will override a selected example file if both are selected. Once the data are loaded, metadata for the image dimensions, number of scans, pixel sizes, m/z range, and number of peaks are displayed below the "Load data" window in the sidebar. The app will also accept zip-compressed files provided there is only a single dataset within the zipped folder.

Tissue segmentation

Once the data are loaded, the app performs an initial classification of object vs. background and displays the results and additional tools in three tabs:

• The "Object mask" tab
  • This displays the average m/z image in grayscale with red pixels highlighting the object mask
  • Controls:
    • Object mask pad: Amount of pixels to expand (positive values) or contract (negative values) the initial object mask to avoid missing any object pixels. Default is 0.
    • Use mask: checkbox to use the object mask to speed up computation. If unchecked, the entire image will be clustered.
    • Invert: checkbox to invert the object mask in case the algorithm misidentifies object vs. background.
• The "Tissue classification" tab
  • This displays the current segmentation results with a colorbar identifying tissue ID labels. When the data are first loaded, these results will just show the filled-in object mask.
  • Tissue segmentation is performed by embedding the dataset in a lower dimensional subspace using UMAP, followed by density-based clustering using HDBSCAN. The app contains several forms that allow for user input into the parameters of the classification:
    • Minimum cluster size: fraction of object pixels that can form the minimum cluster size. Smaller values will yield a larger number of smaller, potentially noisier clusters, while large values will yield a smaller number of large, smooth clusters.
    • Advanced UMAP controls:
      • n_components, n_neighbors, min_dist, metric, random_state: Keyword arguments of the UMAP algorithm. For more information, see: UMAP documentation
      • Note, if random_state is set to 0 (default), the random_state argument is not passed to UMAP.
    • Advanced HDBSCAN controls
      • min_samples, cluster_selection_method: Keyword arguments of the HDBSCAN algorithm. For more information, see: HDBSCAN documentation
  • Pixel clustering results can also be visualized in the projected UMAP space to assess clustering quality
    • Note that if .rte data are loaded, the app uses simple k-means clustering of pixels instead of UMAP due to the lower dimensionality.
  • The "Analyte composition" window
    • This includes a selectbox to choose a tissue ID of interest and view an interactive plot of the average spectra within the corresponding pixels.
• The "Save results" tab
  • Save scan number, x, y, and pixel ID information in csv format
  • Save binary images of individual tissue masks in an analyte text file format to read into HDI

Tissue segmentation workflow

The UMAP step is the most expensive, while the masking and classification steps are relatively quick. All results including UMAP are cached by the app, but recalculation of the mask, as well as a change in any of the UMAP parameters will trigger a new embedding process. Accordingly, the app was designed with the following workflow:

• Load data
  • This triggers calculation and display of the object mask
• Update object mask controls as needed
• Update clustering controls as needed
• Click "Run classification"
• Adjust parameters as needed, remembering that any changes to the mask or UMAP controls will trigger another long UMAP process
• Choose ouput format and update the results filename if desired
• Click "Generate .xxx file" to create the output file
• Click "Download .xxx file" to download results

Analyte clustering

Under the "Analyte clustering" page, results and tools are displayed in 4 tabs:

• The "object mask" tab (same as in Tissue Segmentation)
• The "Cluster images" tab
  • This displays a grid figure of the average m/z image for each cluster
  • This also includes controls to display the m/z values and tentative annotations within each cluster, ranked by relative intensities
  • "Save clustering results" is similar to the Tissue Segmentation page. Note that here, the analyte text output will include the average cluster masks shown in the "Analyte clusters" window
  • Controls
    • Number of clusters: The app uses Ward's hierarchical clustering, which creates a hierarchy / tree-structure of potential clusters of varying sizes. This control effectively allows the user to specify the level to "cut" the tree structure; ie, how many clusters to report.
• The "Find similar ion images" window
  • This creates a dataframe of all ion images ranked by image correlation to a user-selected target image
• The "Univariate thresholding" window
  • This allows the user to select an average cluster image and create a binary mask by simple thresholding.
  • Controls:
    • "Choose a cluster to threshold": selects an average cluster image
    • "Choose intensity percentile": all pixels with intensities above this percentile will be included in the mask, and all values lower will be considered the background.

Spectral correlation map

This page creates a spatial map of Pearson's correlation values between the spectrum at each pixel and a fixed target pixel selected interactively by the user. The map will refresh when a new target pixel is clicked. This image can be used to create a binary mask by univariate thresholding, similar to the cluster images on the "Analyte clustering" page.

M/Z annotation controls

These controls in the sidebar are used to tune an algorithm that tentatively labels m/z images using some isotope-detection heuristics and the Human Metabolome Database). These results carry through to the rest of the interactive visualizations in the app.

• Mass accuracy (ppm): Sets the search window for isotope detection and analyte look-up
• Isotope image R^2 threshold: Candidate isotope images must have a correlation to the monisotopic image greater than this threshold
• Ion mode: Negative or positive

A note on app performance

• The most expensive step in the Tissue Segmentation app is the UMAP projection from the initial data space (~1000 dimensions per pixel) to a low-dimensional representation (2 dimensions per pixel by default). The actual clustering algorithm HDBSCAN is very cheap. The UMAP step is cached, so the user is free to explore different HDBSCAN parameters without needing to wait to recompute the UMAP projection. Note that the UMAP step will be recomputed any time the input data, mask setting, or UMAP settings are changed.
• The most expensive step in the Analyte Clustering app is the original linkage step (building the hierarchy/tree for Ward's hierarchical clustering). This step is also cached, so computation of new clusters at different levels is fast.