relative-log-abundance-calculation
Summary
Compute relative log abundances (RLA) from normalized metabolomics feature matrices by centering each metabolite's intensities on the median within sample groups, enabling detection of normalization artifacts and outlier samples. This diagnostic visualization reveals batch effects and within-group heterogeneity that persist after normalization.
When to use
After applying a normalization method (e.g., median scaling, RUV, RLSC) to metabolomics peak intensity data, when you need to visually assess whether normalization has successfully reduced batch effects and whether samples cluster appropriately by biological group. Use RlaPlots when you have a normalized featuredata matrix (samples × metabolites), grouping variables (batch or sample type), and want to identify samples with anomalous metabolite profiles relative to their group median.
When NOT to use
- Input featuredata is not yet normalized (apply a normalization method first, e.g., median scaling, RLSC, or RUV).
- groupdata contains fewer than 2 groups or has missing group assignments for any sample.
- Your goal is to identify differential abundance of individual metabolites across groups (use LinearModelFit or similar instead).
Inputs
- normalized featuredata matrix (samples × metabolites, numeric)
- groupdata vector (factor or character, length = number of samples)
- minoutlier threshold (numeric, default 0.5)
- plot type parameter ('ag' or 'wg')
Outputs
- interactive RLA plot object (Plotly widget, optional HTML file)
- non-interactive RLA plot (PNG, PDF, JPEG, TIFF, or BMP file)
- sample labels for outliers exceeding minoutlier threshold
How to apply
Load the normalized featuredata matrix (samples as rows, metabolites as columns) and a groupdata vector assigning each sample to a batch or experimental group. Call RlaPlots() with the matrix and groupdata, specifying type='ag' for across-group comparison (to assess batch homogeneity) or type='wg' for within-group comparison (to assess biological consistency). Set minoutlier threshold (default 0.5) to flag samples whose relative log abundance deviates beyond ±minoutlier log2 units from the group median; these labeled samples indicate potential outliers or normalization failures. Enable interactiveplot=TRUE to produce an interactive Plotly output or saveplot=TRUE with a non-interactive format (png, pdf, etc.) for publication. The plot centers each metabolite's relative abundances on zero per group, making it easy to visually detect batch-driven separation, skew, or high-variance samples.
Related tools
- NormalizeMets (R package housing RlaPlots() function and upstream normalization methods (NormScaling, NormQcmets, NormCombined) used to generate the input normalized matrix) — github.com/metabolomicstats/NormalizeMets
- R (execution environment for loading featuredata, groupdata, and calling RlaPlots())
- RStudio (recommended IDE for interactive development and parameter tuning of RlaPlots calls)
- Plotly (underlying graphics library for interactive visualization when interactiveplot=TRUE)
Examples
RlaPlots(featuredata=normalized_matrix, groupdata=batch_assignments, type='ag', minoutlier=0.5, interactiveplot=TRUE, saveinteractiveplot=TRUE, plotname='RLA_diagnostic')
Evaluation signals
- All samples are labeled with their sample IDs on the plot if they deviate >minoutlier log2 units from the group median for any metabolite; unlabeled samples have ≤minoutlier deviation.
- Samples within the same biological group cluster together horizontally (low variance around zero), indicating successful normalization; samples in different batches show distinct vertical separation or skew, indicating remaining batch effects.
- The plot's y-axis shows metabolite names and x-axis shows relative log abundance centered on zero; the plot is symmetric around the zero line if normalization is unbiased.
- Interactive plot renders as an HTML widget with hover tooltips showing sample ID, metabolite, and RLA value; non-interactive version has crisp labels and no missing/overlapping sample annotations.
- Output file (if saveplot=TRUE) is created in the specified format (png, pdf, etc.) with dimensions and resolution appropriate for publication.
Limitations
- RlaPlots assumes the input featuredata is already normalized; it diagnoses whether normalization was effective, not corrects raw data.
- High-dimensional data (many metabolites) may produce crowded plots with overlapping metabolite labels; interactive mode mitigates this via hover tooltips.
- minoutlier threshold is a visual aid; choosing too low a value flags many benign samples, while too high a value misses real outliers—no automated selection is provided.
- RlaPlots does not test statistical significance of outliers; it is a diagnostic visualization tool, not a hypothesis test.
- The function requires balanced or near-balanced group sizes; very imbalanced groups may produce unreliable group medians and median absolute deviations.
Evidence
- [other] The RlaPlots function accepts a normalized featuredata matrix, grouping variables, outlier threshold, plot type (across-group or within-group), and output parameters to generate relative log abundance plots for normalization assessment.: "The RlaPlots function accepts a normalized featuredata matrix, grouping variables, outlier threshold, plot type (across-group or within-group), and output parameters to generate relative log"
- [other] Call RlaPlots() with parameters: featuredata (normalized matrix), groupdata (grouping variable), type set to 'ag' (across-group) or 'wg' (within-group), minoutlier threshold (default 0.5), and interactiveplot=TRUE to enable interactive Plotly output.: "Call RlaPlots() with parameters: featuredata (normalized matrix), groupdata (grouping variable), type set to 'ag' (across-group) or 'wg' (within-group), minoutlier threshold (default 0.5), and"
- [other] Return both interactive and non-interactive plot objects showing metabolite relative log abundances centered on the median per group, with samples labeled when deviation exceeds minoutlier threshold.: "Return both interactive and non-interactive plot objects showing metabolite relative log abundances centered on the median per group, with samples labeled when deviation exceeds minoutlier threshold"
- [readme] Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation"
- [other] RlaPlots <- function(featuredata, groupdata, minoutlier = 0.5, type=c('ag', 'wg'), saveplot=FALSE, plotname = 'RLAPlot'...: "RlaPlots <- function(featuredata, groupdata, minoutlier = 0.5, type=c("ag", "wg"), saveplot=FALSE, plotname = "RLAPlot""
1---2name: relative-log-abundance-calculation3description: Use when after applying a normalization method (e.g., median scaling, RUV, RLSC) to metabolomics peak intensity data, when you need to visually assess whether normalization has successfully reduced batch effects and whether samples cluster appropriately by biological group.4license: CC-BY-4.05---67# relative-log-abundance-calculation89## Summary1011Compute relative log abundances (RLA) from normalized metabolomics feature matrices by centering each metabolite's intensities on the median within sample groups, enabling detection of normalization artifacts and outlier samples. This diagnostic visualization reveals batch effects and within-group heterogeneity that persist after normalization.1213## When to use1415After applying a normalization method (e.g., median scaling, RUV, RLSC) to metabolomics peak intensity data, when you need to visually assess whether normalization has successfully reduced batch effects and whether samples cluster appropriately by biological group. Use RlaPlots when you have a normalized featuredata matrix (samples × metabolites), grouping variables (batch or sample type), and want to identify samples with anomalous metabolite profiles relative to their group median.1617## When NOT to use1819- Input featuredata is not yet normalized (apply a normalization method first, e.g., median scaling, RLSC, or RUV).20- groupdata contains fewer than 2 groups or has missing group assignments for any sample.21- Your goal is to identify differential abundance of individual metabolites across groups (use LinearModelFit or similar instead).2223## Inputs2425- normalized featuredata matrix (samples × metabolites, numeric)26- groupdata vector (factor or character, length = number of samples)27- minoutlier threshold (numeric, default 0.5)28- plot type parameter ('ag' or 'wg')2930## Outputs3132- interactive RLA plot object (Plotly widget, optional HTML file)33- non-interactive RLA plot (PNG, PDF, JPEG, TIFF, or BMP file)34- sample labels for outliers exceeding minoutlier threshold3536## How to apply3738Load the normalized featuredata matrix (samples as rows, metabolites as columns) and a groupdata vector assigning each sample to a batch or experimental group. Call RlaPlots() with the matrix and groupdata, specifying type='ag' for across-group comparison (to assess batch homogeneity) or type='wg' for within-group comparison (to assess biological consistency). Set minoutlier threshold (default 0.5) to flag samples whose relative log abundance deviates beyond ±minoutlier log2 units from the group median; these labeled samples indicate potential outliers or normalization failures. Enable interactiveplot=TRUE to produce an interactive Plotly output or saveplot=TRUE with a non-interactive format (png, pdf, etc.) for publication. The plot centers each metabolite's relative abundances on zero per group, making it easy to visually detect batch-driven separation, skew, or high-variance samples.3940## Related tools4142- **NormalizeMets** (R package housing RlaPlots() function and upstream normalization methods (NormScaling, NormQcmets, NormCombined) used to generate the input normalized matrix) — github.com/metabolomicstats/NormalizeMets43- **R** (execution environment for loading featuredata, groupdata, and calling RlaPlots())44- **RStudio** (recommended IDE for interactive development and parameter tuning of RlaPlots calls)45- **Plotly** (underlying graphics library for interactive visualization when interactiveplot=TRUE)4647## Examples4849```50RlaPlots(featuredata=normalized_matrix, groupdata=batch_assignments, type='ag', minoutlier=0.5, interactiveplot=TRUE, saveinteractiveplot=TRUE, plotname='RLA_diagnostic')51```5253## Evaluation signals5455- All samples are labeled with their sample IDs on the plot if they deviate >minoutlier log2 units from the group median for any metabolite; unlabeled samples have ≤minoutlier deviation.56- Samples within the same biological group cluster together horizontally (low variance around zero), indicating successful normalization; samples in different batches show distinct vertical separation or skew, indicating remaining batch effects.57- The plot's y-axis shows metabolite names and x-axis shows relative log abundance centered on zero; the plot is symmetric around the zero line if normalization is unbiased.58- Interactive plot renders as an HTML widget with hover tooltips showing sample ID, metabolite, and RLA value; non-interactive version has crisp labels and no missing/overlapping sample annotations.59- Output file (if saveplot=TRUE) is created in the specified format (png, pdf, etc.) with dimensions and resolution appropriate for publication.6061## Limitations6263- RlaPlots assumes the input featuredata is already normalized; it diagnoses whether normalization was effective, not corrects raw data.64- High-dimensional data (many metabolites) may produce crowded plots with overlapping metabolite labels; interactive mode mitigates this via hover tooltips.65- minoutlier threshold is a visual aid; choosing too low a value flags many benign samples, while too high a value misses real outliers—no automated selection is provided.66- RlaPlots does not test statistical significance of outliers; it is a diagnostic visualization tool, not a hypothesis test.67- The function requires balanced or near-balanced group sizes; very imbalanced groups may produce unreliable group medians and median absolute deviations.6869## Evidence7071- [other] The RlaPlots function accepts a normalized featuredata matrix, grouping variables, outlier threshold, plot type (across-group or within-group), and output parameters to generate relative log abundance plots for normalization assessment.: "The RlaPlots function accepts a normalized featuredata matrix, grouping variables, outlier threshold, plot type (across-group or within-group), and output parameters to generate relative log"72- [other] Call RlaPlots() with parameters: featuredata (normalized matrix), groupdata (grouping variable), type set to 'ag' (across-group) or 'wg' (within-group), minoutlier threshold (default 0.5), and interactiveplot=TRUE to enable interactive Plotly output.: "Call RlaPlots() with parameters: featuredata (normalized matrix), groupdata (grouping variable), type set to 'ag' (across-group) or 'wg' (within-group), minoutlier threshold (default 0.5), and"73- [other] Return both interactive and non-interactive plot objects showing metabolite relative log abundances centered on the median per group, with samples labeled when deviation exceeds minoutlier threshold.: "Return both interactive and non-interactive plot objects showing metabolite relative log abundances centered on the median per group, with samples labeled when deviation exceeds minoutlier threshold"74- [readme] Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation.: "Metabolomics data are inevitably subject to a component of unwanted variation, due to factors such as batch effects, matrix effects, and confounding biological variation"75- [other] RlaPlots <- function(featuredata, groupdata, minoutlier = 0.5, type=c('ag', 'wg'), saveplot=FALSE, plotname = 'RLAPlot'...: "RlaPlots <- function(featuredata, groupdata, minoutlier = 0.5, type=c("ag", "wg"), saveplot=FALSE, plotname = "RLAPlot""
HolobiomicsLab