[6264] in s-news-athena
No subject found in mail header
daemon@ATHENA.MIT.EDU (Lyle Lofgren)
Thu Jan 26 14:43:22 1995
Date: Thu, 26 Jan 95 11:51:43 CST
From: lyle@rosevax.rosemount.com (Lyle Lofgren)
To: S-news@utstat.toronto.edu
On Jan 26, Stephen Barnett wrote:
>bshipley@courrier.usherb.ca (Bill Shipley) wrote:
>> It never occured to me that functions with names like "table" or "rle" would do
>> what I wanted. Is this problem with documentation of functions in S-PLUS
>> simply due to my lack of experience (stupidity?) or is this a general
>> problem.
>I think this is a good illustration of why one should just READ the
>manual. By reading I mean casual perusal with no specific problem in
>mind. You will find yourself saying things like "That looks useful!"
>or "Now, that's clever!". In the future, when you do actually have a
>problem that requires a function that's hard to find you will recall
>having seen it in passing and now where to find more info on it.
>This mimmicks the way we learn anything. As children we don't ask our
>parents what that thing on 4 wheels is called, we hear them call it a
>car and store this information away for future use.
My experience (about 26 years) of tearing my hair out trying to
understand anything written in unixspeak is that you have to find
someone to show you how to do it, because the manuals are not written
with humans in mind. The S-plus Reference Manual (Sept. 1991), which
is essentially the same as the on-line help reference, entry for TABLE
includes such things as:
DESCRIPTION: Returns a contingency table (array) with the same
number of dimensions as arguments given.
REQUIRED ARGUMENTS: ... any number of objects, each to be interpreted
as a category. All arguments must be of equal length. Together, they
define a multi-way ragged array of as many dimensions as there are
arguments. (etc.)
VALUE: a multi-way array containing the number of observations in
the cells defined by the arguments to the table. For example, if
z <- table(arg1,arg2,arg3)
then z[i,j,k] is the number of times that the combination of the
i-th level of the first category, the j-th level of the second, and
the k-th level of the third appeared together in the data. (etc.).
EXAMPLES:
contin <- table(age.x,sex.x,race.x,income.x)
names(dimnames(contin)) <-c("age","sex","race","income")
The problem is that, even having been pointed to one use for the
"table" function, the manual entry makes so little sense that I
won't be able to recognize other situations where "table" would
be useful. Yes, my parents talked about "car", and I could tell
what they were talking about. But in the above example, we have
"contingency", "array", "dimensions", "objects", "category",
"arguments", "multi-way", "ragged", "cells", and "levels." I
know what some of those things mean to S-plussers, and I don't
know what some of the other words mean. There's no S-plus dictionary
that I can use to find the meanings of those words in different
contexts. The Example is a joke, because it doesn't demonstrate anything.
If the manuals were fully comprehensible, there would be no point in having
a news group.
