# JuliaMSI Platform User Guide ## Core Workflow and Interactive Analysis --- ### Table of Contents 1. [Introduction](#introduction) 2. [Loading a Dataset](#loading-a-dataset) 3. [Converting mzML to imzML](#converting-mzml-to-imzml) 4. [Batch Processing](#batch-processing) 5. [Spectral Visualization](#spectral-visualization) 6. [Imaging Slice Generation](#imaging-slice-generation) 7. [Topography and Surface Plots](#topography-and-surface-plots) 8. [Small Features and Tools](#small-features-and-tools) * [Metadata Viewing](#metadata-viewing) * [Optical Image Overlay](#optical-image-overlay) * [Comparison of Datasets](#comparison-of-datasets) * [Registry and Safe Processing](#registry-and-safe-processing) 9. [Mask Generation and Usage (mask.jl)](#mask-generation-and-usage-maskjl) 10. [Preprocessing](#preprocessing) 11. [Practical Tips for Analysts](#practical-tips-for-analysts) * [Julia Version Compatibility](#julia-version-compatibility) * [First-Time Startup](#first-time-startup) * [Accessing the Web Interface](#accessing-the-web-interface) * [Memory Management](#memory-management) * [Registry and File Locations](#registry-and-file-locations) * [Mask Handling](#mask-handling) 12. [Troubleshooting Common Issues](#troubleshooting-common-issues) 13. [Citation and Contact](#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](JuliaMSI_Preprocessing.md)** 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](https://doi.org/10.1016/j.aca.2025.344613)