R devel - Feb 2008 - Suggestions for R-intro manual (PR#10701)

Some suggestions for R-intro:

--------------------------------------------------
Section 9.2.2, change:
(Note the function split() which produces a list of vectors obtained
by splitting a larger vector according to the classes specified by a
factor. This is a useful function, mostly used in connection with
boxplots. See the help facility for further details.)

    Warning: for() loops are used in R code much less often than in
    compiled languages. Code that takes a `whole object' view is
    likely to be both clearer and faster in R.

to:

    Warning: for() loops are used in R code much less often than in
    compiled languages. Code that takes a `whole object' view is
    likely to be both clearer and faster in R.

(Note the function split() which produces a list of vectors obtained
by splitting a larger vector according to the classes specified by a
factor.  It can also split data frames.  This is a useful function,
often used in combination with lapply to avoid for() loops.  See
help(split) and help(lapply) for further details.)

--------------------------------------------------
Section 10.1

The current twosam is for a pooled-variance t-statistic.
Give the unpooled version instead (for consistency with t.test,
and because it is better statistical practice).


Give initial comments in functions twosam:
# compute a two-sample t-statistic for the difference in means

and bslash:
# Compute least-squares regression coefficients (X'X)^{-}(X'y)


Add initial comments to later functions; even if they are not needed,
this sets a good example.

--------------------------------------------------
Section 11.1.1

This contains outdated information about contrasts in S-PLUS.
For version 8.0.4:
> options("contrasts")
$contrasts:
            factor      ordered 
 "contr.treatment" "contr.poly"

--------------------------------------------------
Section 11.3

In this text:
predict(object, newdata=data.frame)
    The data frame supplied must have variables specified with the
    same labels as the original. The value is a vector or matrix of
    predicted values corresponding to the

it is unclear what "labels" means - same variable names, or same
levels for factor variables.  Change
"variables specified with the same labels" to
"variables with the same names".

--------------------------------------------------
Section 11.6

There is a newer version of Dobson, 2002, second edition.

Dobson is referenced later, in Section 11.7.2.
I don't have the new copy, can't tell you new page numbers.

--------------------------------------------------
Section 12.1

Change
"High-level plotting commands always start a new plot, erasing the
current plot if necessary."
to
"High-level plotting commands start a new plot, erasing the current
plot if necessary.  This can be prevented using 'add=TRUE', see
section 12.1.4"
or
"High-level plotting commands start a new plot, erasing the current
plot if necessary."

--------------------------------------------------
Section 13.3

The last part of this sentence seems irrelevant to this section:
Packages can have namespaces, and currently all of the base and
recommended packages do expect the datasets package.

--------------------------------------------------
Appendix A

Preface comments with #.  I'm looking at the web
version of the manual, and there is nothing to distinguish
continuations of long commands from comments.
Using comments would also allow a user to paste a block
of code into R.

--------------------------------------------------

Tim Hesterberg


--please do not edit the information below--

Version:
 platform = i386-pc-mingw32
 arch = i386
 os = mingw32
 system = i386, mingw32
 status = 
 major = 2
 minor = 6.1
 year = 2007
 month = 11
 day = 26
 svn rev = 43537
 language = R
 version.string = R version 2.6.1 (2007-11-26)

Windows XP (build 2600) Service Pack 2.0

Locale:
LC_COLLATE=English_United States.1252;LC_CTYPE=English_United
States.1252;LC_MONETARY=English_United
States.1252;LC_NUMERIC=C;LC_TIME=English_United States.1252

Search Path:
 .GlobalEnv, package:stats, package:graphics, package:grDevices, package:utils,
package:datasets, package:methods, Autoloads, package:base