[Rd] hist.default documentation
Deepayan Sarkar
deepayan.sarkar at gmail.com
Fri Jun 17 16:30:23 CEST 2005
On 6/17/05, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> 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?
Not mentioning it is fine.
> > (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".
Actually, I missed the remark just below this:
In the last three cases the number is a suggestion only.
so this is fine as it is.
> > I'll be happy to provide a patch if these changes are considered reasonable.
>
> Please do.
Here's the output of svn diff. Is this a reasonable way of providing a patch?
Index: hist.Rd
===================================================================
--- hist.Rd (revision 34748)
+++ hist.Rd (working copy)
@@ -28,9 +28,9 @@
}
\item{freq}{logical; if \code{TRUE}, the histogram graphic is a
representation of frequencies, the \code{counts} component of
- the result; if \code{FALSE}, \emph{relative} frequencies
- (\dQuote{probabilities}), component \code{density},
- are plotted. Defaults to \code{TRUE} \emph{iff} \code{breaks} are
+ the result; if \code{FALSE}, probability densities, component
+ \code{density}, are plotted (so that the histogram has a total area
+ of one). Defaults to \code{TRUE} \emph{iff} \code{breaks} are
equidistant (and \code{probability} is not specified).}
\item{probability}{an \emph{alias} for \code{!freq}, for S compatibility.}
\item{include.lowest}{logical; if \code{TRUE}, an \code{x[i]} equal to
Deepayan
More information about the R-devel
mailing list