nbinomWaldTest {DESeq2} | R Documentation |
This function tests for significance of coefficients in a
negative binomial GLM, using previously calculated
sizeFactors
(or
normalizationFactors
) and dispersion
estimates. See DESeq
for the GLM formula.
nbinomWaldTest(object, betaPrior = TRUE, betaPriorVar, modelMatrixType, maxit = 100, useOptim = TRUE, quiet = FALSE, useT = FALSE, df, useQR = TRUE, betaPriorUpperQuantile = 0.05)
object |
a DESeqDataSet |
betaPrior |
whether or not to put a zero-mean normal prior on the non-intercept coefficients (Tikhonov/ridge regularization) |
betaPriorVar |
a vector with length equal to the number of model terms including the intercept. betaPriorVar gives the variance of the prior on the sample betas on the log2 scale. if missing (default) this is estimated from the data |
modelMatrixType |
either "standard" or "expanded",
which describe how the model matrix, X of the formula in
|
maxit |
the maximum number of iterations to allow for convergence of the coefficient vector |
useOptim |
whether to use the native optim function on rows which do not converge within maxit |
quiet |
whether to print messages at each step |
useT |
whether to use a t-distribution as a null distribution, for significance testing of the Wald statistics. If FALSE, a standard normal null distribution is used. |
df |
the degrees of freedom for the t-distribution |
useQR |
whether to use the QR decomposition on the design matrix X while fitting the GLM |
betaPriorUpperQuantile |
the upper quantile to use for calculating the variance of the beta prior. by default the 0.05 upper quantile of the absolute value of the MLE betas is matched to the 0.025 upper quantile of a zero-centered normal. |
The fitting proceeds as follows: standard maximum likelihood estimates for GLM coefficients (synonymous with beta, log2 fold change) are calculated; a zero-mean normal prior distribution is assumed; the variance of the prior distribution for each non-intercept coefficient is calculated by matching the upper quantile of the MLE coefficients with a zero-centered normal distribution; the final coefficients are then maximum a posteriori estimates (using Tikhonov/ridge regularization) using this prior. The use of a prior has little effect on genes with high counts and helps to moderate the large spread in coefficients for genes with low counts.
For calculating Wald test p-values, the coefficients are scaled by their standard errors and then compared to a normal distribution. From examination of Wald statistics for real datasets, the effect of the prior on dispersion estimates results in a Wald statistic distribution which is approximately normal.
When a log2 fold change prior is used (betaPrior=TRUE),
then nbinomWaldTest
will by default use expanded
model matrices, as described in the modelMatrixType
argument, unless this argument is used to override the
default behavior or unless there the design contains 2
level factors and an interaction term. This ensures that
log2 fold changes will be independent of the choice of base
level. In this case, the beta prior variance for each
factor is calculated as the average of the mean squared
maximum likelihood estimates for each level and every
possible contrast. The results
function
without any arguments will automatically perform a contrast
of the last level of the last variable in the design
formula over the first level. The contrast
argument
of the results
function can be used to
generate other comparisons.
When interaction terms are present, the prior on log fold changes the calculated beta prior variance will only be used for the interaction terms (non-interaction log2 fold changes receive a prior variance of 1e3).
The Wald test can be replaced with the
nbinomLRT
for an alternative test of
significance.
a DESeqDataSet with results columns accessible with the
results
function. The coefficients and
standard errors are reported on a log2 scale.
dds <- makeExampleDESeqDataSet() dds <- estimateSizeFactors(dds) dds <- estimateDispersions(dds) dds <- nbinomWaldTest(dds) res <- results(dds)