HolobiomicsLab MS annotation result validation
Summary
Verify and inspect ranked candidate metabolite annotations from LC–MS All-ion fragmentation data by extracting top-ranked hits, confirming match quality metrics (annotation score, matched ion count), and visualizing experimental spectra against candidate fragmentation patterns. This ensures annotation reliability before downstream interpretation.
When to use
After running annotateRC on LC–MS AIF features with fragment libraries (e.g., LipidPos), use this skill to confirm that rank-1 candidates have acceptable annotation scores and sufficient matched ion support, and to resolve ambiguous or low-confidence assignments by inspecting spectral overlays.
When NOT to use
- Input feature table has not yet been processed with annotateRC or another annotation engine — first run annotation before validation.
- Annotations are from targeted methods (e.g., MRM, SRM) where only a single candidate per feature is expected and no ranking is performed.
- Raw LC–MS data has not been processed through xcms and RamClustR; AIF chromatograms must be in centroid mode and clustered before annotation.
Inputs
- annotations object with rankedResult data from annotateRC
- xcmsSet object (xset) containing LC–MS AIF chromatograms
- RamClustR RC object
- targetTable.csv feature table with m/z, retention time, and feature identifiers
Outputs
- rank-1 candidate annotation record (name, score, matched ion count per feature)
- summary annotation report listing all rank-1 hits
- spectral overlay plots (experimental vs. candidate) for validated features
- validated annotation table with confidence metadata
How to apply
Extract the rankedResult object from the annotations output produced by annotateRC. For each feature of interest, retrieve the rank-1 candidate annotation along with its annotation score and matched ion count. Cross-reference the m/z and retention time from the target feature table to ensure correct feature identification. Use plotResultSpec to overlay the experimental spectrum with the candidate's theoretical fragmentation pattern and visually confirm ion matching. Generate a summary report listing candidate name, score, and supporting evidence; features with low matched ion counts or ambiguous spectral overlays warrant inspection of lower-ranked candidates or manual curation. The decision to accept or reject an annotation should account for the number of matched ions relative to the total ions in the experimental spectrum.
Related tools
- MetaboAnnotatoR (Produces ranked candidate annotations and rankedResult object; enables spectral visualization with plotResultSpec function) — https://github.com/gggraca/MetaboAnnotatoR
- xcms (Preprocesses and aligns LC–MS AIF chromatograms into feature tables required as input for annotation)
- RamClustR (Clusters co-eluting ions and groups them into spectral features before annotation)
- R (version 4.5.0 or higher) (Runtime environment for executing annotateRC and validation workflows)
Examples
annotations <- annotateRC(xset, RC, targetTable, DB='LipidPos'); topHit <- annotations$rankedResult[[1]]$rank1; plotResultSpec(annotations, feature=1, rank=1)
Evaluation signals
- Rank-1 candidate m/z and retention time match the target feature coordinates within instrument tolerance
- Annotation score and matched ion count are above acceptable thresholds (thresholds must be set by analyst based on application; evidence of acceptance should be documented)
- Spectral overlay plot shows clear correspondence between experimental fragment peaks and candidate theoretical fragmentation pattern
- Three or more matched ions are present in the experimental spectrum; low-confidence hits (few matched ions) are flagged for manual review
- Summary report can be generated without errors and all features have a rank-1 annotation or explicit null/ambiguous flag
Limitations
- Annotation quality depends on completeness and accuracy of the fragment library (LipidPos or other); sparse or incorrect library entries will produce false or low-confidence hits.
- MetaboAnnotatoR requires raw LC–MS AIF chromatograms in centroid mode; profile mode data or data from other acquisition methods are not supported.
- In some R environments, installation of MetaboAnnotatoR may fail due to Rcpp version conflicts or i386 architecture issues (documented workarounds exist in README).
- Overlapping m/z or retention time across features may lead to ambiguous spectral assignments; additional separation or manual curation may be required.
- Rank-1 annotation may not always be the correct annotation; visual inspection and domain knowledge are essential for final validation.
Evidence
- [intro] MetaboAnnotatoR is designed to perform metabolite annotation of features from LC-MS All-ion fragmentation (AIF) datasets, using ion fragment databases: "MetaboAnnotatoR is designed to perform metabolite annotation of features from LC-MS All-ion fragmentation (AIF) datasets, using ion fragment databases"
- [intro] This information can be accessed from the rankedResult object stored in the annotations: "This information can be accessed from the rankedResult object stored in the annotations"
- [intro] It is possible to visualise the spectra containing the matched ions to each candidate: "It is possible to visualise the spectra containing the matched ions to each candidate"
- [intro] Three out of the six features were annotated with to a lipid: "Three out of the six features were annotated with to a lipid"
- [readme] It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode.: "It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode."