Eic data extraction from xcms

EIC Data Extraction from XCMS

Summary

Extract retention time, intensity, and peak characteristic data from XCMS-derived EIC and filled peak objects into a structured evalObj for downstream peak-quality metric computation. This skill bridges XCMS preprocessing output and quality assessment in untargeted LC-MS metabolomics workflows.

When to use

After running XCMS getEIC() to generate xcmsEIC objects and fillPeaks() to produce a filled xcmsSet object, before computing the 12 peak-quality metrics (Apex Max-Boundary Ratio, Elution Shift, FWHM2Base, Jaggedness, Modality, Symmetry, Sharpness, Gaussian Similarity, Retention-Time Consistency, TPASR, Zig-Zag Index, and related metrics) used to classify low-quality peaks in untargeted metabolomics data.

When NOT to use

• XCMS preprocessing has not yet been completed; getEIC() and fillPeaks() must have already been run.
• Input is raw MS data in mzML or netCDF format; this skill operates on post-XCMS objects, not raw instrument data.
• Peak-quality metrics have already been computed; getEvalObj is a prerequisite step, not a replacement for existing metric tables.

Inputs

• xcmsEIC object (from XCMS getEIC())
• filled xcmsSet object (from XCMS fillPeaks())
• optional EIC labels CSV with columns for EIC number and class label

Outputs

• evalObj with slots eicPts (list of retention time–intensity pairs per EIC), eicPeakData (peak characteristics: apex, start, end, intensity), and eicNos (EIC identifiers)

How to apply

Call the getEvalObj function on the xcmsEIC object (output from XCMS getEIC()) and the filled xcmsSet object (output from fillPeaks()) to extract and structure peak data. The function populates an evalObj with three key slots: eicPts (retention time and intensity vectors from each EIC), eicPeakData (peak characteristics such as apex position, start/end boundaries, and intensity), and eicNos (EIC identifiers). Optionally supply an EIC labels CSV to annotate peaks with class labels (e.g., metabolite identity or manual quality flags). The evalObj serves as the standardized input for getPeakQualityMetrics in the subsequent step, ensuring that all retention time, intensity, and boundary data are properly aligned and indexed by EIC number.

Related tools

• MetaClean (R package that provides getEvalObj function to extract and structure EIC data from XCMS objects) — https://github.com/KelseyChetnik/MetaClean
• XCMS (LC-MS preprocessing software that produces xcmsEIC and xcmsSet objects consumed by getEvalObj)
• R (Runtime environment for executing getEvalObj and downstream MetaClean functions)

Examples

evalObj <- getEvalObj(xcmsEIC = eic_object, xcmsSet = filled_set, eicLabels = label_df)

Evaluation signals

• evalObj contains three populated slots: eicPts (list of numeric vectors with length ≥ 1 per EIC), eicPeakData (data frame or list with columns for apex, start boundary, end boundary, and apex intensity), and eicNos (vector of unique EIC identifiers matching the number of rows in eicPeakData)
• All retention time values in eicPts are numeric and ordered monotonically within each EIC
• Peak characteristics in eicPeakData satisfy boundary constraints: start < apex < end for each peak
• If EIC labels are provided, the number of rows in the resulting labeled output equals the number of peaks, with no missing class assignments
• evalObj can be successfully passed to getPeakQualityMetrics without schema errors or missing data exceptions

Limitations

• Requires successful prior execution of XCMS getEIC() and fillPeaks(); missing or malformed xcmsEIC or xcmsSet objects will cause extraction failure.
• EIC label CSV, if supplied, must have matching EIC numbers; unmatched EICs will either be dropped or assigned missing values depending on join semantics (not fully specified in the article).
• Peak extraction assumes that XCMS peak-picking has already identified and characterized peaks; getEvalObj does not perform de novo peak detection.

Evidence

• [other] Call getEvalObj on the xcmsEIC and fill objects to extract retention time, intensity, and peak characteristic data into an evalObj with slots eicPts, eicPeakData, and eicNos.: "Call getEvalObj on the xcmsEIC and fill objects to extract retention time, intensity, and peak characteristic data into an evalObj with slots eicPts, eicPeakData, and eicNos."
• [methods] The function getEvalObj is called to extract the relevant data from the three objects provided by the user.: "The function getEvalObj is called to extract the relevant data from the three objects provided by the user"
• [other] Load the xcmsEIC object (from XCMS getEIC()) and filled xcmsSet object (from fillPeaks()) and optional EIC labels CSV.: "Load the xcmsEIC object (from XCMS getEIC()) and filled xcmsSet object (from fillPeaks()) and optional EIC labels CSV."
• [readme] can be easily incorporated into existing untargeted LC-MS metabolomics pipelines that utilize the pre-processing software XCMS: "can be easily incorporated into existing untargeted LC-MS metabolomics pipelines that utilize the pre-processing software XCMS"