# Mass Spectrometry Quality Metrics Extraction

> Use when you have centroided .mzML LC–MS data, a validated target compound list with adjusted expected retention times (e.g., after a screening mode run), and need to quantify peak quality and integration reliability across multiple sample runs to support metabolomics or lipidomics workflows.

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

---


# mass-spectrometry-quality-metrics-extraction

## Summary

Automated extraction of quantitative quality metrics (AUC, Max. Int., SNR, peak_cor, points_over_peak) for targeted chemical compounds from LC–MS data using TARDIS. This skill enables systematic assessment of peak detection reliability across multiple sample runs after retention time adjustment.

## When to use

Apply this skill when you have centroided .mzML LC–MS data, a validated target compound list with adjusted expected retention times (e.g., after a screening mode run), and need to quantify peak quality and integration reliability across multiple sample runs to support metabolomics or lipidomics workflows.

## When NOT to use

- Input files are not in centroided .mzML format; file conversion and centroiding must be completed first.
- Target compound list lacks adjusted retention times or was not validated through prior screening mode; execute screening_mode = TRUE first to identify correct RT windows.
- Data contains only profile-mode (non-centroided) spectra; TARDIS requires centroided input to avoid sawtooth profiles from overlapping m/z scan windows.

## Inputs

- Centroided .mzML files (LC–MS raw data)
- Spectra object (loaded via Spectra package)
- Target compound data.frame with columns: compound ID, Name, m/z, expected RT (minutes), polarity

## Outputs

- Results list object containing data.frame with AUC per target per run
- Tibble with average metrics (Max. Int., SNR, peak_cor, points_over_peak) per target in QC runs
- Tables saved to output folder: Max. Int., SNR, peak_cor, points_over_peak matrices
- Extracted Ion Chromatograms (EICs) saved to output folder

## How to apply

Load centroided .mzML files as Spectra objects using the Spectra package. Create or update a data.frame describing target compounds with columns for compound ID, Name, m/z, expected RT (in minutes), and polarity. Execute the tardisPeaks function with screening_mode = FALSE to perform peak detection and integration across all runs. The function automatically applies polarity filtering and outputs a results list containing a data.frame with AUC for each target in each run, a tibble with average metrics for QC runs, and separate tables for Max. Int., SNR, peak_cor, and points_over_peak saved to the output folder. Use the returned metrics to evaluate consistency and reliability of peak detection across the sample cohort.

## Related tools

- **TARDIS** (Primary peak detection, integration, and quality metrics computation engine; executes tardisPeaks function with specified screening_mode and polarity parameters) — https://github.com/pablovgd/TARDIS
- **Spectra** (Loads centroided .mzML files as Spectra objects for integration with TARDIS; provides data structure interface to mass spectrometry data)
- **xcms** (Supplies established retention time correction algorithm used within TARDIS for RT alignment)
- **R** (Runtime environment for TARDIS package, Spectra integration, and target compound table manipulation) — https://cloud.r-project.org/index.html

## Examples

```
library(TARDIS); library(Spectra); targets <- read.csv('targets_adjusted.csv'); sp <- readMsExperiment(files = list.files('mzML/', full.names=TRUE)); results <- tardisPeaks(Spectra = sp, targets = targets, screening_mode = FALSE, output_folder = './results/')
```

## Evaluation signals

- Results object is a list containing a data.frame with AUC values and a tibble with average metrics (no missing or malformed rows for valid targets).
- Output folder contains expected tables: Max. Int., SNR, peak_cor, points_over_peak matrices with dimensions matching number of targets × number of runs.
- AUC values are numeric and fall within expected range for integrated peak areas in the sample's m/z and RT domain.
- SNR values are positive and vary appropriately across runs and targets (high SNR for strong peaks, low for weak or absent peaks).
- EICs saved to output folder are visually inspectable and display expected peak shapes consistent with the adjusted retention times.

## Limitations

- Peaks in data with multiple overlapping m/z scan windows may display a sawtooth profile due to filtering of empty spectra within TARDIS; this is a known artifact of the data structure, not a quality failure.
- Polarity filtering is performed automatically within TARDIS; users cannot customize polarity thresholds—all targets must be assigned a polarity column value.
- Retention time adjustment must be performed prior to full-run execution; if expected RT values are incorrect, peak detection will fail silently or return zero/low metrics for affected targets.

## Evidence

- [results] describes_metrics_output: "TARDIS automatically calculates area under the peak, max intensity and various quality metrics for targeted chemical compounds in LC-MS data"
- [results] describes_results_list_structure: "The results object is a list containing a data.frame with the AUC of each target in each run and a tibble with average metrics for each target in the QC runs"
- [results] describes_additional_metrics_tables: "Other results include tables with the other metrics (Max. Int., SNR, peak_cor and points over the peak)"
- [intro] describes_screening_mode_prerequisite: "First, we perform a screening step to check if our targets are visible within our m/z and RT windows"
- [intro] describes_full_run_execution: "Now we can perform peak detection in all our runs by setting screening_mode = FALSE"
- [intro] describes_input_format_requirement: "Input files need to be converted to the .mzML format and have to be centroided"
- [intro] describes_polarity_filtering: "Polarity filtering is done within TARDIS, so no polarity subsetting has to be performed"
- [intro] describes_sawtooth_artifact: "you will notice that peaks will have a sawtooth profile, because of the filtering of empty spectra within TARDIS"
- [readme] describes_installation_r_requirement: "Make sure R (version >= 4.4.0) is installed on your computer"
- [readme] describes_gui_launch_method: "To launch the GUI in R: runTardis()"