log-transformation-application
Summary
Log-transformation of metabolomics feature intensity matrices to stabilize variance and handle zeros before normalization. This pre-processing step converts raw peak intensities to a log scale, making downstream normalization methods more effective by reducing the impact of extreme values and improving homogeneity of variance.
When to use
Apply log-transformation immediately after loading a raw metabolomics featuredata matrix (metabolite peak intensities as rows=samples, columns=metabolites) and before normalization. Essential when the data exhibits skewed distributions with right-tail outliers (typical of untransformed mass spectrometry intensities) or contains zero values that would violate assumptions of downstream normalization methods such as 'is', 'nomis', 'ccmn', 'ruv2', or 'ruvrand'.
When NOT to use
- Data is already log-transformed or normalized (check for mean
0, SD1, or verify prior transformation steps)
- featuredata contains only positive, non-zero values with symmetric, approximately normal distribution already
- Missing data is not compatible with your downstream analysis (LogTransform with zerotona=TRUE creates NAs that require imputation)
Inputs
- featuredata matrix (numeric; rows=samples, columns=metabolites; raw peak intensities or concentrations)
- base parameter (numeric; default=exp(1) for natural logarithm)
- zerotona parameter (logical; TRUE to replace zeros with NA)
Outputs
- log-transformed featuredata matrix (numeric; same dimensions as input; zeros converted to NA)
- LogTransform output object (R object containing transformed matrix and metadata)
How to apply
Call the LogTransform function with the featuredata matrix as input, setting base=exp(1) (natural logarithm) and zerotona=TRUE to convert zero values to NA before transformation. The zerotona parameter is critical: it replaces zeros with missing values, which are then handled in the next step via MissingValues with feature.cutoff=0.8, sample.cutoff=0.8, and method='knn' or 'replace'. The natural log scale is chosen because it approximates the multiplicative error structure typical of analytical instruments. After log-transformation and missing-value imputation, extract the transformed featuredata matrix and proceed to identify internal standards (QC metabolites) from metabolitedata before calling NormQcmets.
Related tools
- NormalizeMets (R package providing LogTransform function and downstream normalization workflow) — github.com/metabolomicstats/NormalizeMets
- R (Execution environment for LogTransform and featuredata matrix operations)
- RStudio (Recommended IDE for interactive LogTransform execution and result inspection)
- MissingValues (Companion function (applied after LogTransform) to impute NA values created by zerotona=TRUE) — github.com/metabolomicstats/NormalizeMets
Examples
LogTransform(featuredata = mixdata$featuredata, base = exp(1), zerotona = TRUE)
Evaluation signals
- Transformed featuredata has no zero values; all zeros are converted to NA (verify via sum(featuredata==0, na.rm=TRUE)==0)
- Distribution of transformed values is approximately symmetric and unimodal (inspect via histogram or density plot)
- Mean of log-transformed intensities is near zero; standard deviation is stable across metabolites (run colMeans and colSds on result)
- Outliers in original space are reduced in magnitude after transformation (compare boxplot before/after)
- Missing-value imputation (via MissingValues) succeeds on the transformed matrix with no samples or metabolites removed beyond feature.cutoff=0.8 or sample.cutoff=0.8 thresholds
Limitations
- zerotona=TRUE converts zeros to NA; subsequent imputation (MissingValues) may fail or remove features if too many zeros are present per metabolite or sample
- Natural logarithm is undefined for negative values; ensure featuredata contains only non-negative intensities before transformation
- Log-transformation assumes multiplicative error structure; if errors are additive or data are already heavily pre-processed, transformation may not improve normalization
- Base=exp(1) (natural log) is the recommended choice; other bases are supported but changing base may affect downstream interpretation of effect sizes in linear models
Evidence
- [other] Log-transform the featuredata using LogTransform with base=exp(1) and zerotona=TRUE to handle zeros.: "Log-transform the featuredata using LogTransform with base=exp(1) and zerotona=TRUE to handle zeros."
- [other] A metabolomics data matrix in the featuredata format can be transformed using the LogTransform function.: "A metabolomics data matrix in the featuredata format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1), saveoutput=FALSE,"
- [other] The following MissingValues() function can be used to replace missing values after log-transformation.: "The following
MissingValues() function can be used to replace missing values, depending on the nature of missing data."
- [readme] Metabolomics data are subject to unwanted variation due to batch effects and matrix effects.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation."
1---2name: log-transformation-application3description: Use when apply log-transformation immediately after loading a raw metabolomics featuredata matrix (metabolite peak intensities as rows=samples, columns=metabolites) and before normalization.4license: CC-BY-4.05---67# log-transformation-application89## Summary1011Log-transformation of metabolomics feature intensity matrices to stabilize variance and handle zeros before normalization. This pre-processing step converts raw peak intensities to a log scale, making downstream normalization methods more effective by reducing the impact of extreme values and improving homogeneity of variance.1213## When to use1415Apply log-transformation immediately after loading a raw metabolomics featuredata matrix (metabolite peak intensities as rows=samples, columns=metabolites) and before normalization. Essential when the data exhibits skewed distributions with right-tail outliers (typical of untransformed mass spectrometry intensities) or contains zero values that would violate assumptions of downstream normalization methods such as 'is', 'nomis', 'ccmn', 'ruv2', or 'ruvrand'.1617## When NOT to use1819- Data is already log-transformed or normalized (check for mean~0, SD~1, or verify prior transformation steps)20- featuredata contains only positive, non-zero values with symmetric, approximately normal distribution already21- Missing data is not compatible with your downstream analysis (LogTransform with zerotona=TRUE creates NAs that require imputation)2223## Inputs2425- featuredata matrix (numeric; rows=samples, columns=metabolites; raw peak intensities or concentrations)26- base parameter (numeric; default=exp(1) for natural logarithm)27- zerotona parameter (logical; TRUE to replace zeros with NA)2829## Outputs3031- log-transformed featuredata matrix (numeric; same dimensions as input; zeros converted to NA)32- LogTransform output object (R object containing transformed matrix and metadata)3334## How to apply3536Call the LogTransform function with the featuredata matrix as input, setting base=exp(1) (natural logarithm) and zerotona=TRUE to convert zero values to NA before transformation. The zerotona parameter is critical: it replaces zeros with missing values, which are then handled in the next step via MissingValues with feature.cutoff=0.8, sample.cutoff=0.8, and method='knn' or 'replace'. The natural log scale is chosen because it approximates the multiplicative error structure typical of analytical instruments. After log-transformation and missing-value imputation, extract the transformed featuredata matrix and proceed to identify internal standards (QC metabolites) from metabolitedata before calling NormQcmets.3738## Related tools3940- **NormalizeMets** (R package providing LogTransform function and downstream normalization workflow) — github.com/metabolomicstats/NormalizeMets41- **R** (Execution environment for LogTransform and featuredata matrix operations)42- **RStudio** (Recommended IDE for interactive LogTransform execution and result inspection)43- **MissingValues** (Companion function (applied after LogTransform) to impute NA values created by zerotona=TRUE) — github.com/metabolomicstats/NormalizeMets4445## Examples4647```48LogTransform(featuredata = mixdata$featuredata, base = exp(1), zerotona = TRUE)49```5051## Evaluation signals5253- Transformed featuredata has no zero values; all zeros are converted to NA (verify via sum(featuredata==0, na.rm=TRUE)==0)54- Distribution of transformed values is approximately symmetric and unimodal (inspect via histogram or density plot)55- Mean of log-transformed intensities is near zero; standard deviation is stable across metabolites (run colMeans and colSds on result)56- Outliers in original space are reduced in magnitude after transformation (compare boxplot before/after)57- Missing-value imputation (via MissingValues) succeeds on the transformed matrix with no samples or metabolites removed beyond feature.cutoff=0.8 or sample.cutoff=0.8 thresholds5859## Limitations6061- zerotona=TRUE converts zeros to NA; subsequent imputation (MissingValues) may fail or remove features if too many zeros are present per metabolite or sample62- Natural logarithm is undefined for negative values; ensure featuredata contains only non-negative intensities before transformation63- Log-transformation assumes multiplicative error structure; if errors are additive or data are already heavily pre-processed, transformation may not improve normalization64- Base=exp(1) (natural log) is the recommended choice; other bases are supported but changing base may affect downstream interpretation of effect sizes in linear models6566## Evidence6768- [other] Log-transform the featuredata using LogTransform with base=exp(1) and zerotona=TRUE to handle zeros.: "Log-transform the featuredata using LogTransform with base=exp(1) and zerotona=TRUE to handle zeros."69- [other] A metabolomics data matrix in the featuredata format can be transformed using the LogTransform function.: "A metabolomics data matrix in the _featuredata_ format can be transformed using the following function. LogTransform <- function(featuredata, base=exp(1), saveoutput=FALSE,"70- [other] The following MissingValues() function can be used to replace missing values after log-transformation.: "The following `MissingValues()` function can be used to replace missing values, depending on the nature of missing data."71- [readme] Metabolomics data are subject to unwanted variation due to batch effects and matrix effects.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation."
HolobiomicsLab