\Header{normalise}{Normalisation of Microarray Data}
\keyword{utilities}{normalise}
\begin{Description}\relax
An object of class \code{\Link{exprSetRG}} is generated
which contains the resulting normalised data.
\end{Description}
\begin{Usage}
\begin{verbatim}normalise(arrayDataObject, subtractBackground = FALSE, method = "vsn", subGroups = NULL, channelsSeparately = FALSE, hybridisationGroups, spotIdentifier, verbose = TRUE)\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{arrayDataObject}] object of class \code{\Link{arrayData}};
required; default missing.
\code{arrayDataObject} must contain the raw data, i.e.
a three dimensional array
(spot x channel x hybridisation),
cf. the class methods \code{\Link{getIntensities}}
and \code{\Link{intensities<\Rdash}},
and must contain information
on the hybridisations,
cf. class methods \code{\Link{getHybAttr}} and
\code{\{hybAttrList<-\}}.
If the argument \code{subGroups} (see below)
is specified it must also contain 
information on the spots, cf. the class methods
\code{\Link{getSpotAttr}} and
\code{\Link{spotAttr<\Rdash}}.
Note: Weights are only used by loess-type normalisations.

\item[\code{subtractBackground}] logical; default: \code{FALSE}
\item[\code{method}] character string; required; default: "\code{vsn}";
possible values:
"\code{none}", "\code{vsn}", "\code{quantile}",
"\code{loess}", "\code{loessScale}", "\code{loessQuantile}".
Note: "\code{quantile}" and  "\code{loess*}" normalisation
transforms the data to the (natural) logarithmic scale.
Note: Weights are only used by loess-type normalisations.
Note: "\code{loessScale}" and "\code{loessQuantile}" refer
to a loess normalisation followed by a
between slide normalisation, cf. the function
\code{normalizeBetweenArrays} of the
\code{limma} package.
Note: "\code{quantile}" and  "\code{loess*}" normalisations
do call the corresponding methods of the \code{limma} package
and "\code{vsn}" uses the \code{vsn} package.

\item[\code{subGroups}] character string or \code{NULL};
required; default: \code{NULL};
\code{subGroups} allows to define subgroups
of spots of each hybridisation
which are normalised separately like a 
print-tip normalisation.
The list must contain a column name refering to the
\code{data.frame} of \code{getSpotAttr(arrayDataObject)}.
In case of GenePix data you may for example
specify the column name "Block".
The column itself must contain integer values.
Note: In case of \code{method == "vsn"},
\code{vsn} is called with
the argument \code{strata}, which differs
to a separate normalisation of each subgroup
with \code{vsn} itself. 

\item[\code{channelsSeparately}] logical; required; default: \code{FALSE};
If \code{channelsSeparately} ist set to \code{TRUE}
each channel is normalised separately. Only meaningful
for single channel normalisation methods like
"\code{vsn}" and
"\code{quantile}" normalisation
but not for ratio based
normalisation like "\code{loess}".
\item[\code{hybridisationGroups}] list of vectors of indexes or
the character string "slideBySlide";
optional; default: missing.
Each group of hybridisations
is normalised separately. If
missing all hybridisations are
taken as one group. Only meaningful for
normalisation methods like "vsn" and "quantile".
The indexes must refer to the third
dimension of \code{getIntensities(arrayDataObject)}
and have to contain all hybridisations.

\item[\code{spotIdentifier}] character string; optional; default missing.
\code{spotIdentifier} specifies the column
of \code{getSpotAttr(arrayDataObject)} which must
contain non-unique spot or gene identifiers.
The identifiers are used as names for the
resulting \code{exprSetRG}-object; cf. the function
\code{geneNames} of the \code{exprSetRG-class}. 
\item[\code{verbose}] logical; required; default: \code{TRUE}
\end{ldescription}
\end{Arguments}
\begin{Value}
object of class \code{\Link{exprSetRG}}
\end{Value}
\begin{Author}\relax
Andreas Buness <a.buness@dkfz.de>
\end{Author}
\begin{SeeAlso}\relax
\code{\Link{exprSetRG-class}},
\code{\Link{processArrayData}},
\code{\Link{processArrayDataObject}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

       intensities <- array(data=runif(720),dim=c(120,2,3))
       dimnames(intensities) <- list(NULL, c("green","red"), NULL)
       hybAttr <- data.frame(Name=I(c("hx","hy","hz")), Index=c(1:3))
        arrayDataObject <- new("arrayData",
                              intensities=intensities,
                              hybAttrList=list(red=hybAttr,green=hybAttr)
                             )
       exprSetRGObject <- normalise(arrayDataObject = arrayDataObject,
                               subtractBackground = FALSE,
                               method = "none",
                               verbose = TRUE
                               )
       nRed <- exprs(getExprSetRed(exprSetRGObject))
       nGreen <- exprs(getExprSetGreen(exprSetRGObject))
       stopifnot( all.equal.numeric( nRed, intensities[,"red",] ) )
       stopifnot( all.equal.numeric( nGreen, intensities[,"green",] ) ) 

         
 \end{ExampleCode}
\end{Examples}

