From deepayan.sarkar at gmail.com  Fri Jun 17 14:58:01 2005
From: deepayan.sarkar at gmail.com (Deepayan Sarkar)
Date: Fri, 17 Jun 2005 07:58:01 -0500
Subject: [Rd] hist.default documentation
Message-ID: <eb555e660506170558193cf927@mail.gmail.com>

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



[Rd] hist.default documentation
Deepayan Sarkar