arrayWeights {limma} | R Documentation

## Array Quality Weights

### Description

Estimate relative quality weights for each array or group in a multi-array experiment.

### Usage

    arrayWeights(object, design = NULL, weights = NULL,
         var.design = NULL, var.group = NULL, prior.n = 10,
         method = "auto", maxiter = 50, tol = 1e-5, trace = FALSE)

### Arguments

`object` | any matrix-like object containing log-expression values or log-ratio expression values, for example an `EList` or `ExpressionSet` object. See `help("getEAWP")` for a list of possible classes.
`design` | the design matrix of the microarray experiment, with rows corresponding to arrays and columns to coefficients to be estimated. Defaults to the unit vector meaning that the arrays are treated as replicates.
`weights` | numeric matrix containing prior weights for each expresson value.
`var.design` | design matrix for the variance model. Defaults to the sample-specific model whereby each sample has a distinct variance.
`var.group` | vector or factor indicating groups to have different array weights. This is another way to specify `var.design` for groupwise variance models.
`prior.n` | prior number of genes. Larger values squeeze the array weights more strongly towards equality.
`method` | character string specifying the estimating algorithm to be used. Choices are `"genebygene"`, `"reml"` or `"auto"`.
`maxiter` | maximum number of iterations allowed when `method="reml"`.
`tol` | convergence tolerance when `method="reml"`.
`trace` | logical. If `TRUE` then progress information is printed at each iteration of the `"reml"` algorithm or at every 1000th gene for the `"genebygene"` algorithm.

### Details

The relative reliability of each array is estimated by measuring how well the expression values for that array follow the linear model. Arrays that tend to have larger residuals are assigned lower weights.

The basic method is described by Ritchie et al (2006) and the extension to custom variance models by Liu et al (2015). A weighted linear model is fitted to the expression values for each gene. The variance model is fitted to the squared residuals from the linear model fit and is updated either by full REML scoring iterations (`method="reml"`) or using an efficient gene-by-gene update algorithm (`method="genebygene"`). The final estimates of these array variances are converted to weights. The gene-by-gene algorithm is described by Ritchie et al (2006) while the REML algorithm is an adaption of the algorithm of Smyth (2002).

For stability, the array weights are squeezed slightly towards equality. This is done by adding a prior likelihood corresponding to unit array weights equivalent to `prior.n` genes. The gene-by-gene algorithm is started from the prior genes while the REML algorithm adds the prior to the log-likelihood derivatives.

By default, `arrayWeights` chooses between the REML and gene-by-gene algorithms automatically (`method="auto"`). REML is chosen if there are no prior weights or missing values and otherwise the gene-by-gene algorithm is used.

The input `object` is interpreted as for `lmFit` and `getEAWP`. In particular, the arguments `design` and `weights` will be extracted from the data `object` if available and do not normally need to be set explicitly in the call; if any of these are set in the call then they will over-ride the slots or components in the data `object`.

### Value

A numeric vector of array weights, which multiply to 1.

### Author(s)

Matthew Ritchie and Gordon Smyth

### References

Liu, R., Holik, A. Z., Su, S., Jansz, N., Chen, K., Leong, H. S., Blewitt, M. E., Asselin-Labat, M.-L., Smyth, G. K., Ritchie, M. E. (2015). Why weight? Combining voom with estimates of sample quality improves power in RNA-seq analyses. Nucleic Acids Research 43, e97. http://nar.oxfordjournals.org/content/43/15/e97

Ritchie, M. E., Diyagama, D., Neilson, van Laar, R., J., Dobrovic, A., Holloway, A., and Smyth, G. K. (2006). Empirical array quality weights in the analysis of microarray data. BMC Bioinformatics 7, 261. http://www.biomedcentral.com/1471-2105/7/261

Smyth, G. K. (2002). An efficient algorithm for REML in heteroscedastic regression. Journal of Computational and Graphical Statistics 11, 836-847. http://www.statsci.org/smyth/pubs/remlalgo.pdf

### See Also

`arrayWeightsQuick`, `voomWithQualityWeights`

An overview of linear model functions in limma is given by 06.LinearModels.

### Examples

    ngenes <- 1000
    narrays <- 6
    y <- matrix(rnorm(ngenes*narrays), ngenes, narrays)
    var.group <- c(1,1,1,2,2,2)
    y[,var.group==1] <- 2*y[,var.group==1]
    arrayWeights(y, var.group=var.group)

[Package limma version 3.50.3 Index]