clr.sm: CLR-based scale model

In ALDEx3: Linear Models for Sequence Count Data

CLR-based scale model

Description

Use this model when centered log-ratio (CLR) normalization is a reasonable starting point, but you do not want to assume that it recovers the sample scales exactly. For example, in a case-control study, CLR may provide a plausible center while gamma allows the true difference in total abundance between cases and controls to depart from that center.

Usage

clr.sm(X, logComp, gamma = 0.5)

Arguments

X	Model matrix passed automatically by aldex(). Rows are model coefficients and columns are samples.
logComp	Monte Carlo log-compositions passed automatically by aldex(), with dimensions features x samples x nsample.
gamma	Non-negative scalar. Standard deviation of the Gaussian random shift that relaxes the CLR assumption about scale. gamma = 0 yields the fixed CLR assumption. Larger values express less confidence in the CLR-implied differences between sample scales.

Details

Set gamma = 0 to use the CLR-implied scales without additional uncertainty. A value such as gamma = 0.5 allows each scale-model coefficient to vary with SD 0.5 on the log2 scale. Larger values express less confidence in the CLR assumption.

The uncertainty applies to model coefficients, not independently to every sample. Samples with the same covariate values therefore receive the same random shift in a Monte Carlo draw. This differs from sample.sm, which can draw a separate scale for each sample.

Value

A numeric matrix of dimension N x nsample giving Monte Carlo samples of the log-scale for each sample (rows) and each Monte Carlo draw (columns).

Author(s)

Justin Silverman

References

Nixon G, Gloor GB, Silverman JD (2025). "Incorporating scale uncertainty in microbiome and gene expression analysis as an extension of normalization". Genome Biology. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1186/s13059-025-03609-3")}

Examples

# Allow moderate uncertainty around CLR-implied scale differences.
Y <- matrix(seq_len(60), nrow = 10)
condition <- factor(c("control", "control", "control",
                      "case", "case", "case"))
fit <- aldex(Y, ~ condition, data.frame(condition), nsample = 20,
             scale = clr.sm, gamma = 0.5)

ALDEx3 documentation built on Oct. 20, 2026, 1:07 a.m.