Package {winn}

winn: White Noise Normalization for Metabolomics

Description

The winn package provides a transparent, stepwise workflow for correcting technical artifacts in LC-MS and GC-MS metabolomics data. WINN is designed for real study data that exhibit drift, batch effects, dilution variability, and occasional outliers. Each correction step can be used independently or combined in the full workflow via winn().

Details

Core steps in the WINN pipeline:

1. Robust outlier adjustment (MAD-based)

2. Drift correction by run order with a white-noise gatekeeper

3. Batch correction (ANOVA mean-shift or ComBat)

4. Median or PQN normalization for dilution effects

5. Optional per-batch scaling

If batch labels are not provided, WINN can automatically detect batch segments using an fkPELT change-point method on the median sample signal. If pooled QC samples are provided, WINN can automatically tune several parameters to maximize QC consistency.

Data format

WINN expects a metabolites-by-samples matrix. Run order, batch annotations, and QC index vectors should all align with ncol(data). The full pipeline requires finite, non-negative quantitative intensities. Numeric zeros are treated as observed and are never silently converted to missing values.

Dependencies

• mgcv for spline-based drift detrending

• lmtest for the Durbin-Watson autocorrelation test

• sva (optional) for ComBat batch correction

Recommended usage

• Provide batch and run_order whenever possible.

• Use QC samples and parameters = "auto" for robust tuning.

• Inspect QC CV and correlation before and after correction.

Author(s)

Maintainer: Tanmay Tanna tanmay@tanmaytanna.com [copyright holder]

Authors:

• Tanmay Tanna tanmay@tanmaytanna.com [copyright holder]

See Also

Useful links:

• https://github.com/ratschlab/winn

• Report bugs at https://github.com/ratschlab/winn/issues

Adjust Outliers in Data Matrix Using MAD

Description

This function adjusts outliers in a data matrix on a per-metabolite basis using the median absolute deviation (MAD). For each metabolite, the median, MAD, thresholds, and upper/lower outlier masks are computed once from the original finite values. Upper- and lower-tail values are then shrunk independently in one non-iterative pass; adjusting one tail cannot change the threshold or membership of the other tail. Non-finite values are not eligible for threshold estimation and are returned unchanged by this standalone helper. The full winn() pipeline instead requires finite, non-negative input. Numeric zeros are treated as observed values and are never automatically converted to missing values.

Usage

adjust_outliers_mad(data)

Arguments

Value

A numeric matrix with adjusted outliers.

Examples

set.seed(1)
your_data_matrix <- matrix(rnorm(200, mean = 100, sd = 15), nrow = 20)
adjusted_data <- adjust_outliers_mad(your_data_matrix)

Perform ANOVA-based Mean-Only Batch Correction

Description

This function runs an ANOVA test on each metabolite to detect batch effects, and then corrects significant batch effects by subtracting the estimated batch-specific shifts (while preserving the overall mean). With the default selective gate, features that do not pass the FDR threshold are unchanged; this differs from combat_batch_correction(), which applies an empirical Bayes location/scale model to every feature.

Usage

anova_batch_correction(
  data,
  batch,
  fdr_threshold = 0.05,
  gate = c("selective", "all", "none"),
  return_diagnostics = FALSE
)

Arguments

Value

A numeric matrix of corrected intensities, or a list containing the matrix and diagnostics when return_diagnostics = TRUE.

Examples

set.seed(1)
mat <- matrix(rnorm(200, mean = 100, sd = 15), nrow=20)
batch <- rep(1:4, length.out=ncol(mat))
corrected <- anova_batch_correction(mat, batch, fdr_threshold=0.05)

Correct for Drift in Data Using Autocorrelation Correction

Description

This function corrects for drift effects in metabolomics data by detrending based on run order within each batch segment. When run_order is supplied, every segment is sorted by that vector for both testing and smoothing, and the corrected values are then restored to the original matrix-column order.

Usage

autocorrelation_correct(
  data,
  run_order = NULL,
  batch,
  lag = NULL,
  test = "Ljung-Box",
  ljung_box_fitdf = 0L,
  detrend = "mean",
  fdr_threshold = 0.05,
  spline_method = "conservative",
  gate = NULL,
  return_diagnostics = FALSE
)

Arguments

Value

A numeric matrix with drift corrected, or a list containing the matrix and diagnostics when return_diagnostics = TRUE.

Examples

set.seed(1)
your_data_matrix <- matrix(rnorm(200, mean = 100, sd = 15), nrow = 20)
batch <- rep(1:4, length.out = ncol(your_data_matrix))
run_order <- seq_len(ncol(your_data_matrix))
drift_corrected <- autocorrelation_correct(your_data_matrix, run_order, batch)

Perform ComBat Batch Correction by batch

Description

This function applies the empirical Bayes ComBat method to correct batch effects by batch, adjusting both location and scale parameters across batch. Unlike the default selective ANOVA gate in anova_batch_correction(), ComBat is a global correction: every feature is passed to the empirical Bayes model.

Usage

combat_batch_correction(
  data,
  batch,
  par_prior = TRUE,
  mean_only = FALSE,
  ref_batch = NULL
)

Arguments

Value

A numeric matrix of corrected intensities.

Examples

# Loading the optional Bioconductor dependency can take more than five seconds.
if (requireNamespace("sva", quietly = TRUE)) {
  set.seed(1)
  mat <- matrix(rnorm(200, mean = 100, sd = 15), nrow=20)
  batch <- rep(1:4, length.out=ncol(mat))
  corrected <- combat_batch_correction(mat, batch, par_prior = TRUE)
}

Normalize Data Matrix by Dilution Factor

Description

This function normalizes a data matrix by dilution factors or alternatively shrinks sample measurements if any samples have dilution factors that are more than one standard deviation away from the mean dilution factor. Numeric zeros remain observed values. Features whose reference median is zero are omitted from quotient fitting, but retained when the estimated sample factors are applied. A sample with a non-positive dilution factor is rejected.

Usage

normalize_by_dilution_factor(
  data,
  processing = "shrink",
  control_samples = NULL,
  return_diagnostics = FALSE
)

Arguments

Value

A numeric matrix of normalized intensities, or a list containing the matrix and diagnostics when return_diagnostics = TRUE.

Examples

# Example usage:
set.seed(1)
your_data_matrix <- matrix(rnorm(200, mean = 100, sd = 15), nrow = 20)
normalized_data <- normalize_by_dilution_factor(your_data_matrix, control_samples = 1:4)

Scale Data by batch

Description

This function scales the values for each metabolite within each batch by subtracting the batch mean and dividing by the batch standard deviation.

Usage

scale_by_batch(data, batch)

Arguments

Value

A numeric matrix of scaled intensities.

Examples

set.seed(1)
your_data_matrix <- matrix(rnorm(200, mean = 100, sd = 15), nrow = 20)
batch <- rep(1:4, length.out = ncol(your_data_matrix))
scaled_data <- scale_by_batch(your_data_matrix, batch)

Winn Correction for Metabolomics Data

Description

This function performs a series of corrections on metabolomics data to adjust for dilution effects, outliers, drift, and batch effects. If batch information is not supplied, segments are automatically detected using an fkPELT-based approach and labeled as batch.

Usage

winn(
  data,
  batch = NULL,
  run_order = NULL,
  control_samples = NULL,
  parameters = "fixed",
  fdr_threshold = 0.05,
  median_adjustment = "shrink",
  detrend_non_autocorrelated = "mean",
  spline_method = "conservative",
  remove_batch_effects = "anova",
  test = "Ljung-Box",
  lag = NULL,
  ljung_box_fitdf = 0L,
  scale_by_batch = FALSE,
  pelt_penalty = NULL,
  return_details = FALSE
)

Arguments

Details

The correction pipeline is as follows:

1. Outlier adjustment using MAD.

2. Drift correction using autocorrelation-based detrending.

3. Batch effect correction using ANOVA-based mean-adjustment or ComBat.

4. Per-sample median adjustment using dilution factor.

5. Optional scaling by batch.

When control samples are provided and parameters="auto", the function performs comprehensive parameter optimization by testing multiple combinations of settings and selecting those that maximize control sample correlation while minimizing coefficient of variation. This searches spline methods, FDR thresholds, and normalization approaches while respecting the supplied autocorrelation-test family and scale_by_batch setting. Auto mode requires at least two controls. In auto mode, fdr_threshold, spline_method, and median_adjustment are fixed-mode settings and are replaced by the documented internal candidate grids. Other arguments still constrain the candidate family. Set return_details = TRUE to retain the selected settings and stage decisions in machine-readable form.

The full pipeline expects finite, non-negative quantitative intensities. Zeros are treated as observed values and are not converted to missingness. Users should recode declared non-detection sentinels and impute missing values using a documented preprocessing policy before calling winn().

Value

A numeric matrix of corrected intensities, or a structured winn_result when return_details = TRUE.

Examples

set.seed(1)
your_data_matrix <- matrix(rnorm(200, mean = 100, sd = 15), nrow = 20)
batch <- rep(1:4, length.out = ncol(your_data_matrix))
run_order <- seq_len(ncol(your_data_matrix))
corrected_data <- winn(your_data_matrix, batch = batch, run_order = run_order)

Run WiNN as Explicit Ablation Stages

Description

A thin, fixed-parameter orchestration layer around the package's existing outlier, drift, batch, and dilution-factor functions. It is intended for controlled mechanistic ablations and returns every intermediate matrix and gate diagnostic without changing the standard winn() API.

Usage

winn_ablation(
  data,
  batch,
  run_order = NULL,
  control_samples = NULL,
  parameters = "fixed",
  use_outlier_shrinkage = TRUE,
  drift_gate = c("selective", "none", "all"),
  batch_gate = c("selective", "none", "all"),
  pqn_mode = c("shrink", "none"),
  fdr_threshold = 0.05,
  test = "Ljung-Box",
  lag = NULL,
  ljung_box_fitdf = 0L,
  spline_method = "conservative",
  return_intermediates = TRUE,
  return_diagnostics = TRUE
)

Arguments

Value

A list containing the final matrix, intermediate matrices, diagnostics, stage runtimes, and the exact fixed configuration.

Examples

set.seed(1)
example_data <- matrix(abs(rnorm(120, mean = 100, sd = 15)), nrow = 10)
example_batch <- rep(1:3, each = 4)
example_result <- winn_ablation(
  example_data,
  batch = example_batch,
  run_order = seq_len(ncol(example_data)),
  drift_gate = "none",
  batch_gate = "none",
  pqn_mode = "none"
)
dim(example_result$data)