[Rd] hist.default documentation

Duncan Murdoch
Fri, 17 Jun 2005 13:21:14 -0000

On 6/17/2005 8:58 AM, Deepayan Sarkar wrote:
> 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.

I agree.

> 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.

I'm not sure about this.  Is it really worth mentioning something if you
can't do it?  Are you thinking of just giving a reference to barplot?

> (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 like the pretty breakpoints. It is good to label the breakpoints, and
ugly to have labels at other than pretty points.  I'd clarify by
changing "giving" to "suggesting".

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

Please do.

Duncan Murdoch