Targeted peak integration configuration

targeted-peak-integration-configuration

Summary

Configure and validate input parameters for targeted peak detection and integration in LC-MS data, including proper m/z window segregation, target list definition, and screening to ensure artifact-free extraction of ion chromatograms. This skill prevents sawtooth artefacts and ensures correct peak profiling by routing scan windows through accurate mass_range separation.

When to use

When performing targeted quantification of known compounds in LC-MS data using TARDIS, especially when the instrument acquired data with multiple overlapping m/z scan windows. Specifically: (1) you have centroided mzML files and a list of target compounds with known m/z, retention time, and polarity; (2) you need to avoid sawtooth artefacts in extracted ion chromatograms (EICs) caused by improper segregation of overlapping scan windows; (3) you want to screen target visibility before full peak detection across all runs.

When NOT to use

• Input files are already in non-centroided format (profile mode) without prior centroiding—TARDIS requires centroided mzML files
• Target list lacks m/z precision or retention time windows (TARDIS requires all four columns: ID, name, m/z, RT, polarity) to define mass_range and time windows
• Analysis goal is discovery or untargeted screening rather than quantification of predefined compounds

Inputs

• Centroided mzML files (LC-MS raw data)
• Spectra objects (MS data loaded as Bioconductor Spectra)
• Target list data.frame with columns: compound ID, compound name, m/z, retention time (minutes), polarity

Outputs

• Extracted ion chromatogram (EIC) plots with visual confirmation of artefact presence/absence
• Configuration validation report confirming scan-window routing correctness
• Peak detection results (area under curve, max intensity, SNR, peak_cor, points over peak) in subsequent tardisPeaks() execution

How to apply

First, prepare a target list as a data.frame with columns for compound ID, compound name, theoretical or measured m/z, expected retention time (in minutes), and polarity (positive/negative). Load centroided mzML files as Spectra objects using the xcms/Spectra framework. Execute tardisPeaks() in screening_mode = TRUE to verify that targets are visible within the defined m/z and RT windows; this step reveals whether mass_range parameters are correctly segregating overlapping scan windows. If EIC plots show sawtooth profiles during screening, adjust the mass_range argument to ensure each scan window is routed separately rather than merged. Once screening passes without artefacts, set screening_mode = FALSE and run peak detection across all samples. The key rationale is that TARDIS filters empty spectra internally; without proper mass_range separation, filtering creates artificial gaps in the EIC, producing the sawtooth profile. Verify clean chromatography by comparing EICs before and after correct mass_range routing.

Related tools

• TARDIS (Main R package for targeted peak integration and configuration; executes tardisPeaks() with mass_range routing and screening modes) — https://github.com/pablovgd/TARDIS
• xcms (Provides retention time correction algorithm used internally by TARDIS for chromatographic alignment)
• Spectra (Bioconductor package for MS data representation; TARDIS loads mzML files as Spectra objects for downstream processing)
• ProteoWizard / MSConvert (File conversion tool to prepare raw vendor formats as centroided mzML input)
• knitr / kableExtra (Used for rendering and displaying EIC plots and results tables in reports)

Examples

library(TARDIS); targets <- data.frame(ID=c('cmp1','cmp2'), Name=c('Compound1','Compound2'), mz=c(200.0523, 250.1234), RT=c(5.2, 7.8), polarity=c('pos','pos')); results <- tardisPeaks(files='data/sample.mzML', targets=targets, mass_range=list(c(199.5,200.5), c(249.5,250.5)), screening_mode=TRUE)

Evaluation signals

• EIC plots generated during screening_mode = TRUE show smooth, unimodal peak profiles without sawtooth artefacts
• Comparison of 'before' (incorrect mass_range) and 'after' (correct mass_range) EIC plots visually confirms removal of sawtooth structure
• All target compounds are detected in screening output (targets visible within m/z and RT windows as defined)
• Peak quality metrics (SNR, peak_cor, points over peak) are consistent and above expected thresholds after configuration validation
• Polarity filtering within TARDIS correctly segregates positive and negative mode targets without cross-contamination

Limitations

• Configuration correctness depends critically on accurate m/z and retention time values in the target list; incorrect window definitions will still produce artefacts or miss peaks
• Sawtooth artefacts arise specifically from filtering of empty spectra within TARDIS when overlapping scan windows are not properly segregated; this limitation is instrument-specific and may not apply to non-windowed or single-window acquisitions
• No changelog is available for TARDIS, limiting visibility into past configuration parameter changes or known issues that may affect specific use cases
• Centroiding is a strict requirement; profile-mode (non-centroided) mzML files will not be processed correctly and must be converted before configuration

Evidence

• [other] Peaks display a sawtooth profile when tardisPeaks() processes data with multiple overlapping m/z scan windows without mass_range separation: "Peaks display a sawtooth profile when tardisPeaks() processes data with multiple overlapping m/z scan windows without mass_range separation, due to filtering of empty spectra within TARDIS."
• [intro] Configuration requires target list data frame with compound ID, name, m/z, RT, and polarity columns: "compound ID, a unique identifier; A compound Name; Theoretical or measured m/z; Expected RT (in minutes); A column that indicates the polarity"
• [intro] Centroided mzML files are mandatory input format: "Input files need to be converted to the .mzML format and have to be centroided"
• [intro] Screening mode validates target visibility before full peak detection: "perform a screening step to check if our targets are visible within our m/z and RT windows"
• [intro] Spectra objects are the standard data representation for TARDIS integration: "loads MS data as Spectra objects so it's easily integrated with other tools"
• [results] EICs are visually inspected to confirm proper configuration: "The resulting EICs are again saved in the output folder and can be inspected"
• [intro] Polarity filtering is handled within TARDIS automatically: "Polarity filtering is done within TARDIS, so no polarity subsetting has to be performed"