\HeaderA{vsn2}{Fit the vsn model}{vsn2}
\aliasA{vsn2,ExpressionSet-method}{vsn2}{vsn2,ExpressionSet.Rdash.method}
\aliasA{vsn2,matrix-method}{vsn2}{vsn2,matrix.Rdash.method}
\aliasA{vsn2,numeric-method}{vsn2}{vsn2,numeric.Rdash.method}
\aliasA{vsn2-methods}{vsn2}{vsn2.Rdash.methods}
\aliasA{vsnMatrix}{vsn2}{vsnMatrix}
\begin{Description}\relax
\code{vsn2} fits the vsn model to the data matrix
in an \code{\LinkA{ExpressionSet}{ExpressionSet}} and
returns a \code{\LinkA{vsn}{vsn.Rdash.class}} object with the fit parameters and
the transformed data matrix.
The data matrix contains, typically, feature intensity readings from a
microarray. There are also \code{vsn2} methods for numeric matrices and vectors.
\code{\LinkA{predict}{predict}} applies a fitted model
to data and returns an \code{\LinkA{ExpressionSet}{ExpressionSet}} object.
\code{\LinkA{justvsn}{justvsn}} is a simple wrapper that 
takes and returns an \code{\LinkA{ExpressionSet}{ExpressionSet}}.
These are the main functions of this package. An overview is given in the vignette
\emph{Introduction to vsn}.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S4 method for signature 'ExpressionSet':
vsn2(x, reference, strata, ...)

vsnMatrix(x,
  reference,
  strata,
  lts.quantile = 0.9,
  subsample    = 0L,
  verbose      = interactive(),
  returnData   = TRUE,
  pstart,
  cvg.niter    = 5L,
  cvg.eps      = 5e-3)

## S4 method for signature 'matrix':
vsn2(x, reference, strata, ...)
## S4 method for signature 'numeric':
vsn2(x, reference, strata, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object containing the data to which the model is to be
fitted. Methods exists for \code{\LinkA{ExpressionSet}{ExpressionSet}},
\code{matrix} and \code{numeric}.
\item[\code{reference}] Optional, a \code{\LinkA{vsn}{vsn.Rdash.class}} object from
a previous fit. If this argument is specified, the data in \code{x}
are normalized "towards" an existing set of reference arrays whose
parameters are stored in the object \code{reference}. If this
argument is not specified, then the data in \code{x} are normalized
"among themselves". See Details for a more precise explanation.
\item[\code{strata}] Optional, a factor whose length is \code{nrow(x)}. Can
be used for stratified normalization (i.e. separate offsets \code{a} and
factors \code{b} for each level of \code{strata}). If missing, all
rows of \code{x} are assumed to come from one stratum.
\item[\code{lts.quantile}] Numeric of length 1. The quantile that is used for the resistant
least trimmed sum of squares regression. Allowed values are between
0.5 and 1. A value of 1 corresponds to ordinary least sum of squares
regression.
\item[\code{subsample}] Integer of length 1. If specified, the model parameters are
estimated from a subsample of the data of size \code{subsample}
only, yet the fitted transformation is
then applied to all data. For large datasets, this can substantially
reduce the CPU time and memory consumption at a negligible loss of precision.
\item[\code{verbose}] Logical. If TRUE, some messages are printed.
\item[\code{returnData}] Logical. If TRUE, the transformed data are returned
in a slot of the resulting \code{\LinkA{vsn}{vsn.Rdash.class}} object.
The option to set this option to \code{FALSE} allows saving of memory
if the data are not needed.
\item[\code{pstart}] Optional, array. Can be used to specify start values
for the iterative parameter estimation algorithm. See 
\code{\LinkA{vsn2trsf}{vsn2trsf}} for a description of the layout of the array.
\item[\code{cvg.niter}] Integer. The number of iterations to be used in the least
trimmed sum of squares regression.
\item[\code{cvg.eps}] Numeric. A convergence treshold.
\item[\code{...}] Arguments that get passed on to \code{vsnMatrix}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If the \code{reference} argument is \emph{not} specified, then the model
parameters $\mu_k$ and $\sigma$ are fit from the data in \code{x}.
This is the mode of operation described in the 2002 Bioinformatics
paper and that was the only option in versions 1.X of this package.
If \code{reference} is specified, the model parameters  $\mu_k$ and $\sigma$ are taken from
it. This allows for 'incremental' normalization. See the vignette
\emph{Likelihood Calculations for vsn}.
\end{Details}
\begin{Value}
An object of class \code{\LinkA{vsn}{vsn.Rdash.class}}.
The transformed data are on a glog scale to base 2. More precisely,
the transformed data are subject to the transformation
asinh(a+bx)/log(2)+c, where
$\mbox{asinh}(x)/log(2)=log_2(x+sqrt{x^2+1})$ is also called the 'glog', and
the constant c is an overall constant offset that is computed such that for
large x the transformation approximately corresponds to the
$\log_2$ function. The offset c is inconsequential for all differential expression
calculations, but many users like to see the data in a range that they
are familiar with.
\end{Value}
\begin{Author}\relax
Wolfgang Huber \url{http://www.ebi.ac.uk/huber}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{justvsn}{justvsn}}, \code{\LinkA{predict}{predict}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data("kidney")

fit = vsn2(kidney)                   ## fit
nkid = predict(fit, newdata=kidney)  ## apply fit

plot(exprs(nkid), pch=".")
abline(a=0, b=1, col="red")
\end{ExampleCode}
\end{Examples}

