\name{varianceFitDiagnostics}
\Rdversion{1.1}
\alias{varianceFitDiagnostics}

\title{
   Generate a data frame with diagnostic information on the fit of a base variance function.
}
\description{
   After fitting base variance function with \code{\link{estimateVarianceFunctions}}, it is
   prudent to check the quality of the fit for all or at least a few conditions. This function
   produces a data frame with useful data for this purpose. 
}
\usage{
varianceFitDiagnostics(cds, cond)
}
\arguments{
  \item{cds}{
      a CountDataSet with base variance functions
}
  \item{cond}{
      the name of a condition
}
}
\value{
A data frame with these columns:
  \item{baseMean}{The base mean for the condition (see \code{\link{getBaseMeansAndVariances}} for details).}
  \item{baseVar}{The base variance for the condition as estimated from the counts of the respecive row only (see \code{\link{getBaseMeansAndVariances}} for details).}
  \item{fittedRawVar}{The raw variance as predicted by the raw variance function when given the baseMean.}
  \item{fittedBaseVar}{The base variance, found by adding the effective base-level shot noise to the raw variance.}
  \item{pchisq}{The cumulative chi-square probability of the residual. }
}
\note{
\itemize{
To check the fit, you might want to do one of the following:
\item Make a doubly-logarithmic scatter plot of baseVar against the baseMean and then add a line with the fittedBaseVar values. The line should follow the points.
\item Calculate the squared coefficient of variance (SCV), i.e., baseVar/baseMean^2. Make a scatter plot of the SCV against the (log of the) baseMean and then add a line of the fitted SCV. The line should follow the points. You can also plot 1/baseMean against baseMean as another line to see the shot noise.
\item The residuals, i.e., baseVar/fittedBaseVar, should follow a chi-square distribution with k degrees of freedom, after scaling by k (where k is the number of replicates minus 1). (See paper for details). The 'pchisq' column contains the cumulative probabilities (i.e., the result of 'pchisq') of the residuals, and these values
should be uniformly distributed. You can check this with a histogram, or more conveniently, with ECDF plot generated by the function \code{\link{residualsEcdfPlot}}.
}
}


\seealso{
\code{\link{residualsEcdfPlot}}
}
\author{
   Simon Anders, sanders@fs.tum.de
}
\examples{
cds <- makeExampleCountDataSet()
cds <- estimateSizeFactors( cds )
cds <- estimateVarianceFunctions( cds )
vfd <- varianceFitDiagnostics( cds, "A" )
head( vfd )
}