estimateDispersionsGeneEst {DESeq2} | R Documentation

## Low-level functions to fit dispersion estimates

### Description

Normal users should instead use `estimateDispersions`. These low-level functions are called by `estimateDispersions`, but are exported and documented for non-standard usage. For instance, it is possible to replace fitted values with a custom fit and continue with the maximum a posteriori dispersion estimation, as demonstrated in the examples below.

### Usage

    estimateDispersionsGeneEst(
      object,
      minDisp = 1e-08,
      kappa_0 = 1,
      dispTol = 1e-06,
      maxit = 100,
      useCR = TRUE,
      weightThreshold = 0.01,
      quiet = FALSE,
      modelMatrix = NULL,
      niter = 1,
      linearMu = NULL,
      minmu = if (type == "glmGamPoi") 1e-06 else 0.5,
      alphaInit = NULL,
      type = c("DESeq2", "glmGamPoi")
    )

    estimateDispersionsFit(
      object,
      fitType = c("parametric", "local", "mean", "glmGamPoi"),
      minDisp = 1e-08,
      quiet = FALSE
    )

    estimateDispersionsMAP(
      object,
      outlierSD = 2,
      dispPriorVar,
      minDisp = 1e-08,
      kappa_0 = 1,
      dispTol = 1e-06,
      maxit = 100,
      useCR = TRUE,
      weightThreshold = 0.01,
      modelMatrix = NULL,
      type = c("DESeq2", "glmGamPoi"),
      quiet = FALSE
    )

    estimateDispersionsPriorVar(object, minDisp = 1e-08, modelMatrix = NULL)

### Arguments

`object` | a DESeqDataSet
`minDisp` | small value for the minimum dispersion, to allow for calculations in log scale, one order of magnitude above this value is used as a test for inclusion in mean-dispersion fitting
`kappa_0` | control parameter used in setting the initial proposal in backtracking search, higher kappa_0 results in larger steps
`dispTol` | control parameter to test for convergence of log dispersion, stop when increase in log posterior is less than dispTol
`maxit` | control parameter: maximum number of iterations to allow for convergence
`useCR` | whether to use Cox-Reid correction
`weightThreshold` | threshold for subsetting the design matrix and GLM weights for calculating the Cox-Reid correction
`quiet` | whether to print messages at each step
`modelMatrix` | for advanced use only, a substitute model matrix for gene-wise and MAP dispersion estimation
`niter` | number of times to iterate between estimation of means and estimation of dispersion
`linearMu` | estimate the expected counts matrix using a linear model, default is NULL, in which case a lienar model is used if the number of groups defined by the model matrix is equal to the number of columns of the model matrix
`minmu` | lower bound on the estimated count for fitting gene-wise dispersion
`alphaInit` | initial guess for the dispersion estimate, alpha
`type` | can either be "DESeq2" or "glmGamPoi". Specifies if the glmGamPoi package is used to calculate the dispersion. This can be significantly faster if there are many replicates with small counts.
`fitType` | either "parametric", "local", "mean", or "glmGamPoi" for the type of fitting of dispersions to the mean intensity. See `estimateDispersions` for description.
`outlierSD` | the number of standard deviations of log gene-wise estimates above the prior mean (fitted value), above which dispersion estimates will be labelled outliers. Outliers will keep their original value and not be shrunk using the prior.
`dispPriorVar` | the variance of the normal prior on the log dispersions. If not supplied, this is calculated as the difference between the mean squared residuals of gene-wise estimates to the fitted dispersion and the expected sampling variance of the log dispersion

### Value

a DESeqDataSet with gene-wise, fitted, or final MAP dispersion estimates in the metadata columns of the object.

`estimateDispersionsPriorVar` is called inside of `estimateDispersionsMAP` and stores the dispersion prior variance as an attribute of `dispersionFunction(dds)`, which can be manually provided to `estimateDispersionsMAP` for parallel execution.

### See Also

`estimateDispersions`

### Examples

    dds <- makeExampleDESeqDataSet()
    dds <- estimateSizeFactors(dds)
    dds <- estimateDispersionsGeneEst(dds)
    dds <- estimateDispersionsFit(dds)
    dds <- estimateDispersionsMAP(dds)
    plotDispEsts(dds)

    # after having run estimateDispersionsFit()
    # the dispersion prior variance over all genes
    # can be obtained like so:

    dispPriorVar <- estimateDispersionsPriorVar(dds)

[Package DESeq2 version 1.32.0 Index]