[BioC] Limma Documentation: normalization functions

[Gordon Smyth]

Dear Paul,

At 04:38 AM 10/08/2003, Paul Boutros wrote:
> > -----Original Message-----
> > From: Gordon Smyth [mailto:smyth at wehi.edu.au]
> > Sent: Saturday, August 09, 2003 4:09 AM
> > To: Paul.Boutros at utoronto.ca
> > Cc: bioconductor at stat.math.ethz.ch
> > Subject: Re: [BioC] Limma Documentation: normalization functions
> >
> >
> > Dear Paul,
> >
> > At 05:24 AM 9/08/2003, Paul Boutros wrote:
> > >Hi all,
> > >
> > >I'm trying to get familiar with the limma package, but I've run into
> > >something
> > >I don't understand.  After I load the package, if I type:
> > >?normalizeWithinArrays
> > >The documentation doesn't give a list of available normalization methods.
> > >Instead it refers me to:
> > >"An overview of LIMMA functions for normalization is given in
> > >4.Normalization."
> >
> > I have reproduced below the first few paragraphs of the help
> > document that
> > one gets by typing ?normalizeWithinArrays. As you can see, documentation
> > for the argument "method" gives a list of available normalization
> > methods.
> > There are further details further down in the document under
> > "Details". The
> > line that you have quoted is the second last line of the help
> > document. It
> > would seem that you are only reading the last two lines of the document.

... help document deleted

>This is weird: I get totally different output.  I've appended mine below.
>Is this just a version issue, or is it something I should worry about?

Ah, I can see what is happening now. My apologies.

In the BioC Release 1.2 version of limma, which was limma 1.0.8, I wrote 
normalizeWithinArrays as a new-style generic function. That means that 
normalizeWithinArrays doesn't do anything itself, it just passes the 
information on to more specific functions called "Methods" which actually 
do the work, depending on the type of data which you input. What you were 
supposed to do was to see that normalizeWithinArrays accepts RGList objects 
and then type ?normalizeWithinArrays.RGList for the more detailed 
information. (Alternatively you could type 
helpMethods("normalizeWithinArrays") which would give you a menu of more 
detailed help pages, or else use the html contents help page for limma.) 
You are far from the only one who found this too obscure. I decided that 
there is no good way to write documentation for new-style generic functions 
within the R help system as it currently stands, so I have gone back to a 
programming style in the development version of limma which does not use 
the formal object-orientated programming system. This means that the 
documentation for functions like normalizeWithinArrays is now much more 
direct and you should find it more transparent.

I recommend that you get limma 1.1.10. An added advantage is that the 
normalization routines are now much faster and more robust. If you can't 
get it from the Bioconductor.org www site, then you can get it from 
http://bioinf.wehi.edu.au/limma/. If you have installation rights on your 
computer you may be able to type

   install.packages("limma",contriburl="http://bioinf.wehi.edu.au/limma")

in R to get automatic installation of the latest version.

Best wishes
Gordon

>------------------ Begin document ------------------------------
>normalizeWithinArrays         package:limma         R Documentation
>
>Normalize Within Arrays - generic
>
>Description:
>
>      A generic function which normalizes microarray data. Normalization
>      is intended to remove from the expression measures any systematic
>      trends which arise from the microarray technology rather than from
>      differences between the probes or between the target RNA samples
>      hybridized to the arrays.
>
>Usage:
>
>      normalizeWithinArrays(object,...)
>
>Arguments:
>
>   object: a data object containing microarray data
>
>      ...: any other arguments
>
>Methods:
>
>      Methods are defined in limma for `object' an object of class
>      `list', `RGList' or `MAList'.
>
>      Type `showMethods("normalizeBetweenArrays")' at the R prompt for a
>      complete list of classes for which methods are defined.
>
>Author(s):
>
>      Gordon Smyth
>
>See Also:
>
>      An overview of LIMMA functions for normalization is given in
>      4.Normalization.
>
>      See also `normalizeBetweenArrays' and `maNorm' in the marrayNorm
>      package.
>------------------ End document --------------------------------

... earlier correspondence deleted