HolobiomicsLab Feature Table Format Handling
Summary
Convert, validate, and manage metabolomic feature tables across multiple formats (CSV, RData, tabular) while preserving sample and feature identifiers for downstream processing in LC-MS untargeted profiling workflows. This skill ensures consistent representation of intensity matrices (samples × features) with associated metadata throughout the nine-step OUKS pipeline.
When to use
Apply this skill when transitioning feature intensity data between pipeline stages (e.g., post-integration to pre-imputation, post-correction to pre-filtering), when importing raw peak-picked data into R for OUKS processing, or when exporting corrected/normalized tables for external validation or cross-tool analysis. Specifically use it when the feature table must preserve QC sample identifiers and run-order metadata needed for batch correction, or when downstream steps require specific row/column ordering or naming conventions.
When NOT to use
- Input is already a validated, in-memory R data.frame ready for imputation or normalization without format conversion.
- Feature table lacks clear sample or feature identifiers (unindexed or single-column layouts) and cannot be reliably parsed into samples × features structure.
- QC sample labels are inconsistent or missing but required for batch correction or drift assessment steps.
Inputs
- Raw feature intensity table (samples × features, CSV or tabular format)
- Sample metadata (class labels, QC identifiers, batch/run-order columns)
- Feature annotations (m/z, retention time, or feature IDs as column names)
- RData objects containing pre-computed feature tables from prior pipeline stages
Outputs
- Validated feature intensity matrix (samples × features) in R memory
- Corrected or filtered feature table (CSV or RData) with preserved identifiers
- Sample-feature mapping metadata for traceability and validation
How to apply
Load the feature intensity matrix (samples × features dimension) along with associated metadata (sample class labels, QC identifiers, batch/run-order information) into R as a data.frame or matrix. Validate that row names match sample identifiers in the metadata file and column names correspond to detected features (m/z-RT pairs or feature IDs). Standardize column/row naming to remove special characters or whitespace that may cause parsing errors in downstream R packages. For tables requiring QC-based correction (e.g., before MetCorR GAM application), ensure QC sample rows are clearly marked with a consistent label (e.g., 'QC') in the class column. Export corrected or filtered tables as CSV or RData format, preserving the same sample-feature structure and identifiers to maintain traceability through the pipeline.
Related tools
- R (Primary environment for loading, validating, and exporting feature tables as data.frames; manages metadata integration) — https://cran.r-project.org/index.html
- MetCorR (Consumes feature table with QC labels and batch metadata; outputs corrected intensity matrix preserving original structure) — https://github.com/plyush1993/MetCorR
- OUKS (Pipeline framework integrating feature table handling across nine processing steps; scripts load/export tables at each stage) — https://github.com/plyush1993/OUKS
Examples
# Load feature table and metadata into R
int_data <- read.csv('feature_intensity_table.csv', row.names=1)
meta <- read.csv('metadata.csv', row.names=1)
# Pass to MetCorR for QC-GAM correction
out <- MetCorR(method=2, int_data=int_data, order=meta$order, class=meta$class, batch=meta$batch, qc_label='QC')
# Export corrected table
write.csv(out$corrected_data, 'corrected_feature_table.csv')
Evaluation signals
- Feature table dimensions (samples × features) are preserved after load/export cycles; row count equals number of samples, column count equals number of detected features.
- Sample and feature identifiers remain intact and human-readable post-processing (no truncation, corruption, or encoding artifacts).
- QC sample rows are correctly marked and retrievable from the metadata class column for use in batch correction algorithms.
- Intensity values remain numeric, without conversion to strings or loss of precision; NaN/NA missingness is handled consistently.
- CSV and RData formats are round-trip compatible: loading and re-exporting produces functionally identical tables with identical row/column ordering.
Limitations
- No guidance provided on parameter selection, sensitivity analysis, or tuning for handling sparse or high-dimensional tables (>>10,000 features).
- Article does not specify maximum table size, memory requirements, or performance characteristics for very large sample cohorts (>10,000 samples).
- No validation dataset or benchmarking study documented to assess format handling robustness across different LC-MS instrument outputs or vendor software exports.
- R version requirement (≥4.1.2) is stated but compatibility with newer major versions or older legacy R code is not tested.
Evidence
- [other] Load the QC-annotated feature table (samples × features with QC sample identifiers) into R.: "Load the QC-annotated feature table (samples × features with QC sample identifiers) into R."
- [other] Output the corrected feature table in CSV or tabular format, preserving sample and feature identifiers.: "Output the corrected feature table in CSV or tabular format, preserving sample and feature identifiers."
- [readme] Scripts (R) with comments, notes and references are stored in Scripts folder: "Scripts (R) with comments, notes and references are stored in Scripts folder at a previously defined order"
- [readme] Datasets in .csv and other files (.RData, .R) are available for reproducibility: "Datasets in .csv and other files (.RData, .R) are available for reproducibility from corresponding folders."