metabolite-feature-matrix-manipulation
Summary
Prepare and transform raw metabolomics intensity matrices into analysis-ready featuredata objects through log transformation and missing-value handling. This skill enables downstream normalization, biomarker identification, and statistical modeling by standardizing the input data format and distribution.
When to use
Apply this skill when you have raw metabolomics peak intensity or concentration data in matrix form (samples as rows, metabolites as columns) and need to prepare it for normalization or statistical analysis. Specifically, use it when the data exhibits non-normal (right-skewed) intensity distributions, contains missing values from incomplete analyses or below-detection-limit measurements, or requires standardization before batch-effect correction or biomarker discovery workflows.
When NOT to use
- Input data is already normalized, batch-corrected, or log-transformed by upstream processing.
- Missing values represent true biological zeros (e.g., metabolites absent in certain samples) — replacement or imputation may introduce bias; consider filtering instead.
- Data is already in a reduced-dimension or summary format (e.g., PCA scores, averaged across replicates) rather than raw feature-level intensities.
Inputs
- raw featuredata matrix (samples × metabolites, numeric intensities or concentrations)
- sample row names (unique sample identifiers)
- metabolite column names (unique metabolite identifiers)
Outputs
- log-transformed featuredata matrix
- imputed featuredata matrix (missing values replaced)
- processed featuredata object ready for normalization or statistical analysis
How to apply
Load the raw featuredata matrix (sample names as row names, metabolite names as column names) into R. Apply LogTransform() with base=exp(1) to convert intensity values to log scale, addressing the non-normal distribution typical of metabolomics measurements. Then apply MissingValues() to handle missing data using either k-nearest-neighbor (knn) imputation for data missing at random, or replacement methods (e.g., half minimum detection limit) for values below detection threshold. The choice between methods depends on the missing-data mechanism: use knn for sparse, random missingness; use replacement for systematic missingness associated with detection limits. Validate that the resulting featuredata matrix contains no missing values and has appropriate numeric range for downstream normalization (typically log-transformed intensities with mean near zero and sd near 1 before normalization). Store the processed featuredata as an R object for input to NormQcmets(), NormScaling(), or LinearModelFit().
Related tools
- LogTransform (Applies log transformation (base e by default) to featuredata matrix to normalize intensity distributions) — github.com/metabolomicstats/NormalizeMets
- MissingValues (Replaces or imputes missing values in featuredata depending on missingness mechanism (knn or replacement methods)) — github.com/metabolomicstats/NormalizeMets
- R (Execution environment for loading, manipulating, and validating metabolomics matrices)
- NormalizeMets (R package containing LogTransform and MissingValues functions and dependent workflow functions) — github.com/metabolomicstats/NormalizeMets
Examples
LogTransform(featuredata, base=exp(1), saveoutput=FALSE); featuredata_imputed <- MissingValues(featuredata_log, method=c('knn'))
Evaluation signals
- Log-transformed featuredata has numeric values with plausible range (typically mean ~0–1 log scale) suitable for normalization; no negative values if base-e log of positive intensities.
- Imputed featuredata contains zero missing values (100% completeness) across all samples and metabolites; missingness summary shows all replaced values documented.
- Row and column names are preserved, unique, and match the original featuredata dimensions; sample and metabolite identities are traceable.
- Distribution of log-transformed intensities is approximately normal or unimodal (inspect via histogram or Q-Q plot); skewness reduced compared to raw intensity distribution.
- Imputation choice is justified by missing-data pattern: knn applied to sparse random missingness; replacement applied to systematic below-detection-limit missingness.
Limitations
- Log transformation assumes all intensity values are positive; zero or negative values will produce NaN or -Inf, requiring filtering or pseudocount addition before transformation.
- Missing-value imputation introduces uncertainty; knn imputation accuracy depends on number of observed neighbors and data dimensionality; replacement at LOD threshold is conservative but may underestimate true biological signals.
- This skill does not address batch effects, matrix effects, or other sources of unwanted variation; normalized data should be processed through NormQcmets() or NormCombined() for batch correction.
- The choice of imputation method (knn vs. replacement) is not automated; analyst must inspect missing-data patterns and justify method selection per study design.
Evidence
- [other] Log transforming, handling missing values, and visualization: "Log transforming, handling missing values, and visualization"
- [other] A metabolomics data matrix in the featuredata format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1), saveoutput=FALSE,: "A metabolomics data matrix in the featuredata format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1)"
- [other] The following
MissingValues() function can be used to replace missing values, depending on the nature of missing data.: "The following MissingValues() function can be used to replace missing values, depending on the nature of missing data."
- [other] Load the imputed featuredata matrix (log-transformed, missing values handled via knn or replacement) and a design matrix (factormat) encoding factors of interest: "Load the imputed featuredata matrix (log-transformed, missing values handled via knn or replacement) and a design matrix"
- [readme] The input data format consists of three parts: (i) "featuredata" which is the metabolomics data matrix containing all metabolite peak intensities (or concentrations). Unique sample names must be provided as row names and unique metabolite names as column names: "featuredata" which is the metabolomics data matrix containing all metabolite peak intensities. Unique sample names must be provided as row names and unique metabolite names as column names"
1---2name: metabolite-feature-matrix-manipulation3description: Use when you have raw metabolomics peak intensity or concentration data in matrix form (samples as rows, metabolites as columns) and need to prepare it for normalization or statistical analysis.4license: CC-BY-4.05---67# metabolite-feature-matrix-manipulation89## Summary1011Prepare and transform raw metabolomics intensity matrices into analysis-ready featuredata objects through log transformation and missing-value handling. This skill enables downstream normalization, biomarker identification, and statistical modeling by standardizing the input data format and distribution.1213## When to use1415Apply this skill when you have raw metabolomics peak intensity or concentration data in matrix form (samples as rows, metabolites as columns) and need to prepare it for normalization or statistical analysis. Specifically, use it when the data exhibits non-normal (right-skewed) intensity distributions, contains missing values from incomplete analyses or below-detection-limit measurements, or requires standardization before batch-effect correction or biomarker discovery workflows.1617## When NOT to use1819- Input data is already normalized, batch-corrected, or log-transformed by upstream processing.20- Missing values represent true biological zeros (e.g., metabolites absent in certain samples) — replacement or imputation may introduce bias; consider filtering instead.21- Data is already in a reduced-dimension or summary format (e.g., PCA scores, averaged across replicates) rather than raw feature-level intensities.2223## Inputs2425- raw featuredata matrix (samples × metabolites, numeric intensities or concentrations)26- sample row names (unique sample identifiers)27- metabolite column names (unique metabolite identifiers)2829## Outputs3031- log-transformed featuredata matrix32- imputed featuredata matrix (missing values replaced)33- processed featuredata object ready for normalization or statistical analysis3435## How to apply3637Load the raw featuredata matrix (sample names as row names, metabolite names as column names) into R. Apply LogTransform() with base=exp(1) to convert intensity values to log scale, addressing the non-normal distribution typical of metabolomics measurements. Then apply MissingValues() to handle missing data using either k-nearest-neighbor (knn) imputation for data missing at random, or replacement methods (e.g., half minimum detection limit) for values below detection threshold. The choice between methods depends on the missing-data mechanism: use knn for sparse, random missingness; use replacement for systematic missingness associated with detection limits. Validate that the resulting featuredata matrix contains no missing values and has appropriate numeric range for downstream normalization (typically log-transformed intensities with mean near zero and sd near 1 before normalization). Store the processed featuredata as an R object for input to NormQcmets(), NormScaling(), or LinearModelFit().3839## Related tools4041- **LogTransform** (Applies log transformation (base e by default) to featuredata matrix to normalize intensity distributions) — github.com/metabolomicstats/NormalizeMets42- **MissingValues** (Replaces or imputes missing values in featuredata depending on missingness mechanism (knn or replacement methods)) — github.com/metabolomicstats/NormalizeMets43- **R** (Execution environment for loading, manipulating, and validating metabolomics matrices)44- **NormalizeMets** (R package containing LogTransform and MissingValues functions and dependent workflow functions) — github.com/metabolomicstats/NormalizeMets4546## Examples4748```49LogTransform(featuredata, base=exp(1), saveoutput=FALSE); featuredata_imputed <- MissingValues(featuredata_log, method=c('knn'))50```5152## Evaluation signals5354- Log-transformed featuredata has numeric values with plausible range (typically mean ~0–1 log scale) suitable for normalization; no negative values if base-e log of positive intensities.55- Imputed featuredata contains zero missing values (100% completeness) across all samples and metabolites; missingness summary shows all replaced values documented.56- Row and column names are preserved, unique, and match the original featuredata dimensions; sample and metabolite identities are traceable.57- Distribution of log-transformed intensities is approximately normal or unimodal (inspect via histogram or Q-Q plot); skewness reduced compared to raw intensity distribution.58- Imputation choice is justified by missing-data pattern: knn applied to sparse random missingness; replacement applied to systematic below-detection-limit missingness.5960## Limitations6162- Log transformation assumes all intensity values are positive; zero or negative values will produce NaN or -Inf, requiring filtering or pseudocount addition before transformation.63- Missing-value imputation introduces uncertainty; knn imputation accuracy depends on number of observed neighbors and data dimensionality; replacement at LOD threshold is conservative but may underestimate true biological signals.64- This skill does not address batch effects, matrix effects, or other sources of unwanted variation; normalized data should be processed through NormQcmets() or NormCombined() for batch correction.65- The choice of imputation method (knn vs. replacement) is not automated; analyst must inspect missing-data patterns and justify method selection per study design.6667## Evidence6869- [other] Log transforming, handling missing values, and visualization: "Log transforming, handling missing values, and visualization"70- [other] A metabolomics data matrix in the _featuredata_ format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1), saveoutput=FALSE,: "A metabolomics data matrix in the _featuredata_ format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1)"71- [other] The following `MissingValues()` function can be used to replace missing values, depending on the nature of missing data.: "The following `MissingValues()` function can be used to replace missing values, depending on the nature of missing data."72- [other] Load the imputed featuredata matrix (log-transformed, missing values handled via knn or replacement) and a design matrix (factormat) encoding factors of interest: "Load the imputed featuredata matrix (log-transformed, missing values handled via knn or replacement) and a design matrix"73- [readme] The input data format consists of three parts: (i) "featuredata" which is the metabolomics data matrix containing all metabolite peak intensities (or concentrations). Unique sample names must be provided as row names and unique metabolite names as column names: "featuredata" which is the metabolomics data matrix containing all metabolite peak intensities. Unique sample names must be provided as row names and unique metabolite names as column names"
HolobiomicsLab 