[Rd] ?mean

[Berwin A Turlach]

G'day Gabor,

On Thu, 25 Jan 2007 09:53:49 -0500
"Gabor Grothendieck" <ggrothendieck at gmail.com> wrote:

> The help page for mean does not say what happens when one
> applies mean to a matrix.

Well, not directly.  :-)

But the help page of mean says that one of the arguments is:

       x: An R object.  Currently there are methods for numeric data
          frames, numeric vectors and dates.  A complex vector is
          allowed for 'trim = 0', only.

And the `Value' section states:
 
     For a data frame, a named vector with the appropriate method being
     applied column by column.

     If 'trim' is zero (the default), the arithmetic mean of the values
     in 'x' is computed, as a numeric or complex vector of length one. 
     If any argument is not logical (coerced to numeric), integer,
     numeric or complex, 'NA' is returned, with a warning.

Since a matrix is a vector with a dimension attribute, and not a data
frame, one can deduce that the second paragraph describes the return
value for `mean(x)' when x is a matrix.

As I always tell my students, reading R help pages is a bit of an
art. :)

> mean and sd work in an inconsistent way on a matrix so that should at
> least be documented. 

Agreed.  But it is documented in the help page of sd, which clearly
states:

     [....] If 'x' is a matrix or a data frame, a vector
     of the standard deviation of the columns is returned.

I guess you also want to have it documented in the mean help page?  

But then, should `var' also be mentioned in the mean help page?  This
command also work in an a different and inconsistent manner to mean on
matrices.

And, of course, there are other subtle inconsistencies in the language
used in these help pages.  Note that the mean help page talks about
"numeric data frames" while the help pages of `var' and `se' talk about
"data frames" only, though all components of the data frame have to be
numeric, of course.

> Also there should be a See Also to colMeans since that provides the
> missing column-wise analog to sd.

That's probably a good idea.  What would you suggest should be
mentioned to provide the column-wise analog of `var'?

Cheers,

	Berwin