weitrix_confects {weitrix} | R Documentation

## Top confident effects based on one or more contrasts of a linear model for each row

### Description

This 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.

### Usage

    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
    )

### Arguments

`weitrix` | A weitrix object, or an object that can be converted to a weitrix with `as_weitrix`.
`design` | A formula in terms of `colData(weitrix` or a design matrix, which will be fitted to the weitrix on each row. Can also be a pre-existing Components object, in which case the existing fits (`design$row`) are used.
`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.

### Details

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.

### Value

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.

### Examples

    # Simplest possible test
    # Which rows have an average different from zero?
    weitrix_confects(simwei, ~1, coef="(Intercept)")

    # See vignettes for more substantial examples

[Package weitrix version 1.6.0 Index]