1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/core.R
\name{estimateDispersionsGeneEst}
\alias{estimateDispersionsGeneEst}
\alias{estimateDispersionsFit}
\alias{estimateDispersionsMAP}
\alias{estimateDispersionsPriorVar}
\title{Low-level functions to fit dispersion estimates}
\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{
\item{object}{a DESeqDataSet}
\item{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}
\item{kappa_0}{control parameter used in setting the initial proposal
in backtracking search, higher kappa_0 results in larger steps}
\item{dispTol}{control parameter to test for convergence of log dispersion,
stop when increase in log posterior is less than dispTol}
\item{maxit}{control parameter: maximum number of iterations to allow for convergence}
\item{useCR}{whether to use Cox-Reid correction}
\item{weightThreshold}{threshold for subsetting the design matrix and GLM weights
for calculating the Cox-Reid correction}
\item{quiet}{whether to print messages at each step}
\item{modelMatrix}{for advanced use only,
a substitute model matrix for gene-wise and MAP dispersion estimation}
\item{niter}{number of times to iterate between estimation of means and
estimation of dispersion}
\item{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}
\item{minmu}{lower bound on the estimated count for fitting gene-wise dispersion}
\item{alphaInit}{initial guess for the dispersion estimate, alpha}
\item{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.}
\item{fitType}{either "parametric", "local", "mean", or "glmGamPoi"
for the type of fitting of dispersions to the mean intensity.
See \code{\link{estimateDispersions}} for description.}
\item{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.}
\item{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.
\code{estimateDispersionsPriorVar} is called inside of \code{estimateDispersionsMAP}
and stores the dispersion prior variance as an attribute of
\code{dispersionFunction(dds)}, which can be manually provided to
\code{estimateDispersionsMAP} for parallel execution.
}
\description{
Normal users should instead use \code{\link{estimateDispersions}}.
These low-level functions are called by \code{\link{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.
}
\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)
}
\seealso{
\code{\link{estimateDispersions}}
}
|
