\HeaderA{normalizeByReference}{Probe-specific normalization of hybridization intensities from an oligonucleotide microarray}{normalizeByReference}
\keyword{manip}{normalizeByReference}
\begin{Description}\relax
Adjust the hybridization intensities from an oligonucleotide microarray
for probe-specific response effect by using one or several reference
hybridizations.
If \code{x} contains more than one array, \code{\LinkA{vsnMatrix}{vsnMatrix}} from
the \code{vsn} package is called for between array normalization.
\end{Description}
\begin{Usage}
\begin{verbatim}
normalizeByReference(x, reference, pm, background, refSig, nrStrata=10,
  cutoffQuantile=0.05, plotFileNames, verbose=FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] ExpressionSet containing the data to be normalized.
\item[\code{reference}] ExpressionSet with the same number of features as \code{x},
containing the reference signal, on the raw scale (non-logarithmic).
This argument can be used to directly input the data from a set of
replicate DNA hybridizations.
Alternatively, the argument \code{refSig} can be specified.
\item[\code{pm}] Indices specifying the perfect match features in
\code{reference} (see Details).
This can be either an integer vector with values between 1 and
\code{nrow(exprs(reference))} or a logical vector.
\item[\code{background}] Indices specifying a set of background features in
\code{x} (see Details).
This can be either an integer vector with values between 1 and
\code{nrow(exprs(x))} or a logical vector.
\item[\code{refSig}] A numeric vector of the same length as \code{pm} with
estimates of probe response effects, on a logarithm-like scale.
This argument can be specified alternatively to \code{reference}.
\item[\code{nrStrata}] Integer (length 1), number of strata for the estimation of
the background function.
\item[\code{cutoffQuantile}] Numeric (length 1), the probes whose reference
signal is below this quantile are thrown out.
\item[\code{plotFileNames}] Character vector whose length is the same as the
number of arrays in \code{x}. Optional, if missing, no plots are
produced.
\item[\code{verbose}] Logical of length 1, if \code{TRUE}, some messages about
progress are printed.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The intensities in \code{x} are adjusted according to the
reference values.
Typically, the reference values are obtained by hybridizing a DNA
sample to the array, so that the abundance of target is
the same for all reference probes, and their signal can be used to estimate
the probe sequence effect. A reference probe is a probe that
perfectly matches the target genome exactly once.
Usually, not all probes on a chip are reference
probes, hence the subset of those that are is specified by the
argument \code{pm}.

The background signal is estimated from the probes indicated by the
argument \code{background}. They need to be a strict subset of the
\code{reference} probes. I.e., they need to uniquely
match the target organism's DNA, but are not expected to match any of its transcripts. A
robust estimation method is used, so a small fraction of
\code{background} probes that do hit transcripts is not harmful.

A limitation of this normalization method is that it only makes sense
for the data from reference probes, NA values are returned for all other probes.

The functions \code{PMindex} and \code{BGindex} can be used to produce
the \code{pm} and \code{background} arguments from a \code{probeAnno}
environment such as provided in the davidTiling package.

To summarize, a reference probe (indicated by argument \code{pm}) is a
probe that perfectly matches the target genome exactly once, a
background probe (indicated by argument \code{background})
is a reference probe which we expect not to be transcribed. These
should not be confused with what is called 'perfect match' and
'mismatch' probes in Affymetrix annotation.
\end{Details}
\begin{Value}
A copy of \code{x} with the normalized intensities.
\end{Value}
\begin{Author}\relax
W. Huber \email{huber@ebi.ac.uk}
\end{Author}
\begin{References}\relax
Huber W, Toedling J, Steinmetz, L. Transcript mapping with high-density 
oligonucleotide tiling arrays. Bioinformatics 22, 1963-1970 (2006).
\end{References}
\begin{SeeAlso}\relax
\code{PMindex}, \code{BGindex}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## see vignette assessNorm.Rnw in inst/scripts directory
\end{ExampleCode}
\end{Examples}

