voomWithDuplicateCorrelation: Alternate 'limma::duplicateCorrelation()' and 'limma::voom()'...

In DarwinAwardWinner/rctutils: Utility functions by Ryan C. Thompson

Alternate limma::duplicateCorrelation() and limma::voom() until convergence

Description

This function runs limma::voom() and limma::duplicateCorrelation() repeatedly until two consecutive runs yield the same correlation value (within tol of each other), indicating that the iteration has converged.

Usage

voomWithDuplicateCorrelation(
  counts,
  design = NULL,
  plot = FALSE,
  block = NULL,
  trim = 0.15,
  voom.fun = voomWithOffset,
  dupCor.fun = limma::duplicateCorrelation,
  initial.correlation = 0,
  maxiter = 5,
  tol = 1e-06,
  verbose = TRUE,
  ...
)

Arguments

counts, design, plot, ...	These are passed to limma::voom().
block, trim	These are passed to limma::duplicateCorrelation().
voom.fun	Function to use in place of limma::voom(). For example, you could use limma::voomWithQualityWeights. Obvoiusly, this function should conform to the same interface as limma::voom(), accepting the same arguments and returning an EList.
dupCor.fun	Function to use in place of limma::duplicateCorrelation(). I don't currently know of any suitable values for this other than limma::duplicateCorrelation().
initial.correlation	Initial correlation value to use for the first run of limma::voom(). There is no need to set this value, but setting it to a reasonable guess might allow the iteration to converge sooner.
maxiter	Maximum number of iterations. If convergence has not been achieved after this many iterations, the final result will be returned with a warning.
tol	Convergence tolerance. If a run of limma::duplicateCorrelation() yeilds a correlation value within tol of the previous correlation value, the result is considered converged, and iteration is stopped.
verbose	If TRUE, give messages indicating the progress of the iteration.

Value

The EList object returned by the final iteration of limma::voom().

It has previously been recommended in the past to run voom and duplicateCorrelation twice each, with the implication that further iterations would see diminishing returns (see https://support.bioconductor.org/p/59700/#67620). However, rather than assume two iterations is always sufficient, this function instead keeps iterating until convergence is actually observed.

Note that I am not aware of any proof that iterating to convergence is guaranteed to produce a unique solution. The optimization may well be non-convex, in which case this naive algorithm could converge to a local optimum rather than a global one. Empirically, differences between successive runs get very small after the second run, so it seems stable in practice.

Examples

# TODO: Steal from voom/dupcor examples

DarwinAwardWinner/rctutils documentation built on July 22, 2022, 5:19 a.m.