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"
1---2name: eic-data-extraction-from-xcms3description: Use when 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.4license: CC-BY-4.05---67# EIC Data Extraction from XCMS89## Summary1011Extract 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.1213## When to use1415After 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.1617## When NOT to use1819- XCMS preprocessing has not yet been completed; getEIC() and fillPeaks() must have already been run.20- Input is raw MS data in mzML or netCDF format; this skill operates on post-XCMS objects, not raw instrument data.21- Peak-quality metrics have already been computed; getEvalObj is a prerequisite step, not a replacement for existing metric tables.2223## Inputs2425- xcmsEIC object (from XCMS getEIC())26- filled xcmsSet object (from XCMS fillPeaks())27- optional EIC labels CSV with columns for EIC number and class label2829## Outputs3031- evalObj with slots eicPts (list of retention time–intensity pairs per EIC), eicPeakData (peak characteristics: apex, start, end, intensity), and eicNos (EIC identifiers)3233## How to apply3435Call 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.3637## Related tools3839- **MetaClean** (R package that provides getEvalObj function to extract and structure EIC data from XCMS objects) — https://github.com/KelseyChetnik/MetaClean40- **XCMS** (LC-MS preprocessing software that produces xcmsEIC and xcmsSet objects consumed by getEvalObj)41- **R** (Runtime environment for executing getEvalObj and downstream MetaClean functions)4243## Examples4445```46evalObj <- getEvalObj(xcmsEIC = eic_object, xcmsSet = filled_set, eicLabels = label_df)47```4849## Evaluation signals5051- 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)52- All retention time values in eicPts are numeric and ordered monotonically within each EIC53- Peak characteristics in eicPeakData satisfy boundary constraints: start < apex < end for each peak54- If EIC labels are provided, the number of rows in the resulting labeled output equals the number of peaks, with no missing class assignments55- evalObj can be successfully passed to getPeakQualityMetrics without schema errors or missing data exceptions5657## Limitations5859- Requires successful prior execution of XCMS getEIC() and fillPeaks(); missing or malformed xcmsEIC or xcmsSet objects will cause extraction failure.60- 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).61- Peak extraction assumes that XCMS peak-picking has already identified and characterized peaks; getEvalObj does not perform de novo peak detection.6263## Evidence6465- [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."66- [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"67- [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."68- [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"
HolobiomicsLab 