[Rd] hist.default documentation

Deepayan Sarkar
Fri, 17 Jun 2005 12:58:01 -0000

I think there are a couple of things in ?hist that are not quite as
clear as they could be.

(1)

  freq: logical; if 'TRUE', the histogram graphic is a representation
          of frequencies, the 'counts' component of the result; if
          'FALSE', _relative_ frequencies ("probabilities"),
component
          'density', are plotted.   Defaults to 'TRUE' _iff_
'breaks'
          are equidistant (and 'probability' is not specified).

Unless I'm missing something, the 'density' component is NOT
relative
frequency or 'probability' in any reasonable sense, country-specific
biases notwithstanding, except in the very special case where
all(diff(breaks) == 1). Thus, the above description is confusing and
probably even wrong.

Also, it seems to me that hist cannot draw a relative frequency
histogram at all (which is not a bad thing, but it's of course very
important to the undergrads we're teaching intro stats and R to). This
should be explicitly mentioned.

(2)

  breaks: one of:

             ...
             *  a single number giving the number of cells for the
                histogram,
             ...

This is not quite true. 'breaks' is used in 'pretty', so
it's more a
suggestion than an exact specification. I'm not sure whether or not
the behaviour should be changed (what's the point of having
``pretty''
breakpoints anyway?), but if not, the documentation should be
clarified.

I'll be happy to provide a patch if these changes are considered reasonable.

Deepayan