coefficient.sm: Scale model using prior information about groups or...

In ALDEx3: Linear Models for Sequence Count Data

Scale model using prior information about groups or treatments

Description

Use this model when prior information describes a treatment, group, time, or other model coefficient rather than an individual sample. Samples with the same covariate values share the same scale shift in each Monte Carlo draw.

Usage

coefficient.sm(
  X,
  logComp,
  c.mu = NULL,
  c.cor = NULL,
  c.sd = NULL,
  c.cov = NULL
)

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(). This function uses the third dimension to determine the number of draws.
c.mu	Expected log2 scale change for each model coefficient, in the same order as the rows of X. Must have length P.
c.cor	Deprecated P x P covariance matrix for the fixed-effect coefficients. Use c.cov instead. Retained until ALDEx3 2.0.0.
c.sd	SD of the log2 scale change for each model coefficient. Must have length P; coefficients are treated as independent.
c.cov	A P x P covariance matrix for the model coefficients' log2 scale changes. Use this instead of c.sd when coefficient uncertainties are correlated.

Details

Suppose an effect plot from a control-versus-treatment experiment is centered near -8, even though prior knowledge suggests that most features should not change. One way to represent that knowledge is to shift the treatment samples upward by 8 log2 units relative to the controls. With control as the reference level, use c.mu = c(0, 8): the first value leaves the common intercept unchanged, and the second adds 8 to treatment. Setting c.sd = c(0, 0.5) expresses an SD of 0.5 around that treatment shift. If the plot were centered near +8, use -8 instead. Adding 8 to both groups would not recenter the plot because it would leave their difference unchanged.

More generally, c.mu gives the expected log2 scale change for each model coefficient and c.sd gives its SD. Use c.cov when the coefficient uncertainties are correlated. For each Monte Carlo draw, ALDEx3 samples a coefficient vector and applies it to the model matrix X; mathematically, b^{(m)} \sim N(c.mu, Sigma) and the sample scales are b^{(m)T} X.

Exactly one of c.sd or c.cov must be provided. The deprecated c.cor argument may be used in place of c.cov during the compatibility period.

Value

A numeric matrix of dimension N x nsample giving Monte Carlo draws of the log2 scale for each sample (rows) across nsample draws (columns).

Author(s)

Kyle McGovern

Examples

# Three control samples followed by three treatment samples.
condition <- factor(
  c("control", "control", "control", "treatment", "treatment", "treatment"),
  levels = c("control", "treatment")
)
X <- t(model.matrix(~ condition))
logComp <- array(0, c(2, 6, 10))
logScale <- coefficient.sm(
  # Shift treatment upward by 8, with SD 0.5 around that shift.
  X, logComp, c.mu = c(0, 8), c.sd = c(0, 0.5)
)

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