# Mass Spectrometry Chromatogram Extraction

> Use when 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).

- Skill: `holobiomicslab/mass-spectrometry-chromatogram-extraction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-spectrometry-chromatogram-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-spectrometry-chromatogram-extraction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"