218 lines
15 KiB
Markdown
218 lines
15 KiB
Markdown
# 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)
|