weitrix_confects.RdThis function provides topconfects-style testing of a linear model contrast, as well as a multi-contrast extension of this method for F-tests with effect sizes.
weitrix_confects( weitrix, design, coef = NULL, contrasts = NULL, effect = c("auto", "contrast", "sd", "cohen_f"), dispersion_est = c("ebayes_limma", "row", "none"), fdr = 0.05, step = NULL, full = FALSE )
| weitrix | A weitrix object, or an object that can be converted to a weitrix
with |
|---|---|
| design | A formula in terms of |
| coef | Give either coef or contrasts but not both. If coef is given, it is converted into a set of contrasts that simply test each given coefficient. Coefficients can be specified by number of name. |
| contrasts | Give either coef or contrasts but not both. One or more contrasts of interest, i.e. specifications of linear combination of coefficients. Each contrast should be placed in a columns. The number of rows should match the number of coefficients. |
| effect | Effect to estimate and provide confidence bounds on. See description. |
| dispersion_est | Method of estimating per-row dispersion. See description. |
| fdr | False Discovery Rate to control for. |
| step | Granularity of effect sizes to test. |
| full | If TRUE, output some further columns related to the calculations. |
A topconfects result. The $table data frame contains columns:
effect Estimated effect (as requested using the effect parameter).
confect An inner confidence bound on effect.
fdr_zero FDR-adjusted p-value for the null hypothesis that effect is zero.
row_mean Weighted row mean.
typical_obs_err Typical residual standard deviation (square root of variance) associated with observations in this row. Note that each observation has its own associated variance, based on its weight and the row dispersion estimate used. This column is calculated from the weighted average variance of observations.
Based on the effect argument, the estimated effect may be:
"auto" Choose "contrast" or "sd" as appropriate.
"contrast" The estimated contrast. This should produce results identical to a limma-topconfects analysis.
"sd" Standard deviation explained (i.e. square root of the variance explained) by the part of the model captured by the contrasts provided.
"cohen_f" Cohen's f, i.e. the signal to noise ratio. Ranking is similar to traditional ranking of results by p-value.
Based on the dispersion_est argument, the estimated residual dispersion is estimated as:
"none" Weitrix is assumed to be fully calibrated already. Dispersion is assumed to be 1. If the assumption is correct, this is most powerful, as there is no uncertainty to the dispersion.
"row" Dispersion is estimated based on the residuals for each row. With a limited number of columns, this estimate is uncertain (low residual degrees of freedom), so may lack power.
"ebayes_limma" Default, recommended. Perform Empricial Bayes squeezing of dispersions, using limma::squeezeVar. This also reduces the uncertainty about the dispersion (mainfesting as extra "prior" degrees of freedom), increasing the power of the test.
In results from this function, whenever we talk about the mean, standard deviation explained, or typical observation error, this should be understood to be weighted. Standard deviation explained is in the same units as the observations, but its estimation is weighted by the weights, so in a row with some high weight observations and other low weight observations, estimated standard deviation explained will mostly be driven by the high weight observations.
# Simplest possible test # Which rows have an average different from zero? weitrix_confects(simwei, ~1, coef="(Intercept)")#> $table #> confect effect se df fdr_zero row_mean typical_obs_err name #> 1 1.651 3.249145 0.6023 8.715 0.001323 3.249145 1.2046 7 #> 2 -1.651 -3.178220 0.5942 9.715 0.001323 -3.178220 1.3287 5 #> 3 -1.624 -2.949244 0.5590 8.715 0.001323 -2.949244 1.1180 1 #> 4 0.798 2.440758 0.7549 9.715 0.016286 2.440758 1.6880 3 #> 5 NA -0.233750 0.4467 9.715 0.857530 -0.233750 0.9989 4 #> 6 NA 0.042831 0.3617 9.715 0.988203 0.042831 0.8088 6 #> 7 NA 0.006796 0.4480 9.715 0.988203 0.006796 1.0017 2 #> 4 of 7 non-zero contrast at FDR 0.05 #> Prior df 5.7# See vignettes for more substantial examples