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