# Feature Metadata Parsing And Integration

> Use when after completing sample alignment in JPA (Part 5) or when ingesting a peaklist or aligned feature matrix from prior peak-picking runs, parse feature metadata to enable EIC export or multi-sample feature annotation.

- Skill: `holobiomicslab/feature-metadata-parsing-and-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/feature-metadata-parsing-and-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/feature-metadata-parsing-and-integration/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/feature-metadata-parsing-and-integration

---


# feature-metadata-parsing-and-integration

## Summary

Extract and structure m/z, retention time, intensity, and sample assignment metadata from aligned feature tables generated by metabolomics peak-picking or MS2 recognition workflows. This skill prepares feature metadata for downstream analysis by normalizing heterogeneous feature table formats into a consistent R data structure suitable for ion chromatogram extraction and export.

## When to use

After completing sample alignment in JPA (Part 5) or when ingesting a peaklist or aligned feature matrix from prior peak-picking runs, parse feature metadata to enable EIC export or multi-sample feature annotation. Trigger this skill when you have aligned features and need to map individual features to their underlying mass spectrometry characteristics (m/z, RT windows, intensities, sample memberships) for quality control or visualization.

## When NOT to use

- Input is single-sample, non-aligned peak picking output (use MS1 peak picking directly without alignment/metadata integration)
- Feature metadata is already in vendor-specific format and upstream tools (e.g., MS-DIAL, XCMS) have not yet been applied to your cohort
- You are processing full-scan or DIA (data-independent acquisition) data without MS2 recognition steps, where feature metadata schemas may differ from DDA assumptions

## Inputs

- aligned feature table (CSV, dataframe, or JPA-native peaklist format)
- feature metadata: m/z values, retention times, retention time windows (rtmin/rtmax in seconds)
- sample identifiers and feature intensities/heights
- raw LC-MS data file (mzXML, netCDF, or MS-Convert-compatible format) for validation (optional)

## Outputs

- parsed feature table (R dataframe) with standardized columns: mz, rt, rtmin, rtmax, maxo, sample, level
- validated feature metadata schema
- MSnbase object or reference to underlying mass spectrometry data
- feature-to-sample mapping for multi-sample cohorts

## How to apply

Load the aligned feature table (peaklist or feature matrix) into the R environment using JPA data structures. Extract and validate the presence of required metadata columns: m/z, retention time (rt), minimum and maximum retention time (rtmin, rtmax in seconds), intensity/height, and sample identifiers. Verify that retention time columns are in seconds and m/z values are numeric; resolve any unit inconsistencies. For multi-sample analyses, ensure each feature row includes a sample assignment column. Cross-reference metadata against the original raw mass spectrometry data or MSnbase object to confirm that m/z and RT ranges are consistent with feature boundaries. Store the parsed metadata in a standardized dataframe with columns ordered as: mz, rt, rtmin, rtmax, maxo (intensity), sample, level (feature type indicator).

## Related tools

- **JPA** (R package that defines feature table structures and metadata schemas; provides XCMS.featureTable() and custom.featureTable() functions for loading and normalizing feature metadata into standardized dataframes) — https://github.com/HuanLab/JPA.git
- **XCMS** (Bioconductor package embedded in JPA for peak picking and feature extraction; generates initial feature metadata (m/z, RT, intensity) consumed by metadata parsing) — https://rdrr.io/bioc/xcms/man/
- **CAMERA** (Part 6 of JPA workflow; performs adduct and isotope annotation on parsed feature metadata prior to MS2 annotation)
- **MSnbase** (R/Bioconductor object framework used by JPA to store and query raw mass spectrometry data and feature metadata in a unified structure)

## Examples

```
featureTable <- XCMS.featureTable(dir = "X:/Users/JPAtest_20210330/multiDDA", mz.tol = 10, ppm=10, peakwidth=c(5,20), mzdiff = 0.01, snthresh = 6, integrate = 1, prefilter = c(3,100), noise = 100); head(featureTable)
```

## Evaluation signals

- Feature table dataframe has exactly 7 columns in correct order (mz, rt, rtmin, rtmax, maxo, sample, level) with no missing values in metadata fields
- m/z values are numeric, positive, and within expected range (typically 40–2000 m/z for metabolomics); retention times (rt, rtmin, rtmax) are numeric, positive, and in seconds
- rtmin < rt < rtmax for every feature row (retention time ordering invariant)
- Sample identifiers are consistent with input cohort and map correctly to underlying raw data file(s); all samples referenced in feature table have corresponding mzXML or netCDF input files
- Intensity/height (maxo column) values are non-negative numeric; features with identical m/z and RT (within tolerance) are not duplicated across samples after alignment

## Limitations

- CSV input from non-JPA tools (e.g., MS-DIAL) must be pre-converted using the provided convertCSV.R helper script; other formats require custom column reordering and may introduce data loss or type mismatches
- Retention time metadata assumes all RT values are in seconds; vendor-specific formats (e.g., minutes in Thermo or Waters output) must be manually converted or parsing will fail
- Multi-sample alignment metadata integration assumes samples are aligned using Part 5 of JPA workflow; pre-aligned feature tables from external alignment software may have different schema and require additional preprocessing
- Feature metadata parsing does not validate ion m/z accuracy against theoretical monoisotopic masses or expected adduct distributions; schema validation alone cannot detect systematic mass calibration errors
- For multi-sample cohorts, metadata parsing assumes one aligned feature table per sample or one unified aligned table; mixed input formats (some aligned, some raw) are not supported

## Evidence

- [other] Parse feature metadata (m/z, retention time, intensity, sample assignments) from the feature table.: "Parse feature metadata (m/z, retention time, intensity, sample assignments) from the feature table."
- [readme] The input feature table contain only columns in the following order: m/z, retention time, min retention time, max retention time, intensity. Note: column 3 and column 4 are the retention time of the feature edges, and all three columns containing retention time information should be in seconds.: "The input feature table contain only columns in the following order: m/z, retention time, min retention time, max retention time, intensity. Note: column 3 and column 4 are the retention time of the"
- [readme] The XCMS.featureTable() function outputs a dataframe formatted featuretable as well as an MSnbase object. The "level" column shows the level of each feature.: "The XCMS.featureTable() function outputs a dataframe formatted featuretable as well as an MSnbase object. The "level" column shows the level of each feature."
- [readme] For multi-sample analysis, a CSV feature table for each single mzXML file needs to be provided. Aligned feature table is not acceptable.: "For multi-sample analysis, a CSV feature table for each single mzXML file needs to be provided. Aligned feature table is not acceptable."
- [readme] An R code (convertCSV.R) is provided to help user transform the csv from MS-DIAL output to the format recognizable by 'JPA'.: "An R code (convertCSV.R) is provided to help user transform the csv from MS-DIAL output to the format recognizable by 'JPA'."