aldex: ALDEx3 Linear Models

In ALDEx3: Linear Models for Sequence Count Data

ALDEx3 Linear Models

Description

ALDEx3 Linear Models

Usage

aldex(
  Y,
  X,
  data = NULL,
  method = "lm",
  nsample = 2000,
  scale = NULL,
  streamsize = 8000,
  n.cores = detectCores() - 1,
  return.pars = c("X", "estimate", "std.error", "p.val", "p.val.adj", "logComp",
    "logScale"),
  p.adjust.method = "BH",
  test = "t.HC3",
  onesided = FALSE,
  ...
)

Arguments

Y	an (D x N) matrix of sequence count, N is number of samples, D is number of taxa or genes
X	either a formula (in which case DATA must be non-null) or a model matrix of dimension P x N (P is number of linear model covariates). If a formula is passed it should not include the target Y, e.g., should simply be "~condition-1" (note the lack of the left hand side). If using lme4, this should be the formula including random effects.
data	a data frame for use with formula, must have N rows
method	(default lm) The regression method; "lm": linear regression, "lme4": linear mixed effects regression with lme4; "nlme": linear mixed effects models with nlme, REQUIRES "random" argument representing random effects be passed into aldex function, can also pass "correlation" as argument (see nlme documentation for how to use "correlation" argument); or "blmm": an ALDEx3-specific approximate mixed-effects engine that uses one batched profiled mixed-model anchor fit per feature, draw-specific local covariance updates, and exact conditional fixed-effect solves. The approximation is only in the variance-component optimisation step. If the shared anchor optimisation fails or its Hessian is unusable, the whole feature falls back to exact lme4. Draw-specific updates that worsen the profiled objective fall back only for the affected draws. See the mixed-effects vignette for details, validation guidance, and the runtime comparison with exact lme4.
nsample	number of monte carlo replicates
scale	A scale-model function, such as clr.sm, tss.sm, sample.sm, or coefficient.sm; alternatively, an N x nsample matrix of log2-scale draws. Additional arguments for a scale-model function are passed through .... See "Writing a custom scale model" in the Examples section for the required interface.
streamsize	(default 8000) memory footprint (approximate) at which to use streaming. This should be thought of as the number of Mb for each streaming chunk. If DNnsample*8/1000000 is less than streamsize then no streaming will be performed. Note, to conserve memory, samples from the Dirichlet and scale models will not be returned if streaming is used. Streaming can be turned off by setting streamsize=Inf.
n.cores	(default detectCores()-1) If method is 'lme4' or 'blmm', use this many cores for feature-level parallelism across taxa/features. For method = "blmm", parallelism is across features, not across Monte Carlo draws within a feature.
return.pars	what results should be returned, see return section below.
p.adjust.method	(default BH) The method for multiple hypothesis test correction. See p.adjust for all available methods.
test	(default t.HC3), "t", t test is performed for each covariate (fast); "t.HC0" Heteroskedasticsity-Robust Standard Errors used (HC0; White's; slower); "t.HC3" (default) Heteroskedasticsity-Robust Standard Errors used (HC3; unlike HC0, this includes a leverage adjustment and is better for small sample sizes or when there are data with high leverage; slowest). To learn more about these, loko at Long and Ervin (2000) Using Heteroscedasticity Consistent Standard Errors in the Linear Regression Model, The American Statistician.
onesided	(default: FALSE) if sided return p-values for two-sided test. Otherwise if "lower" or "upper" return one-sided test corresponding to test that estimate is negative or positive respectively.
...	Additional scale-model arguments, such as gamma, s.mu, or c.mu. For method = "nlme", this may also include random or correlation.

Details

Sequence counts determine the relative composition of each sample, but not its total abundance or scale. The scale argument tells ALDEx3 what is known about that missing quantity and how uncertain that knowledge is.

Choose a scale model based on the information available:

• Use sample.sm for external measurements such as flow cytometry, qPCR, or spike-ins for individual samples.

• Use coefficient.sm when prior knowledge concerns a group difference, treatment effect, time trend, or another model term.

• Use clr.sm when CLR normalization is a reasonable center but its implied scale differences are uncertain.

• Use tss.sm when the starting assumption is no systematic scale difference between groups.

• Write a custom scale-model function when the built-in models do not match the information available for the study. The "Writing a custom scale model" example below describes the required function interface and N x nsample output.

Value

a list with elements controled by parameter resturn.pars. Options include: - X: P x N covariate matrix - estimate: (P x D x nsample) array of linear model estimates - std.error: (P x D x nsample) array of standard error for the estimates - p.val: (P x D) matrix, unadjusted p-value for two-sided t-test - p.val.adj: (P x D) matrix, p-value for two-sided t-test adjusted according to p.adj.method - logScale: (N x S) matrix, samples of the log scale from the scale model - logComp: (D x N x S) array, samples of the log composition from the multinomial-Dirichlet - streaming: boolean, detnote if streaming was used. - random.effects (Pr x N x S): if using mixed effects models, return all Pr random-effects covariance terms and the residual variance. For method = "blmm", correlated random-effect covariance terms are returned when present, matching the lme4 naming convention as closely as possible. Note, logScale and logComp are not returned if streaming is active.

Author(s)

Justin Silverman, Kyle McGovern

Examples

Y <- matrix(1:110, 10, 11)
condition <- c(rep(0, 5), rep(1, 6))
data <- data.frame(condition=condition)
## Use CLR as the center and allow coefficient-scale uncertainty of SD 0.5.
res <- aldex(Y, ~condition, data, nsample=2000, scale=clr.sm, gamma=0.5)

## Writing a custom scale model
## A custom model must return one log2-scale draw per sample and Monte
## Carlo replicate. Here, external_scale supplies a known value per sample.
known_scale <- function(X, logComp, external_scale) {
  nsample <- dim(logComp)[3]
  matrix(rep(external_scale, nsample), nrow=ncol(X), ncol=nsample)
}
res <- aldex(Y, ~condition, data, nsample=2000, scale=known_scale,
             external_scale=rep(0, ncol(Y)))

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