Feature Metadata Parsing And Integration

---
name: feature-metadata-parsing-and-integration
description: 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3891
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0091
  - http://edamontology.org/topic_3520
  tools:
  - JPA
  - R
  - XCMS
  - CAMERA
  - MSnbase
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.3390/metabo12030212
  title: JPA
evidence_spans:
- JPA is a comprehensive and integrated metabolomics data processing software.
- JPA is a comprehensive and integrated metabolomics data processing software
- '''JPA'' is written in R and its source code is publicly available'
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_jpa_cq
    doi: 10.3390/metabo12030212
    title: JPA
  dedup_kept_from: coll_jpa_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.3390/metabo12030212
  all_source_dois:
  - 10.3390/metabo12030212
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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'."