Skip to content

JuliaMSI_MainGuide.md

Latest commit

 

History

History
217 lines (155 loc) · 15.4 KB

JuliaMSI_MainGuide.md

File metadata and controls

217 lines (155 loc) · 15.4 KB

JuliaMSI Platform User Guide

Core Workflow and Interactive Analysis

Table of Contents

  1. Introduction
  2. Loading a Dataset
  3. Converting mzML to imzML
  4. Batch Processing
  5. Spectral Visualization
  6. Imaging Slice Generation
  7. Topography and Surface Plots
  8. Small Features and Tools
  9. Mask Generation and Usage (mask.jl)
  10. Preprocessing
  11. Practical Tips for Analysts
  12. Troubleshooting Common Issues
  13. Citation and Contact

Introduction

This document serves as an entry point for analysts using the JuliaMSI platform. It focuses on the user-facing modules: app.jl (the main application entry), julia_imzml_visual.jl (visualization and heavy procedures), and mask.jl (mask generation and filtering). The goal is to explain why each step requires specific inputs and what those inputs mean scientifically.

JuliaMSI is a user-friendly Graphical User Interface (GUI) developed in Julia for MSI data analyses. Our framework allows for rapid imzML MSI data analysis and mzML spectra plot loading, significantly improving analytical workflows. High-resolution instruments produce massive datasets, requiring efficient memory management and parallel processing—reasons why JuliaMSI is written in Julia, which offers high performance.

Core Objectives:

  • Simplification: Reducing command-line dependency through intuitive visualizations and easy parameter input.
  • Accessibility: Breaking the proprietary software barrier across fields like plant sciences, biomedical research, and environmental studies.
  • Interactive Exploration: Using the Plotly.jl package for dynamic visualizations. Users can explore multiple interpretations of images, select specific coordinates for spectra analysis, or pick an m/z value directly from the displayed spectrum.

Key Capabilities:

  • Smart data handling: Processes large files in manageable sections without overwhelming memory.
  • Batch processing: Analyzes multiple samples simultaneously for high-throughput studies.
  • Interactive exploration: Web interface enables real-time data visualization and analysis.

Loading a Dataset

Action: Click the Search button (@onbutton btnSearch)

Load an imzML or mzML file into the workspace, extract metadata, and prepare the dataset for visualization and processing.

The platform checks whether a pre-processed version of the same file exists in the registry (fast load). If not, it performs a full load using OpenMSIData. The GUI handles multiple file uploads for MSI slice generation; however, for spectra and preprocessing, it will only use the last selected file.

Converting mzML to imzML

Action: Click Convert/Process (@onbutton convert_process)

This tool converts an mzML file (from a non-imaging mass spectrometry run) into an imzML file suitable for imaging analysis. This is necessary when spectra were acquired in a raster pattern but saved as a continuous mzML file without spatial coordinates.

Inputs Required:

  • mzML file: The raw mass spectrometry data file.
  • Sync file: A text file that maps each spectrum in the mzML to a specific pixel coordinate (x, y). The sync file typically contains one line per spectrum with the format x y or similar.

Why these inputs?: mzML files lack spatial metadata; they contain a list of spectra in acquisition order. Without coordinate information, the data cannot be reconstructed as an image. Sync files provide the missing spatial mapping, often generated by instrument software from a motor stage log. The conversion process embeds these coordinates into the imzML structure.

Batch Processing

Action: Click Main Process (@onbutton mainProcess)

This is the core image generation routine. It takes a list of comma-separated m/z values and produces ion images (and optionally TrIQ Quantized images) for each file loaded.

Required Inputs:

  • m/z values: A comma-separated list of m/z values to visualize spatial distribution. These are the core of MSI: each image maps the abundance of a particular ion across the sample. Without a target, there is no image.
  • Tolerance: The mass window around each target ion. Necessary because no mass spectrometer measures masses with infinite precision. The signal from a given ion is spread over a small m/z range; integrating over that range (by summing intensities of all data points within ±tolerance) captures the true signal.
  • Color level: Number of discrete color levels in the output BMP image. A low number (e.g., 16) gives a coarse view; a high number (256) shows subtle intensity variations but can be noisy.
  • TrIQ: A toggle to enable Threshold Intensity Quantization. This produces images with enhanced contrast and reduced influence of extreme outliers, making spatial patterns more visible. It is a contrast normalization and quantization technique.
  • TrIQ Threshold: Probability threshold for outlier removal in TrIQ.
  • Median filter: Replaces each pixel’s intensity with the median of its neighbors, effectively removing isolated "hot pixels" while preserving sharp boundaries.
  • Mask: Toggle to focus on biologically relevant regions (e.g., tissue vs. background), avoiding wasted computational resources on irrelevant pixels.

Note: The mask path is determined inside the JSON file, which can be manually altered, or using the specific section in mask.jl.

Imaging Slice Generation (Part of Main Process)

In MSI, each pixel contains a full mass spectrum. To create an ion image (or "slice"), we must decide which data points in that spectrum belong to the ion of interest.

  • Tolerance: Defines the m/z window. Too narrow may miss part of the peak; too wide includes noise or interfering peaks. Optimal tolerance depends on instrument resolving power and calibration stability.
  • Colorbar Generation: Each image is accompanied by a colorbar PNG showing the mapping between intensity and colors. The bounds are determined during quantization (TrIQ or min-max scaling) and passed to generate_colorbar_image. This ensures consistent color interpretation with labels indicating the intensity range and scaling factors (e.g., "Intensity ×10³").

Spectral Visualization

Functions: createMeanPlot, createSumPlot, createXYPlot, createNSpectrumPlot

Displays spectra from the loaded dataset, optionally filtered by a mask. This generates a Plotly layout plot for quality control, identification, and m/z selection.

Inputs & Features:

  • Dataset: The last imzML / mzML file loaded in the GUI.
  • Mask: Toggle for mask filtering. The spectrum is computed only from pixels inside the mask.
  • User click: If a user clicks on an already generated slice (2D image), two vertical lines appear and values are filled (one for x-axis, one for y-axis) to generate spectrum plot indicating the position of the click in the image. This allows the creation of a spectrum plot correlating to specific spatial selection.
  • NSpectrumPlot: Allows the user to select specific spectra based on the ID (the index of the spectra in the dataset).

Spectral Types:

  • Mean spectrum: The average of all pixel spectra. Gives an overview of ions present in the entire sample and their relative abundances. Used to identify peaks for further imaging.
  • Sum spectrum: Total ion current summed across all pixels. Emphasizes ions that are abundant across many pixels.
  • Per-pixel spectra (XY and N): Reveal the distribution of ions in a specific location, useful for comparing tissue regions (e.g., tumor vs. normal).

Why these inputs?: Spectra are the raw data of MSI. Visualizing them is the first step: checking for unexpected peaks, assessing signal-to-noise ratio, and verifying mass calibration. Applying a mask (e.g., only tumor region) allows researchers to extract region-specific molecular signatures.

Topography and Surface Plots

Functions: image3dPlot, imageCPlot, triq3dPlot, triqCPlot

Convert a 2D ion image into a 3D surface plot where the height (z-axis) represents ion intensity.

  • Inputs: Current ion image and optional Mask.
  • Why these inputs?: 3D surfaces and 2D Contour plots make intensity variations more tangible, especially for features with large dynamic range. They are useful for understanding the topography of ion distributions (e.g., a lipid enriched in a specific tissue layer). The 3D plot is interactive, allowing for rotation and zoom.

Small Features and Tools

Metadata Viewing (showMetadataBtn)

Display a summary of the dataset’s metadata: instrument settings, acquisition parameters, image dimensions, number of pixels, m/z range, etc.

Optical Image Overlay (btnOptical)

Overlay a histological or photographic image onto the MSI image to correlate molecular distributions with tissue anatomy.

  • Inputs: Current ion image, Transparency slider (imgTrans), and Optical image file (PNG, BMP, JPG, JPEG).
  • Output: The main image tab updates to show the MSI image (or TrIQ image) blended with the optical background.

Comparison of Datasets

Functionality to compare two datasets (e.g., control vs. treated). This involves side-by-side visualization or ratio image generation to highlight differences in molecular abundance. It allows visualization of slices with or without TrIQ filtering.

Registry and Safe Processing

Batch processing is orchestrated by process_file_safely. The registry (registry.json) stores critical info: source path, image dimensions, summary statistics, and mask path. This file can be edited manually following its generated structure.

Mask Generation and Usage (mask.jl)

Create binary masks that define Regions of Interest (ROI) in the sample. Masks filter spectra, preprocessing, and images to include only pixels inside the ROI.

User-Defined Inputs:

  • Drawing tools: Draw freehand shapes on the ion image or optical overlay.
  • Otsu Scale: Automatically generates a mask based on the Otsu thresholding algorithm with the slider percentage.
  • Noise Size: Removes noise from the mask based on the slider percentage.
  • Hole Size: Removes holes in the mask based on the slider percentage.
  • Smoothing: Smooths the mask based on the slider percentage.
  • Thresholding: Set intensity thresholds to automatically segment regions.
  • Import: Load a pre-existing mask image (e.g., from a segmentation tool).

Outputs:

  • A binary mask matrix (same dimensions as the MSI image) saved in the public/css/masks folder as a .png file with the name of the dataset.
  • The mask is registered in the dataset’s metadata entry for automatic application in subsequent analyses.

Why these inputs?: Often only a portion of the imaged area contains tissue; the rest could be background. Masking removes background pixels, improving statistical power and avoiding artifacts. Manual delineation based on optical images is standard practice in histology-directed MSI. It can also work for a selection of an area of interest (e.g. only the tumor region) in samples with multiple areas of interest.

Preprocessing

To understand the deep structure of the preprocessing pipeline, please refer to the dedicated guide: JuliaMSI Preprocessing Guide

This document describes the rationale, methods (TIC/PQN, SNIP, Wavelets), and implementation choices in detail.

Practical Tips for Analysts

Julia Version Compatibility

  • The platform is tested and compatible with Julia 1.11.
  • Recommendation: Use Julia 1.11 to ensure all dependencies work correctly. Use Juliaup to manage multiple versions easily. Downgrading your system Julia is unnecessary; you can keep multiple versions and launch the platform with the specific executable path.

First-Time Startup

  • The script will detect a missing Manifest.toml and automatically instantiate packages. This may take a few minutes. Subsequent startups will be much faster.
  • Caution: Do not close the terminal/console while the server is running; it hosts the web interface.

Accessing the Web Interface

  • The platform opens your browser to http://127.0.0.1:1481.
  • If port 1481 is in use, change this segment in the startup script: up(host="127.0.0.1", port=1481).

Memory Management

  • MSI datasets can be large (gigabytes). JuliaMSI includes automatic garbage collection and, on Linux, calls malloc_trim to return freed memory to the OS.
  • OOM Troubleshooting: Process fewer m/z values at once, use a mask to exclude background, or increase system swap space.

Registry and File Locations

  • registry.json stores paths to your datasets. If you move original imzML files, update the paths in the JSON or delete the registry file to let the platform rebuild it.
  • Processed images and colorbars are saved in the public/ folder, organized by dataset name.

Mask Handling

  • Ensure manually created masks have the exact same dimensions (width × height) as the MSI image.
  • Masks are automatically applied during batch processing if the "Mask" toggle is enabled. If you move the mask file, you must update its path in the registry.

Troubleshooting Common Issues

  • "Error loading active file": Check that the file is a valid imzML or mzML and that the corresponding .ibd file is in the same directory.
  • Images appear all black: This can happen if the tolerance is too narrow (no signal captured) or if the mask is incorrectly applied. Verify m/z and tolerance.
  • Slow performance: Reduce the number of m/z values or disable the median filter. Ensure you have enough RAM.
  • Browser interface not responding: Refresh the page. Check the console for errors; you may need to restart the Julia process.

Citation and Contact

Any revision to the code, bug, or error should be reported to: julian.sierrag@icloud.com

Note: This guide is based on collective knowledge of these algorithms; please perform your own research and cite properly. To cite the JuliaMSI platform, please use:

José Julián Sierra-Álvarez, Martín Orlando Camargo-Escalante, Carlos Daniel Sierra-Álvarez, Carmelo Hernández-Caricio, Juan Francisco Moreno-Luna, Isabel Buendía-Corona, Robert Winkler, JuliaMSI: A high-performance graphical platform for mass spectrometry imaging data analysis, Analytica Chimica Acta, Volume 1377, 2025, 344613, ISSN 0003-2670, https://doi.org/10.1016/j.aca.2025.344613