\name{getVarianceStabilizedData}
\Rdversion{1.1}
\alias{getVarianceStabilizedData}
\title{
   Perform a variance stabilising transformation (VST) on the count data
}
\description{
   This function calculates a variance stabilising transformations (VST) from the
   raw variance functions and then transforms the count data (after normalization
   by division by the size factor), yielding a matrix
   of values which are now approximately homoskedastic. This is useful as input 
   to statistical analyses requiring homoskedasticity. 
}
\usage{
getVarianceStabilizedData(cds)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{cds}{
      a CountDataSet with estimated variance functions
}
}
\details{
   For each sample (i.e., column of \code{counts(cds)}), the full variance function
   is calculated from the raw variance (by scaling according to the size factor and adding 
   the shot noise). The function always uses a pooled estimate of the variance function, i.e.,
   one ignoring conditions. The reciprocal of the square root of the base variance (i.e., the full variance
   divided by the size factor) is then numerically
   integrated up, and the integral (approximated by a spline function) evaluated for each
   count value in the column, yielding a transformed value.
   
   Note: This function calls internally \code{\link{estimateVarianceFunctions}} with \code{pooled=TRUE}
   and bases its calculations on the result. Any condition labels or variance adjustment factors
   are hence ignored.
   
   Limitations: In order to preserve normalization, the same transformation has to be used
   for all samples. This results in the variance stabilizition to be only approximate. The
   more the siza factors differ, the more residual dependence of the variance on the mean
   you will find in the transformed data. (Compare the variance of the upper half of your
   transformed data with the lower half to see whether this is a problem in your case.)
}
\value{
   A matrix of the same dimension as the count data, containing the transformed data.
}
\author{
   Simon Anders, sanders@fs.tum.de
}

\examples{
cds <- makeExampleCountDataSet()
cds <- estimateSizeFactors( cds )
cds <- estimateVarianceFunctions( cds )
vsd <- getVarianceStabilizedData( cds )
colsA <- conditions(cds) == "A"
plot( rank( rowMeans( vsd[,colsA] ) ), genefilter::rowVars( vsd[,colsA] ) )
}