Isotopologue quantification extraction

isotopologue-quantification-extraction

Summary

Automated extraction of isotopologue abundances, areas, and intensities from low- and high-resolution mass spectrometry data using the isoSCAN/autoQ pipeline. This skill quantifies labeled and unlabeled forms of target compounds in stable isotope labeling experiments by matching peak signatures against calculated isotope patterns.

When to use

Apply this skill when you have GC-CI-MS or LC-MS data in mzML format targeting a defined set of compounds with known monoisotopic mass, retention time, and chemical formula, and you need per-isotopologue (M+0, M+1, M+2, etc.) quantification metrics (area, maxo intensity, abundance). Use it when your research question requires distinguishing between isotopic forms of the same compound across multiple samples or conditions.

When NOT to use

• Input mzML files are in centroided format for low-resolution data (profile format is essential for accurate peak quantification)
• Raw data has not been converted to mzML format or formulaTable is missing required columns (CompoundName, mz, RT, Formula, NumAtoms)
• Compounds have overlapping retention times or m/z values that exceed the specified mass error tolerance (mzerror/maxppm), preventing reliable isotopologue discrimination

Inputs

• formulaTable data frame (columns: CompoundName, mz, RT, Formula, NumAtoms)
• mzML files in profile format (low-resolution) or centroided format (high-resolution)
• enviPat isotopes object (for isotope pattern calculation)
• autoQ function parameters (minscans, SNR, mzerror/maxppm, RTwin, maxwidth, minwidth, labelatom)

Outputs

• Quantification table with columns: CompoundName, m.z, isotopologue designation (M+0, M+1, M+2), abundance, ppm mass error, area, maxo (maximum intensity) per sample
• Quality control plots (rawPlot, meanRawPlot) flagging peak shape anomalies

How to apply

First, prepare a formulaTable data frame with columns CompoundName, mz (monoisotopic ion), RT (retention time in seconds), Formula (derivatized formula for high-resolution), and NumAtoms, loaded via read.csv. Convert raw MS data to mzML format using Proteowizard MSconvert, preserving profile format for low-resolution data or applying centroiding for high-resolution (Orbitrap) data. Call the autoQ function with the formulaTable and mzML files, specifying parameters: minscans (minimum scans per peak, typically 6), SNR (signal-to-noise threshold, typically 3), mzerror or maxppm (mass error tolerance, e.g., 0.1 Da or 5 ppm), RTwin (retention time window in seconds, typically 5), and maxwidth/minwidth (peak width bounds in scans). For labeled experiments, specify labelatom='13C'. Extract the resulting table containing per-compound isotopologue designations (M+0, M+1, M+2) with paired area and maxo values, ppm mass error, and abundance metrics. Validate results using rawPlot and meanRawPlot for quality control to identify moving peaks, noise, or saturation artifacts.

Related tools

• isoSCAN (Primary R package providing the autoQ function for automated isotopologue extraction and quantification from mzML files) — https://github.com/jcapelladesto/isoSCAN
• mzR (R package used by isoSCAN to parse and read mzML/mzXML mass spectrometry files)
• Proteowizard MSconvert (Converts vendor-format raw MS data into mzML format with user-selectable profile or centroided output)
• enviPat (R package that calculates isotope patterns for high-resolution mass spectrometry to enable isotopologue identification)

Examples

library(isoSCAN); formulaTable <- read.csv('targets.csv'); autoQ(formulaTable, mzMLfiles=c('sample1.mzML','sample2.mzML'), minscans=6, SNR=3, mzerror=0.1, RTwin=5, maxwidth=4, minwidth=1, labelatom='13C')

Evaluation signals

• autoQ output table contains all target compounds from formulaTable with isotopologue designations (M+0, M+1, M+2) and non-null area and maxo values (when peak shape permits)
• Returned ppm mass error values are within specified mzerror/maxppm tolerance for each isotopologue peak
• Ratio of M+1 to M+0 abundance (or M+2/M+0 for doubly labeled compounds) matches theoretical labeling fraction within ±5% when validated against synthetic mixtures or known standards
• rawPlot and meanRawPlot quality control plots show stable, smooth peak profiles without drift, noise spikes, or saturation artifacts across replicate samples
• Area and maxo values increase monotonically with compound concentration in a dose-response experiment (R² > 0.98 for standard curves)

Limitations

• Profile format is essential for low-resolution data; centroided files will yield inaccurate or missing quantification
• High-resolution data requires derivatized formula in formulaTable; mismatch with actual derivatization will cause isotopologue pattern misalignment and peak misidentification
• Peak quantification fails or returns only maxo (not area) when peak shape is severely distorted, overlapped, or saturated; manual review via rawPlot is required
• Retention time window (RTwin) and mass error tolerance (mzerror/maxppm) must be tuned per instrument and chromatography method; inappropriate settings cause false positives or missed isotopologues
• No changelog or versioning information provided; compatibility with R version, mzR, and enviPat version updates is undocumented

Evidence

• [intro] isoSCAN primary design goal: "The package is designed to automatically extract the abundances of isotopologues of a targeted list of compounds."
• [intro] Low-resolution format requirement: "In the case of Low-resolution. Transform the data mantaining profile format. This is essential for peak quantification."
• [intro] High-resolution format requirement: "In the case of High-resolution, please use centroiding (e.g. peakPicking= True in MSconvert)"
• [intro] formulaTable required columns: "formulaTable must contain the following column names in no specific order: * CompoundName * mz * RT * Formula * NumAtoms"
• [intro] autoQ parameter specification: "This parameters refer to peak width and number of scans recorded, together with signal-to-noise ratio and mass error."
• [intro] Workflow: load compounds and process files: "Before starting with file processing, we need to load the targeted compounds as a formulaTable data frame. This can be done either with read.table or read.csv functions."
• [intro] Workflow: call autoQ function: "Now we can call autoQ function that will process the files and look for the isotopologues for each compound found in the formulaTable."
• [intro] Quality control functions: "rawPlot and meanRawPlot functions should be used for quality control purposes. They are useful to check for moving peaks, noisy spots or saturated peaks."
• [other] Low-resolution Quadrupole autoQ output: "autoQ processing of low-resolution Quadrupole data with parameters minscans=6, SNR=3, mzerror=0.1, RTwin=5, maxwidth=4, minwidth=1 yields both area and maxo values for isotopologues"
• [other] High-resolution Orbitrap autoQ output: "The autoQ function returns for high-resolution Orbitrap data a table with columns for CompoundName, m.z, abundance, Isotopologue designation (M+0, M+1, M+2), ppm mass error, and paired maxo and area"