# Targeted Metabolite Extraction

> Use when you have centroided LC-MS data (.mzML format) and a curated list of targeted metabolites or lipids (with m/z, retention time, and polarity) that you want to quantify and quality-assess across multiple analytical runs, and you need both per-run AUC values and averaged QC metrics for each.

- Skill: `holobiomicslab/targeted-metabolite-extraction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/targeted-metabolite-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/targeted-metabolite-extraction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/targeted-metabolite-extraction

---


# targeted-metabolite-extraction

## Summary

Extract quantitative metrics (area under curve, max intensity, signal-to-noise ratio, peak correlation, and points over peak) for user-defined targeted compounds from centroided LC-MS data in .mzML format using the TARDIS tardisPeaks() function with screening_mode=FALSE. This skill automates peak detection and quality assessment across all runs after validating target visibility in a screening pass.

## When to use

Apply this skill when you have centroided LC-MS data (.mzML format) and a curated list of targeted metabolites or lipids (with m/z, retention time, and polarity) that you want to quantify and quality-assess across multiple analytical runs, and you need both per-run AUC values and averaged QC metrics for each target compound.

## When NOT to use

- Input files are not in centroided .mzML format — TARDIS requires centroided data and will not process profile-mode or unconverted raw formats.
- You only have untargeted metabolomics data and no predefined compound list — TARDIS is purpose-built for targeted analysis and requires a curated target list.
- You already have a pre-computed feature table with integrated peak areas — there is no need to re-extract and re-quantify.

## Inputs

- Centroided LC-MS data files in .mzML format
- Spectra object loaded from .mzML files
- Target list data.frame with columns: compound ID, name, m/z, retention time (minutes), polarity

## Outputs

- List object containing data.frame with per-target AUC values across all runs
- QC feature table tibble with average metrics (AUC, Max Intensity, SNR, peak_cor, points over peak) per target
- CSV files with per-metric tables exported to output directory
- Extracted ion chromatograms (EICs) saved to output folder for inspection

## How to apply

First, prepare input: convert raw LC-MS files to centroided .mzML format (e.g., using ProteoWizard MSConvert) and create a target list data.frame with compound ID, name, theoretical m/z, expected retention time in minutes, and polarity annotation. Load the mzML files as Spectra objects and apply retention-time correction using the xcms algorithm if needed (e.g., for targets with drift across runs). Execute tardisPeaks() with screening_mode=FALSE to perform peak detection across all runs; polarity filtering is applied automatically within TARDIS. Extract the resulting list object, which contains: a data.frame with AUC values per target per run, a tibble with average metrics (AUC, Max Intensity, SNR, peak_cor, points over peak) computed from QC runs, and per-metric CSV tables. Verify output by inspecting extracted ion chromatograms (EICs) saved to the output folder and checking that all targets produced valid peak detections.

## Related tools

- **TARDIS** (Primary R package that implements tardisPeaks() function for targeted peak detection, integration, and QC metric calculation in LC-MS data) — https://github.com/pablovgd/TARDIS
- **Spectra** (R/Bioconductor package for loading and representing LC-MS data as objects for input to TARDIS)
- **xcms** (Bioconductor package providing retention-time correction algorithm applied optionally before peak detection)
- **ProteoWizard** (MSConvert tool for converting raw LC-MS files to centroided .mzML format required by TARDIS)
- **MsExperiment** (Alternative input format (instead of file paths) for TARDIS peak detection)

## Examples

```
library(TARDIS); library(Spectra); spectra_obj <- Spectra(files=c('run1.mzML', 'run2.mzML')); targets <- data.frame(compound_id=c(1,2), name=c('metaboliteA', 'metaboliteB'), mz=c(200.05, 250.10), rt_min=c(5.2, 8.7), polarity=c(1,1)); results <- tardisPeaks(spectra=spectra_obj, targets=targets, screening_mode=FALSE, output_dir='./output')
```

## Evaluation signals

- All targets in the input list produce valid peak detections (non-zero AUC values) across sample runs and QC runs.
- EICs are successfully saved to the output folder and visual inspection confirms peak detection aligns with expected retention time and m/z windows for each target.
- QC feature table tibble contains averaged metrics (AUC, Max Intensity, SNR, peak_cor, points over peak) with values in expected ranges for your sample type (e.g., SNR > 3 for confident detections).
- Per-metric CSV files contain rows for all targets and columns for all analytical runs with no missing values (NaN/NA); numeric values are non-negative.
- Data.frame with per-run AUC values has dimensions matching (number of targets) × (number of analytical runs) with no NaN entries for successfully detected peaks.

## Limitations

- Requires input files to be in centroided .mzML format; profile-mode or non-standard formats will not be processed.
- Polarity filtering is automatic within TARDIS; users cannot override or manually adjust polarity assignments post hoc.
- Retention-time drift correction relies on the xcms algorithm; if xcms correction is inadequate for your data, targets may fail to integrate correctly.
- Peak detection performance depends on signal-to-noise ratio and peak resolution; low-abundance or co-eluting metabolites may not be reliably extracted.
- No changelog is available in the repository documentation, so users should verify version compatibility and breaking changes manually.

## Evidence

- [intro] Input files requirement: "Input files need to be converted to the .mzML format and have to be centroided"
- [intro] Target list format: "compound ID, a unique identifier; A compound Name; Theoretical or measured *m/z*; Expected RT (in minutes); A column that indicates the polarity"
- [intro] Peak detection mode execution: "perform peak detection in all our runs by setting `screening_mode = FALSE`"
- [results] Output data structures: "The `results` object is a `list` that contains a `data.frame` with the AUC of each target in each run"
- [results] QC metrics output: "a `tibble` that contains a feature table with the average metrics for each target in the QC runs"
- [results] Per-metric CSV tables: "Other results include tables with the other metrics (Max. Int., SNR, peak_cor and points over the peak)"
- [results] EIC output and inspection: "The resulting EICs are again saved in the output folder and can be inspected"
- [intro] Polarity handling: "Polarity filtering is done within `TARDIS`, so no polarity subsetting has to be performed"
- [intro] xcms retention-time correction: "It makes use of an established retention time correction algorithm from the `xcms` package"
- [intro] Spectra integration: "loads MS data as `Spectra` objects so it's easily integrated with other tools"