Metabolomics Feature Transformation

metabolomics-feature-transformation

Summary

Sequential application of missing value replacement, log transformation, and scaling (mean-centering, auto-scaling, Pareto, or range scaling) to metabolomics feature intensity tables, with automatic tracking of intermediate transformation steps via compound column name suffixes and saved name vectors.

When to use

When you have a feature intensity table (samples × compounds) from targeted or non-targeted metabolomics and need to prepare it for statistical modeling or multivariate analysis. Use this skill when raw peak areas or intensities contain missing values, show right-skewed distributions, or have features with widely varying dynamic ranges—all common in LC-MS or GC-MS metabolomics data.

When NOT to use

• Input is already a pre-transformed, normalized, or scaled feature table—applying additional transformations risks over-processing and loss of interpretability.
• Missing value rate exceeds domain-specific tolerance (e.g., >50% missing in a feature)—missing value replacement may introduce artifacts without sufficient information.
• Feature intensities are already approximately normally distributed or follow a known, non-log-normal distribution—log transformation may worsen fit.

Inputs

• Feature intensity table (matrix or data.frame: samples × compounds with numeric intensity or peak area values)
• Legend table (optional; data.frame with sample identifiers, sample type classification (blank/curve/qc/unknown), and known concentration values for curve and QC samples)

Outputs

• Transformed feature table with columns named using compound suffixes (_mr, _mr_ln, _mr_ln_paretosc) reflecting transformation sequence
• Name vectors saved in global environment (prefixed vectors documenting original feature names and their transformed column identifiers for each transformation step)

How to apply

Load the feature table (samples in rows, compounds in columns) and optionally a legend table specifying sample types (blank, curve, qc, unknown) and concentrations. Call the transf_data function from GetFeatistics, enabling missing_replace=TRUE to substitute NA values (producing _mr suffix), log_transf=TRUE to apply natural logarithm transformation (adding _ln suffix), and specify a scaling method (scaling=TRUE with scale_type='pareto_scale' for Pareto scaling, producing _paretosc suffix). Set vect_names_transf=TRUE to automatically save intermediate column name vectors to the global environment with user-specified prefixes (name_vect_names argument). The function applies transformations sequentially and generates output columns with compound suffixes (_mr, _mr_ln, _mr_ln_paretosc) documenting the transformation lineage. Monitor the name vectors to verify correct feature tracking through each step.

Related tools

• GetFeatistics (R package providing transf_data function for sequential feature transformation with missing value replacement, log transformation, and scaling options) — https://github.com/FrigerioGianfranco/GetFeatistics
• R (Runtime environment (version ≥ 4.3.1) required for executing GetFeatistics package functions)
• ggplot2 (Used to visualize transformed feature distributions and relationships post-transformation)
• XCMS (Upstream non-targeted feature extraction tool; output feature tables are typical input to transformation workflow)
• MS-Dial (Alternative upstream non-targeted feature extraction tool; output feature tables are typical input to transformation workflow)

Examples

library(GetFeatistics); transf_data(data = feature_table, missing_replace = TRUE, log_transf = TRUE, scaling = TRUE, scale_type = 'pareto_scale', vect_names_transf = TRUE, name_vect_names = 'feat')

Evaluation signals

• Output column names follow expected compound suffix pattern (_mr, _mr_ln, _mr_ln_paretosc) and increase in length with each transformation step applied.
• Name vectors saved to global environment have correct length matching the number of features and document original feature identifiers before and after each transformation.
• No missing (NA) values remain in _mr or downstream columns if missing_replace=TRUE was specified.
• Log-transformed columns (_ln) contain only finite numeric values (no -Inf or NaN from log of zero or negative); negative values or zeros in original intensities should trigger investigation.
• Scaled columns (_paretosc for Pareto scaling) have mean near zero and standard deviation near unity across all samples; verify via colMeans() and apply(data, 2, sd).
• Comparing pre- and post-transformation univariate distributions (e.g., via qqplot or Shapiro-Wilk test on log-transformed columns) shows improved normality approximation.

Limitations

• Missing value replacement strategy (simple substitution) does not account for missing-at-random mechanisms; sophisticated imputation (KNN, multiple imputation) is not implemented in transf_data.
• Log transformation assumes all intensity values are positive; zero or negative intensities (rare but possible in some instrumental artifacts or data entry errors) must be pre-screened or handled via offset parameter before calling transf_data.
• Pareto scaling and other scaling methods assume features have sufficient variance; features with near-zero standard deviation may produce non-finite scaled values.
• Sequential transformation order (missing → log → scaling) is fixed; alternative orders (e.g., scaling before log) are not supported by transf_data and must be implemented manually.
• Name vector tracking relies on user-specified prefixes in name_vect_names argument; omitting or misspecifying this argument results in loss of transformation lineage documentation.

Evidence

• [other] Sequential transformation pattern with naming convention: "The transf_data function applies transformations sequentially: missing values are replaced (suffix _mr), followed by log transformation (suffix _ln), then scaling options including mean_scale,"
• [other] Name vector tracking and global environment storage: "the vect_names_transf argument automatically saves intermediate column name vectors in the global environment with prefixes specified in name_vect_names"
• [intro] Data format requirements and transformation steps: "The first should contain the intensities of peak area. Samples in rows, analysed compounds in columns"
• [intro] Missing value and log transformation implementation: "If missing_replace is TRUE, each NA in the data will be replaced...If log_transf is TRUE, the data will be log-transformed"
• [intro] Scaling parameter activation and method selection: "If scaling is TRUE, data will be scaled"
• [other] Pareto scaling mathematical definition: "Apply Pareto scaling to produce columns with paretosc suffix, dividing each feature by the square root of its standard deviation"
• [readme] Installation and invocation pattern: "devtools::install_github("FrigerioGianfranco/GetFeatistics", dependencies = TRUE)"