Mass Spectrometry Chromatogram Extraction

mass-spectrometry-chromatogram-extraction

Summary

Extract ion chromatograms and mass spectrometry profile data from raw .mzML files as the foundational step for peak detection in LC-MS metabolomics workflows. This skill prepares unprocessed profile LC-MS data into segmented regions of interest (ROI) suitable for downstream machine-learning-based peak classification.

When to use

You have raw profile LC-MS data in .mzML format and need to prepare candidate peak regions for classification by a neural network detector (e.g., QuanFormer). Use this skill when your goal is to identify true peaks versus false peaks within user-defined m/z and retention time windows, or to discover peaks in an untargeted manner using centWave-derived ROI candidates.

When NOT to use

• Input is already a centroided (non-profile) feature table or a pre-processed peak list — use this skill only on raw profile LC-MS data.
• You need quantification results directly — this skill produces only ROI candidates; you must apply peak detection and boundary localization downstream.
• Your file format is not .mzML (e.g., raw vendor format, NetCDF, mzXML) — QuanFormer currently supports only .mzML.

Inputs

• Raw .mzML file (profile LC-MS data)
• Feature table (CSV with compound name, m/z, and retention time for targeted mode, optional)
• PPM tolerance value (integer, default 10)
• Peak width range parameters for untargeted mode (minWidth, maxWidth integers)
• Signal-to-noise and noise threshold parameters (integers, defaults s2n=5, noise=100)

Outputs

• Segmented ROI tensors (image-like 2D arrays: m/z × retention time intensity matrices)
• ROI metadata (m/z center, retention time center, width, height per ROI)
• Optionally: visualized ROI plots (PNG/image files if roi_plot=True)

How to apply

Parse the raw .mzML file using an mzML reader to extract the ion chromatogram and mass spectrometry profile data across the full m/z and retention time dimensions. Segment the profile data into candidate ROIs by either (1) targeted mode: extracting windows around known m/z and retention time coordinates with a PPM tolerance (default 10 ppm), or (2) untargeted mode: applying the centWave algorithm with user-specified peak width (minWidth, maxWidth), signal-to-noise ratio (s2n), noise threshold, and m/z difference parameters. Format each ROI as an image-like tensor with dimensions and data types compatible with CNN-Transformer input specifications (typically a 2D intensity matrix indexed by m/z and retention time bins). Verify tensor shape consistency and absence of NaN or out-of-range values before passing to the detection network.

Related tools

• QuanFormer (Main framework that ingests extracted ROI tensors and applies CNN-Transformer detection and boundary localization) — https://github.com/LinShuhaiLAB/QuanFormer
• mzML reader (Parses raw .mzML files to extract ion chromatogram and profile MS data)
• xcms (centWave algorithm) (Untargeted ROI detection via peak-finding in profile LC-MS data; requires R 4.4.2+ and Bioconductor) — https://www.bioconductor.org/packages/release/bioc/html/xcms.html

Examples

python main.py --ppm 10 --source resources/example/profile --feature resources/example/profile_feature.csv --images_path resources/example/profile_output --output resources/example/profile_output/area.csv --model resources/checkpoint0029.pth

Evaluation signals

• Tensor dimensions match CNN-Transformer input specification (verify shape consistency across all ROIs)
• No NaN, Inf, or out-of-range intensity values in output tensors; data type is float32 or compatible numeric type
• ROI bounding boxes do not exceed m/z and retention time bounds of the input raw file
• In targeted mode: all ROIs are centered within ±PPM tolerance of their respective feature m/z; retention time centers match provided coordinates
• In untargeted mode: ROI count and positions are reproducible across repeated runs; visual ROI plots (if generated) show coherent intensity peaks aligned with expected m/z and retention time

Limitations

• Currently supports only .mzML format; other vendor formats or NetCDF require prior conversion.
• PPM tolerance and peak width parameters are user-specified; incorrect settings may cause missed peaks or excessive false candidates.
• Untargeted mode requires R 4.4.2+, Bioconductor xcms 4.4.0+, and additional R dependencies; installation can be complex on some systems.
• Profile data with extreme baseline noise or very low signal-to-noise may produce ROIs that fail detection downstream; the skill does not validate SNR a priori.
• Large .mzML files (>2 GB) may consume substantial memory during chromatogram extraction and ROI segmentation.

Evidence

• [other] Parse raw .mzML file using mzML reader to extract ion chromatogram and mass spectrometry profile data.: "Parse raw .mzML file using mzML reader to extract ion chromatogram and mass spectrometry profile data."
• [other] Segment profile LC-MS data into candidate regions of interest (ROIs) containing potential peaks.: "Segment profile LC-MS data into candidate regions of interest (ROIs) containing potential peaks."
• [other] Format ROI data as image-like tensors compatible with CNN-Transformer input requirements.: "Format ROI data as image-like tensors compatible with CNN-Transformer input requirements."
• [other] Verify ROI tensor dimensions and data types match detection network specifications.: "Verify ROI tensor dimensions and data types match detection network specifications."
• [readme] Type of raw data files, currently only supports the mzML format.: "Type of raw data files, currently only supports the mzML format."
• [readme] PPM value for ROI extraction.: "PPM value for ROI extraction."
• [readme] train object detection network combining CNN and Transformer to identify the peaks in ROI (to judge whether it is a true peak or a false peak) and locate the peak boundaries: "train object detection network combining CNN and Transformer to identify the peaks in ROI (to judge whether it is a true peak or a false peak) and locate the peak boundaries"