Implements a total-sum-scaling (TSS)-centered variant of the default
scale-uncertainty model described in Nixon et al. (Beyond Normalizations /
scale-uncertainty framework). Unlike clr.sm, which is centered
on the CLR-implied scale, this model is centered on the TSS assumption that
there is no systematic change in scale across.
tss.sm(X, logComp, gamma = 0.5)A numeric matrix of dimension N x nsample giving Monte Carlo
draws of the log2 scale for each sample (rows) across nsample draws
(columns).
A numeric design matrix passed internally by aldex() to the
scale model. Rows correspond to fixed-effect coefficients/covariates
(P = nrow(X)) and columns correspond to samples
(N = ncol(X)). (Automatically supplied by aldex().)
A numeric array of Monte Carlo log-compositions with
dimensions features x samples x nsample. This scale model uses
nsample (the number of Monte Carlo draws) but does not otherwise use
logComp. (Automatically supplied by aldex().)
Non-negative scalar. Standard deviation of the Gaussian
perturbation applied to the scale-model coefficients (in log2 space).
gamma = 0 implies no scale uncertainty (all draws are centered at
zero effect); larger values allow greater departures from the TSS-centered
assumption.
Justin Silverman
Scale uncertainty is introduced via an additive Gaussian perturbation on the
(log2) fixed effects. For each Monte Carlo draw, a coefficient vector is
sampled as \(b^{(m)} \sim N(0, \gamma^2 I)\), and the per-sample log2 scale
is computed as \(b^{(m)T} X\). Larger values of gamma correspond to
weaker confidence in the TSS-centered assumption (more allowed scale
variation); gamma = 0 yields no scale variation beyond the model
center.
Note: logComp is included to match the ALDEx3 scale-model interface
and to determine nsample, but it is not otherwise used by this model.
Nixon G, Gloor GB, Silverman JD (2025). "Incorporating scale uncertainty in microbiome and gene expression analysis as an extension of normalization". Genome Biology. tools:::Rd_expr_doi("10.1186/s13059-025-03609-3")