---
name: pseudo-ms-ms-spectra-ranking-and-curation
description: Use when after executing annotateRC to match six or more lipidomics/metabolomics features against ion fragment databases (e.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3632
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0157
  tools:
  - MetaboAnnotatoR
  - R
  - RamClustR
  - xcms
derived_from:
- doi: 10.1021/acs.analchem.1c03032
  title: metaboannotator
evidence_spans:
- MetaboAnnotatoR is designed to perform metabolite annotation of features from LC-MS All-ion fragmentation (AIF) datasets
- To install this package, start R (version "4.5.0" or higher)
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_metaboannotator
    doi: 10.1021/acs.analchem.1c03032
    title: metaboannotator
  dedup_kept_from: coll_metaboannotator
schema_version: 0.2.0
---

# Pseudo-MS/MS Spectra Ranking and Curation

## Summary

This skill ranks and curates candidate metabolite annotations from pseudo-MS/MS spectra generated by RAMClustR, matching fragment ions against lipid or metabolite databases to identify and prioritize the most confident assignments. It is essential for converting raw feature-to-candidate mappings into ranked, interpretable annotation results for untargeted LC-MS All-ion fragmentation lipidomics and metabolomics data.

## When to use

Apply this skill after executing annotateRC to match six or more lipidomics/metabolomics features against ion fragment databases (e.g., LipidPos), when you have pseudo-MS/MS spectra from RAMClustR objects and need to identify which of multiple candidate annotations best explain each feature's fragmentation pattern. Use it specifically when you expect only a fraction of features (e.g., 3 out of 6) to receive high-confidence lipid or metabolite annotations and require ranked candidates for manual or automated validation.

## When NOT to use

- Input data are already manually validated, peer-reviewed annotations; ranking adds no additional confidence.
- Feature table lacks corresponding pseudo-MS/MS spectra (e.g., only precursor masses without fragmentation data).
- Ion fragment database is incomplete, outdated, or not suitable for the lipid or metabolite class of interest (e.g., using general MassBank for specialized lipidomes without dedicated LipidPos coverage).

## Inputs

- RAMClustR object containing pseudo-MS/MS spectra
- xcmsSet object containing peak-picked LC-MS feature data
- Feature table (e.g., targetTable.csv) with m/z, retention time, and feature identifiers
- Ion fragment database library (e.g., LipidPos, MassBank-formatted .msp)
- Annotated candidate list from annotateRC function (matching scores per feature)

## Outputs

- Ranked candidate annotations table (feature ID, candidate metabolite, rank, matching score, adduct type)
- Annotation report with confidence assessment per feature
- Visualization of matched fragment ions overlaid on pseudo-MS/MS spectra
- Curated annotation results saved to user-specified directory

## How to apply

Load the annotateRC output containing matched fragment scores for candidate metabolites against each feature's pseudo-MS/MS spectrum. Rank candidates by matching score (typically correlation or spectral similarity) for each feature and filter to candidates meeting a specified threshold or keeping only the top-ranked assignment. Verify that assignments match biologically plausible ion adducts and fragmentation patterns—for example, confirming that LPC(14:0) appears as rank-1 candidate for a 468.3095 m/z feature aligns with expected [M+H]+ mass and lysophosphatidylcholine fragmentation. Visual inspection of matched ion positions in the spectrum against the candidate's theoretical fragments strengthens confidence. Document the matching score, rank position, and reasoning for each retained annotation, and save results to user-specified output directory for downstream validation.

## Related tools

- **MetaboAnnotatoR** (R package that executes annotateRC function to match fragment ions and produce candidate rankings; used to load libraries and curate results) — https://github.com/gggraca/MetaboAnnotatoR
- **RamClustR** (Generates pseudo-MS/MS spectra from AIF data that serve as input for ranking; integrated with xcms for feature processing)
- **xcms** (Produces peak-picked feature data and xcmsSet object required alongside RAMClustR spectra for annotation ranking)
- **R** (Runtime environment for executing ranking, filtering, and visualization code; version 4.5.0 or higher required)

## Examples

```
annotateRC(RC = RC, xset = xset, targetTable = targetTable, ionLibrary = "LipidPos") → inspect(annotated_results$rank1_candidates) → visualize_spectra(feature_id = 3, candidate = "LPC(14:0)", spectrum_plot = TRUE) → save_annotations(annotated_results, output_dir = "./annotations/")
```

## Evaluation signals

- Three out of six features (or expected proportion) receive metabolite annotations with unambiguous rank-1 candidates and matching scores above threshold
- Rank-1 annotation m/z and adduct assignment (e.g., LPC(14:0) [M+H]+ = 468.3095) fall within expected mass tolerance (typically <5 ppm) and match known fragmentation rules for the lipid class
- Visual inspection of pseudo-MS/MS spectrum shows matched fragment ions (marked in output visualization) clustered at expected m/z positions corresponding to the rank-1 candidate's theoretical fragments
- Annotations are reproducible: re-running annotateRC with the same feature table, xcmsSet, RAMClustR object, and library parameters produces identical ranked candidate lists and matching scores
- Output annotation report documents rank, matching score, and any alternative candidates (rank 2+) for features where the top candidate's score is close to second-ranked, aiding manual review

## Limitations

- Only features with sufficient pseudo-MS/MS spectral quality and fragment ion coverage will receive confident annotations; low signal-to-noise features may match only lower-ranked or false-positive candidates.
- Annotation rank and matching score depend heavily on the completeness and accuracy of the ion fragment library; databases with poor coverage of certain lipid classes or metabolite families will yield incomplete results.
- No changelog or version history is publicly available, limiting ability to assess improvements, bug fixes, or changes in matching algorithms across MetaboAnnotatoR releases.
- Default peak-picking thresholds (noise = 0.005, mpeaksThres = 0.1) may require optimization for different instrument platforms or acquisition protocols; suboptimal thresholds reduce spectrum quality and ranking reliability.

## Evidence

- [intro] Three out of six features were annotated to a lipid: "Three out of the six features were annotated with to a lipid"
- [other] LPC(14:0) assigned as rank 1 annotation for feature 3 at 468.3095 m/z: "LPC(14:0) assigned as the rank 1 annotation for feature 3 (468.3095 m/z, 82.92009 s)"
- [intro] annotateRC function matches fragment ions and retrieves ranked candidate annotations: "annotations can be performed using the *annotateRC* function"
- [intro] Ranked candidates can be inspected for each feature: "It is also possible to inspect if there were other candidate annotations for a given feature"
- [intro] Spectra visualization with matched ions supports annotation curation: "It is possible to visualise the spectra containing the matched ions to each candidate"
- [intro] Results saved to user-specified directory for downstream use: "It is possible to save the annotation results to a user-specified directory"
- [readme] Requires centroid-mode raw LC-MS AIF chromatograms processed via xcms and RAMClustR: "It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode"