The R Project SVN R

START-INFO-DIR-ENTRY

* R FAQ: (R-FAQ).               The R statistical system FAQ.

END-INFO-DIR-ENTRY

   R FAQ

Frequently Asked Questions on R

Version 1.8-42, 2004-02-19

ISBN 3-900051-01-1

Kurt Hornik

Table of Contents

*****************

R FAQ

1 Introduction

  1.1 Legalese

  1.2 Obtaining this document

  1.3 Citing this document

  1.4 Notation

  1.5 Feedback

2 R Basics

  2.1 What is R?

  2.2 What machines does R run on?

  2.3 What is the current version of R?

  2.4 How can R be obtained?

  2.5 How can R be installed?

    2.5.1 How can R be installed (Unix)

    2.5.2 How can R be installed (Windows)

    2.5.3 How can R be installed (Macintosh)

  2.6 Are there Unix binaries for R?

  2.7 What documentation exists for R?

  2.8 Citing R

  2.9 What mailing lists exist for R?

  2.10 What is CRAN?

  2.11 Can I use R for commercial purposes?

  2.12 Why is R named R?

3 R and S

  3.1 What is S?

  3.2 What is S-PLUS?

  3.3 What are the differences between R and S?

    3.3.1 Lexical scoping

    3.3.2 Models

    3.3.3 Others

  3.4 Is there anything R can do that S-PLUS cannot?

  3.5 What is R-plus?

4 R Web Interfaces

5 R Add-On Packages

  5.1 Which add-on packages exist for R?

    5.1.1 Add-on packages in R

    5.1.2 Add-on packages from CRAN

    5.1.3 Add-on packages from Omegahat

    5.1.4 Add-on packages from BioConductor

    5.1.5 Other add-on packages

  5.2 How can add-on packages be installed?

  5.3 How can add-on packages be used?

  5.4 How can add-on packages be removed?

  5.5 How can I create an R package?

  5.6 How can I contribute to R?

6 R and Emacs

  6.1 Is there Emacs support for R?

  6.2 Should I run R from within Emacs?

  6.3 Debugging R from within Emacs

7 R Miscellanea

  7.1 Why does R run out of memory?

  7.2 Why does sourcing a correct file fail?

  7.3 How can I set components of a list to NULL?

  7.4 How can I save my workspace?

  7.5 How can I clean up my workspace?

  7.6 How can I get eval() and D() to work?

  7.7 Why do my matrices lose dimensions?

  7.8 How does autoloading work?

  7.9 How should I set options?

  7.10 How do file names work in Windows?

  7.11 Why does plotting give a color allocation error?

  7.12 How do I convert factors to numeric?

  7.13 Are Trellis displays implemented in R?

  7.14 What are the enclosing and parent environments?

  7.15 How can I substitute into a plot label?

  7.16 What are valid names?

  7.17 Are GAMs implemented in R?

  7.18 Why is the output not printed when I source() a file?

  7.19 Why does outer() behave strangely with my function?

  7.20 Why does the output from anova() depend on the order of factors in the model?

  7.21 How do I produce PNG graphics in batch mode?

  7.22 How can I get command line editing to work?

  7.23 How can I turn a string into a variable?

  7.24 Why do lattice/trellis graphics not work?

  7.25 How can I sort the rows of a data frame?

8 R Programming

  8.1 How should I write summary methods?

  8.2 How can I debug dynamically loaded code?

  8.3 How can I inspect R objects when debugging?

  8.4 How can I change compilation flags?

9 R Bugs

  9.1 What is a bug?

  9.2 How to report a bug

10 Acknowledgments

R FAQ

*****

1 Introduction

**************

This document contains answers to some of the most frequently asked

questions about R.

1.1 Legalese

============

This document is copyright (C) 1998-2004 by Kurt Hornik.

   This document is free software; you can redistribute it and/or modify it

under the terms of the GNU General Public License as published by the Free

Software Foundation; either version 2, or (at your option) any later

version.

   This document is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

for more details.

   A copy of the GNU General Public License is available via WWW at

     `http://www.gnu.org/copyleft/gpl.html'.

You can also obtain it by writing to the Free Software Foundation, Inc., 59

Temple Place -- Suite 330, Boston, MA 02111-1307, USA.

1.2 Obtaining this document

===========================

The latest version of this document is always available from

     `http://www.ci.tuwien.ac.at/~hornik/R/'

   From there, you can obtain versions converted to plain ASCII text, DVI,

GNU info, HTML, PDF, PostScript as well as the Texinfo source used for

creating all these formats using the GNU Texinfo system

(http://texinfo.org/).

   You can also obtain the R FAQ from the `doc/FAQ' subdirectory of a CRAN

site (*note What is CRAN?::).

1.3 Citing this document

========================

In publications, please refer to this FAQ as Hornik (2004), "The R FAQ",

and give the above, _official_ URL and the ISBN 3-900051-01-1.

1.4 Notation

============

Everything should be pretty standard.  `R>' is used for the R prompt, and a

`$' for the shell prompt (where applicable).

1.5 Feedback

============

Feedback is of course most welcome.

   In particular, note that I do not have access to Windows or Macintosh

systems.  Features specific to the Windows and MacOS X ports of R are

described in the "R for Windows FAQ"

(http://www.stats.ox.ac.uk/pub/R/rw-FAQ.html) and the "R for Macintosh

FAQ/DOC" (http://cran.r-project.org/bin/macosx/RAqua-FAQ.html).  If you

have information on Macintosh or Windows systems that you think should be

added to this document, please let me know.

2 R Basics

**********

2.1 What is R?

==============

R is a system for statistical computation and graphics.  It consists of a

language plus a run-time environment with graphics, a debugger, access to

certain system functions, and the ability to run programs stored in script

files.

   The design of R has been heavily influenced by two existing languages:

Becker, Chambers & Wilks' S (*note What is S?::) and Sussman's Scheme

(http://www.cs.indiana.edu/scheme-repository/home.html).  Whereas the

resulting language is very similar in appearance to S, the underlying

implementation and semantics are derived from Scheme.  *Note What are the

differences between R and S?::, for further details.

   The core of R is an interpreted computer language which allows branching

and looping as well as modular programming using functions.  Most of the

user-visible functions in R are written in R.  It is possible for the user

to interface to procedures written in the C, C++, or FORTRAN languages for

efficiency.  The R distribution contains functionality for a large number

of statistical procedures.  Among these are: linear and generalized linear

models, nonlinear regression models, time series analysis, classical

parametric and nonparametric tests, clustering and smoothing.  There is

also a large set of functions which provide a flexible graphical

environment for creating various kinds of data presentations.  Additional

modules ("add-on packages") are available for a variety of specific

purposes (*note R Add-On Packages::).

   R was initially written by Ross Ihaka <Ross.Ihaka@R-project.org> and

Robert Gentleman <Robert.Gentleman@R-project.org> at the Department of

Statistics of the University of Auckland in Auckland, New Zealand.  In

addition, a large group of individuals has contributed to R by sending code

and bug reports.

   Since mid-1997 there has been a core group (the "R Core Team") who can

modify the R source code CVS archive.  The group currently consists of Doug

Bates, John Chambers, Peter Dalgaard, Robert Gentleman, Kurt Hornik,

Stefano Iacus, Ross Ihaka, Friedrich Leisch, Thomas Lumley, Martin

Maechler, Duncan Murdoch, Paul Murrell, Martyn Plummer, Brian Ripley,

Duncan Temple Lang, and Luke Tierney.

   R has a home page at `http://www.R-project.org/'.  It is free software

distributed under a GNU-style copyleft, and an official part of the GNU

project ("GNU S").

2.2 What machines does R run on?

================================

R is being developed for the Unix, Windows and Mac families of operating

systems.  Support for Mac OS Classic will end with the 1.7 series.

   The current version of R will configure and build under a number of

common Unix platforms including i386-freebsd, CPU-linux-gnu for the i386,

alpha, arm, hppa, ia64, m68k, powerpc, and sparc CPUs (see e.g.

`http://buildd.debian.org/build.php?&pkg=r-base'), i386-sun-solaris,

powerpc-apple-darwin, mips-sgi-irix, alpha-dec-osf4, rs6000-ibm-aix,

hppa-hp-hpux, and sparc-sun-solaris.

   If you know about other platforms, please drop us a note.

2.3 What is the current version of R?

=====================================

The current released version is 1.8.1.  Based on this

`major.minor.patchlevel' numbering scheme, there are two development

versions of R, working towards the next patch (`r-patched') and minor or

eventually major (`r-devel') releases of R, respectively.  Version

r-patched is for bug fixes mostly.  New features are typically introduced

in r-devel.

2.4 How can R be obtained?

==========================

Sources, binaries and documentation for R can be obtained via CRAN, the

"Comprehensive R Archive Network" (see *Note What is CRAN?::).

   Sources are also available via anonymous rsync.  Use

     rsync -rC --delete rsync.R-project.org::MODULE R

to create a copy of the source tree specified by MODULE in the subdirectory

`R' of the current directory, where MODULE specifies one of the three

existing flavors of the R sources, and can be one of `r-release' (current

released version), `r-patched' (patched released version), and `r-devel'

(development version).  The rsync trees are created directly from the

master CVS archive and are updated hourly.  The `-C' and in the `rsync'

command is to cause it to skip the CVS directories.  Further information on

`rsync' is available at `http://rsync.samba.org/rsync/'.

   The sources of the development version are also available via anonymous

CVS.  See `http://anoncvs.R-project.org' for more information.

2.5 How can R be installed?

===========================

2.5.1 How can R be installed (Unix)

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

If binaries are available for your platform (see *Note Are there Unix

binaries for R?::), you can use these, following the instructions that come

with them.

   Otherwise, you can compile and install R yourself, which can be done

very easily under a number of common Unix platforms (see *Note What

machines does R run on?::).  The file `INSTALL' that comes with the R

distribution contains a brief introduction, and the "R Installation and

Administration" guide (*note What documentation exists for R?::) has full

details.

   Note that you need a FORTRAN compiler or `f2c' in addition to a C

compiler to build R.  Also, you need Perl version 5 to build the R object

documentations.  (If this is not available on your system, you can obtain a

PDF version of the object reference manual via CRAN.)

   In the simplest case, untar the R source code, change to the directory

thus created, and issue the following commands (at the shell prompt):

     $ ./configure

     $ make

   If these commands execute successfully, the R binary and a shell script

front-end called `R' are created and copied to the `bin' directory.  You

can copy the script to a place where users can invoke it, for example to

`/usr/local/bin'.  In addition, plain text help pages as well as HTML and

LaTeX versions of the documentation are built.

   Use `make dvi' to create DVI versions of the R manuals, such as

`refman.dvi' (an R object reference index) and `R-exts.dvi', the "R

Extension Writers Guide", in the `doc/manual' subdirectory.  These files

can be previewed and printed using standard programs such as `xdvi' and

`dvips'.  You can also use `make pdf' to build PDF (Portable Document

Format) version of the manuals, and view these using e.g. Acrobat.  Manuals

written in the GNU Texinfo system can also be converted to info files

suitable for reading online with Emacs or stand-alone GNU Info; use `make

info' to create these versions (note that this requires `makeinfo' version

4).

   Finally, use `make check' to find out whether your R system works

correctly.

   You can also perform a "system-wide" installation using `make install'.

By default, this will install to the following directories:

`${prefix}/bin'

     the front-end shell script

`${prefix}/man/man1'

     the man page

`${prefix}/lib/R'

     all the rest (libraries, on-line help system, ...).  This is the "R

     Home Directory" (`R_HOME') of the installed system.

In the above, `prefix' is determined during configuration (typically

`/usr/local') and can be set by running `configure' with the option

     $ ./configure --prefix=/where/you/want/R/to/go

(E.g., the R executable will then be installed into

`/where/you/want/R/to/go/bin'.)

   To install DVI, info and PDF versions of the manuals, use `make

install-dvi', `make install-info' and `make install-pdf', respectively.

2.5.2 How can R be installed (Windows)

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

The `bin/windows' directory of a CRAN site contains binaries for a base

distribution and a large number of add-on packages from CRAN to run on

Windows 95, 98, ME, NT4, 2000, and XP (at least) on Intel and clones (but

not on other platforms).  The Windows version of R was created by Robert

Gentleman, and is now being developed and maintained by Duncan Murdoch

<murdoch@stats.uwo.ca> and Brian D. Ripley <Brian.Ripley@R-project.org>.

   For most installations the Windows installer program will be the easiest

tool to use.

   See the "R for Windows FAQ"

(http://www.stats.ox.ac.uk/pub/R/rw-FAQ.html) for more details.

2.5.3 How can R be installed (Macintosh)

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

The `bin/macosx' directory of a CRAN site contains a standard Apple

installer package named `RAqua.pkg.sit' compressed in Aladdin Stuffit

format.  Once downloaded, uncompressed and executed, the installer will

install the current non-developer release of R.  RAqua is a native MacOSX

Darwin version of R with an Aqua GUI.  Inside `bin/macosx/X.Y' there are

prebuilt binary packages to be used with RAqua corresponding to the "X.Y"

release of R. The installation of these packages is available through the

"Package" menu of the RAqua GUI.  This port of R for MacOSX is maintained

by Stefano Iacus <Stefano.Iacus@R-project.org>.  The "R for Macintosh

FAQ/DOC" (http://cran.r-project.org/bin/macosx/RAqua-FAQ.html) has more

details.

   The `bin/macos' directory of a CRAN site contains bin-hexed (`hqx') and

stuffit (`sit') archives for a base distribution and a large number of

add-on packages of R 1.7.1 to run under MacOS 8.6 to MacOS 9.2.2.  This

port of R for Macintosh is no longer supported.

2.6 Are there Unix binaries for R?

==================================

The `bin/linux' directory of a CRAN site contains Debian

stable/testing/unstable packages for the i386 platform (now part of the

Debian distribution and maintained by Dirk Eddelbuettel), Mandrake 9.0/9.1

i386 packages by Michele Alzetta, Red Hat 7.x/8.x/9 i386 packages by Martyn

Plummer, SuSE 7.3/8.0/8.1/8.2/9.0 i386 packages by Detlef Steuer, and

VineLinux 2.6 i386 packages by Susunu Tanimura.

   The Debian packages can be accessed through APT, the Debian package

maintenance tool.  Simply add the line

     deb http://cran.R-project.org/bin/linux/debian DISTRIBUTION main

(where DISTRIBUTION is either `stable' or `testing'; feel free to use a

CRAN mirror instead of the master) to the file `/etc/apt/sources.list'.

Once you have added that line the programs `apt-get', `apt-cache', and

`dselect' (using the apt access method) will automatically detect and

install updates of the R packages.

   No other binary distributions are currently publically available.

2.7 What documentation exists for R?

====================================

Online documentation for most of the functions and variables in R exists,

and can be printed on-screen by typing `help(NAME)' (or `?NAME') at the R

prompt, where NAME is the name of the topic help is sought for.  (In the

case of unary and binary operators and control-flow special forms, the name

may need to be be quoted.)

   This documentation can also be made available as one reference manual

for on-line reading in HTML and PDF formats, and as hardcopy via LaTeX, see

*Note How can R be installed?::.  An up-to-date HTML version is always

available for web browsing at `http://stat.ethz.ch/R-manual/'.

   The R distribution also comes with the following manuals.

   * "An Introduction to R" (`R-intro') includes information on data types,

     programming elements, statistical modeling and graphics.  This

     document is based on the "Notes on S-PLUS" by Bill Venables and David

     Smith.

   * "Writing R Extensions" (`R-exts') currently describes the process of

     creating R add-on packages, writing R documentation, R's system and

     foreign language interfaces, and the R API.

   * "R Data Import/Export" (`R-data') is a guide to importing and

     exporting data to and from R.

   * "The R Language Definition" (`R-lang'), a first version of the

     "Kernighan & Ritchie of R", explains evaluation, parsing, object

     oriented programming, computing on the language, and so forth.

   * "R Installation and Administration" (`R-admin').

   Books on R include

     P. Dalgaard (2002), "Introductory Statistics with R", Springer: New

     York, ISBN 0-387-95475-9.

     J. Fox (2002), "An R and S-PLUS Companion to Applied Regression", Sage

     Publications, ISBN 0-761-92280-6 (softcover) or 0-761-92279-2

     (hardcover), `http://socserv.socsci.mcmaster.ca/jfox/Books/Companion/'.

     J. Maindonald and J. Braun (2003), "Data Analysis and Graphics Using R:

     An Example-Based Approach", Cambridge University Press, ISBN

     0-521-81336-0, `http://wwwmaths.anu.edu.au/~johnm/'.

     S. M. Iacus and G. Masarotto (2002), "Laboratorio di statistica con R

     ", McGraw-Hill, ISBN 88-386-6084-0 (in Italian).

The book

     W. N. Venables and B. D. Ripley (2002), "Modern Applied Statistics with

     S.  Fourth Edition".  Springer, ISBN 0-387-95457-0

has a home page at `http://www.stats.ox.ac.uk/pub/MASS4/' providing

additional material.  Its companion is

     W. N. Venables and B. D. Ripley (2000), "S Programming".  Springer,

     ISBN 0-387-98966-8

and provides an in-depth guide to writing software in the S language which

forms the basis of both the commercial S-PLUS and the Open Source R data

analysis software systems.  See

`http://www.stats.ox.ac.uk/pub/MASS3/Sprog/' for more information.

   In addition to material written specifically or explicitly for R,

documentation for S/S-PLUS (see *Note R and S::) can be used in combination

with this FAQ (*note What are the differences between R and S?::).

Introductory books include

     P. Spector (1994), "An introduction to S and S-PLUS", Duxbury Press.

     A. Krause and M. Olsen (2002), "The Basics of S-PLUS" (Third Edition).

     Springer, ISBN 0-387-95456-2

   The book

     J. C. Pinheiro and D. M. Bates (2000), "Mixed-Effects Models in S and

     S-PLUS", Springer, ISBN 0-387-98957-0

provides a comprehensive guide to the use of the *nlme* package for linear

and nonlinear mixed-effects models.  This has a home page at

`http://nlme.stat.wisc.edu/MEMSS/'.

   As an example of how R can be used in teaching an advanced introductory

statistics course, see

     D. Nolan and T. Speed (2000), "Stat Labs: Mathematical Statistics

     Through Applications", Springer Texts in Statistics, ISBN 0-387-98974-9

This integrates theory of statistics with the practice of statistics

through a collection of case studies ("labs"), and uses R to analyze the

data.  More information can be found at

`http://www.stat.Berkeley.EDU/users/statlabs/'.

   Last, but not least, Ross' and Robert's experience in designing and

implementing R is described in Ihaka & Gentleman (1996), "R: A Language for

Data Analysis and Graphics", _Journal of Computational and Graphical

Statistics_, *5*, 299-314.

   An annotated bibliography (BibTeX format) of R-related publications

which includes most of the above references can be found at

     `http://www.R-project.org/doc/bib/R.bib'

2.8 Citing R

============

To cite R in publications, use

     @Manual{,

       title        = {R: A language and environment for statistical

                       computing},

       author       = {{R Development Core Team}},

       organization = {R Foundation for Statistical Computing},

       address      = {Vienna, Austria},

       year         = 2003,

       note         = {ISBN 3-900051-00-3},

       url          = {http://www.R-project.org}

     }

2.9 What mailing lists exist for R?

===================================

Thanks to Martin Maechler <Martin.Maechler@R-project.org>, there are four

mailing lists devoted to R.

`R-announce'

     A moderated list for announcements about the development of R and the

     availability of new code.

`R-packages'

     A moderated list for announcements on the availability of new or

     enhanced contributed packages.

`R-help'

     The `main' R mailing list, for discussion about problems and solutions

     using R, announcements (not covered by `R-announce' and `R-packages')

     about the development of R and the availability of new code,

     enhancements and patches to the source code and documentation of R,

     comparison and compatibility with S and S-PLUS, and for the posting of

     nice examples and benchmarks.

`R-devel'

     This list is for discussions about the future of R and pre-testing of

     new versions.  It is meant for those who maintain an active position in

     the development of R.

Note that the R-announce and R-packages lists are gatewayed into R-help.

Hence, you should subscribe to either of them only in case you are not

subscribed to R-help.

   Send email to <R-help@lists.R-project.org> to reach everyone on the

R-help mailing list.  To subscribe (or unsubscribe) to this list send

`subscribe' (or `unsubscribe') in the _body_ of the message (not in the

subject!) to <R-help-request@lists.R-project.org>.  Information about the

list can be obtained by sending an email with `info' as its contents to

<R-help-request@lists.R-project.org>.

   Subscription and posting to the other lists is done analogously, with

`R-help' replaced by `R-announce', `R-packages', and `R-devel',

respectively.

   Subscriptions to the R-help and R-devel mailing lists are also available

in digest (plain or MIME) format, see the `doc/html/mail.html' file in CRAN

for more information.

   It is recommended that you send mail to R-help rather than only to the R

Core developers (who are also subscribed to the list, of course).  This may

save them precious time they can use for constantly improving R, and will

typically also result in much quicker feedback for yourself.

   Of course, in the case of bug reports it would be very helpful to have

code which reliably reproduces the problem.  Also, make sure that you

include information on the system and version of R being used.  See *Note R

Bugs:: for more details.

   Archives of the above three mailing lists are made available on the net

in a monthly schedule via the `doc/html/mail.html' file in CRAN.

Searchable archives of the lists are available via

`http://maths.newcastle.edu.au/~rking/R/'.

   The R Core Team can be reached at <R-core@lists.R-project.org> for

comments and reports.

2.10 What is CRAN?

==================

The "Comprehensive R Archive Network" (CRAN) is a collection of sites which

carry identical material, consisting of the R distribution(s), the

contributed extensions, documentation for R, and binaries.

   The CRAN master site at TU Wien, Austria, can be found at the URL

     `http://cran.R-project.org/'

and is currently being mirrored daily at

     `http://cran.at.R-project.org/'  (TU Wien, Austria)

     `http://cran.au.R-project.org/'  (PlanetMirror, Australia)

     `http://cran.br.R-project.org/'  (Universidade Federal de

                                      Paraná, Brazil)

     `http://cran.ch.R-project.org/'  (ETH Zürich, Switzerland)

     `http://cran.de.R-project.org/'  (APP, Germany)

     `http://cran.dk.R-project.org/'  (SunSITE, Denmark)

     `http://cran.es.R-project.org/'  (Spanish National Research

                                      Network, Madrid, Spain)

     `http://cran.hu.R-project.org/'  (Semmelweis U, Hungary)

     `http://cran.uk.R-project.org/'  (U of Bristol, United

                                      Kingdom)

     `http://cran.us.R-project.org/'  (U of Wisconsin, USA)

     `http://cran.za.R-project.org/'  (Rhodes U, South Africa)

Please use the CRAN site closest to you to reduce network load.

   From CRAN, you can obtain the latest official release of R, daily

snapshots of R (copies of the current CVS trees), as gzipped and bzipped

tar files, a wealth of additional contributed code, as well as prebuilt

binaries for various operating systems (Linux, MacOS Classic, MacOS X, and

MS Windows).  CRAN also provides access to documentation on R, existing

mailing lists and the R Bug Tracking system.

   To "submit" to CRAN, simply upload to

`ftp://cran.R-project.org/incoming/' and send an email to

<cran@R-project.org>.  Note that CRAN generally does not accept submissions

of precompiled binaries due to security reasons.

     *Note:*  It is very important that you indicate the copyright

     (license) information (GPL, BSD, Artistic, ...)  in your submission.

   Please always use the URL of the master site when referring to CRAN.

2.11 Can I use R for commercial purposes?

=========================================

R is released under the GNU General Public License (GPL).  If you have any

questions regarding the legality of using R in any particular situation you

should bring it up with your legal counsel.  We are in no position to offer

legal advice.

   It is the opinion of the R Core Team that one can use R for commercial

purposes (e.g., in business or in consulting).  The GPL, like all Open

Source licenses, permits all and any use of the package.  It only restricts

distribution of R or of other programs containing code from R.  This is

made clear in clause 6 ("No Discrimination Against Fields of Endeavor") of

the Open Source Definition (http://www.opensource.org/docs/definition.html):

     The license must not restrict anyone from making use of the program in

     a specific field of endeavor.  For example, it may not restrict the

     program from being used in a business, or from being used for genetic

     research.

It is also explicitly stated in clause 0 of the GPL, which says in part

     Activities other than copying, distribution and modification are not

     covered by this License; they are outside its scope.  The act of

     running the Program is not restricted, and the output from the Program

     is covered only if its contents constitute a work based on the Program.

   Most add-on packages, including all recommended ones, also explicitly

allow commercial use in this way.  A few packages are restricted to

"non-commercial use"; you should contact the author to clarify whether

these may be used or seek the advice of your legal counsel.

   None of the discussion in this section constitutes legal advice.  The R

Core Team does not provide legal advice under any circumstances.

2.12 Why is R named R?

======================

The name is partly based on the (first) names of the first two R authors

(Robert Gentleman and Ross Ihaka), and partly a play on the name of the

Bell Labs language `S' (*note What is S?::).

3 R and S

*********

3.1 What is S?

==============

S is a very high level language and an environment for data analysis and

graphics.  In 1998, the Association for Computing Machinery (ACM) presented

its Software System Award to John M. Chambers, the principal designer of S,

for

     the S system, which has forever altered the way people analyze,

     visualize, and manipulate data ...

     S is an elegant, widely accepted, and enduring software system, with

     conceptual integrity, thanks to the insight, taste, and effort of John

     Chambers.

   The evolution of the S language is characterized by four books by John

Chambers and coauthors, which are also the primary references for S.

   * Richard A. Becker and John M. Chambers (1984), "S.  An Interactive

     Environment for Data Analysis and Graphics," Monterey: Wadsworth and

     Brooks/Cole.

     This is also referred to as the "_Brown Book_", and of historical

     interest only.

   * Richard A. Becker, John M. Chambers and Allan R. Wilks (1988), "The New

     S Language," London: Chapman & Hall.

     This book is often called the "_Blue Book_", and introduced what is

     now known as S version 2.

   * John M. Chambers and Trevor J. Hastie (1992), "Statistical Models in

     S,"  London: Chapman & Hall.

     This is also called the "_White Book_", and introduced S version 3,

     which added structures to facilitate statistical modeling in S.

   * John M. Chambers (1998), "Programming with Data," New York: Springer,

     ISBN 0-387-98503-4

     (<http://cm.bell-labs.com/cm/ms/departments/sia/Sbook/>).

     This "_Green Book_" describes version 4 of S, a major revision of S

     designed by John Chambers to improve its usefulness at every stage of

     the programming process.

   See `http://cm.bell-labs.com/cm/ms/departments/sia/S/history.html' for

further information on "Stages in the Evolution of S".

   There is a huge amount of user-contributed code for S, available at the

S Repository (http://lib.stat.cmu.edu/S/) at CMU.

3.2 What is S-PLUS?

===================

S-PLUS is a value-added version of S sold by Insightful Corporation.  Based

on the S language, S-PLUS provides functionality in a wide variety of

areas, including robust regression, modern non-parametric regression, time

series, survival analysis, multivariate analysis, classical statistical

tests, quality control, and graphics drivers.  Add-on modules add

additional capabilities for wavelet analysis, spatial statistics, GARCH

models, and design of experiments.

   See the Insightful S-PLUS page

(http://www.insightful.com/products/splus/) for further information.

3.3 What are the differences between R and S?

=============================================

We can regard S as a language with three current implementations or

"engines", the "old S engine" (S version 3; S-PLUS 3.x and 4.x), the "new S

engine" (S version 4; S-PLUS 5.x and above), and R.  Given this

understanding, asking for "the differences between R and S" really amounts

to asking for the specifics of the R implementation of the S language,

i.e., the difference between the R and S _engines_.

   For the remainder of this section, "S" refers to the S engines and not

the S language.

3.3.1 Lexical scoping

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

Contrary to other implementations of the S language, R has adopted the

evaluation model of Scheme.

   This difference becomes manifest when _free_ variables occur in a

function.  Free variables are those which are neither formal parameters

(occurring in the argument list of the function) nor local variables

(created by assigning to them in the body of the function).  Whereas S

(like C) by default uses _static_ scoping, R (like Scheme) has adopted

_lexical_ scoping.  This means the values of free variables are determined

by a set of global variables in S, but in R by the bindings that were in

effect at the time the function was created.

   Consider the following function:

     cube <- function(n) {

       sq <- function() n * n

       n * sq()

     }

   Under S, `sq()' does not "know" about the variable `n' unless it is

defined globally:

     S> cube(2)

     Error in sq():  Object "n" not found

     Dumped

     S> n <- 3

     S> cube(2)

     [1] 18

   In R, the "environment" created when `cube()' was invoked is also looked

in:

     R> cube(2)

     [1] 8

   As a more "interesting" real-world problem, suppose you want to write a

function which returns the density function of the r-th order statistic

from a sample of size n from a (continuous) distribution.  For simplicity,

we shall use both the cdf and pdf of the distribution as explicit

arguments.  (Example compiled from various postings by Luke Tierney.)

   The S-PLUS documentation for `call()' basically suggests the following:

     dorder <- function(n, r, pfun, dfun) {

       f <- function(x) NULL

       con <- round(exp(lgamma(n + 1) - lgamma(r) - lgamma(n - r + 1)))

       PF <- call(substitute(pfun), as.name("x"))

       DF <- call(substitute(dfun), as.name("x"))

       f[[length(f)]] <-

         call("*", con,

              call("*", call("^", PF, r - 1),

                   call("*", call("^", call("-", 1, PF), n - r),

                        DF)))

       f

     }

Rather tricky, isn't it?  The code uses the fact that in S, functions are

just lists of special mode with the function body as the last argument, and

hence does not work in R (one could make the idea work, though).

   A version which makes heavy use of `substitute()' and seems to work

under both S and R is

     dorder <- function(n, r, pfun, dfun) {

       con <- round(exp(lgamma(n + 1) - lgamma(r) - lgamma(n - r + 1)))

       eval(substitute(function(x) K * PF(x)^a * (1 - PF(x))^b * DF(x),

                       list(PF = substitute(pfun), DF = substitute(dfun),

                            a = r - 1, b = n - r, K = con)))

     }

(the `eval()' is not needed in S).

   However, in R there is a much easier solution:

     dorder <- function(n, r, pfun, dfun) {

       con <- round(exp(lgamma(n + 1) - lgamma(r) - lgamma(n - r + 1)))

       function(x) {

         con * pfun(x)^(r - 1) * (1 - pfun(x))^(n - r) * dfun(x)

       }

     }

This seems to be the "natural" implementation, and it works because the

free variables in the returned function can be looked up in the defining

environment (this is lexical scope).

   Note that what you really need is the function _closure_, i.e., the body

along with all variable bindings needed for evaluating it.  Since in the

above version, the free variables in the value function are not modified,

you can actually use it in S as well if you abstract out the closure

operation into a function `MC()' (for "make closure"):

     dorder <- function(n, r, pfun, dfun) {

       con <- round(exp(lgamma(n + 1) - lgamma(r) - lgamma(n - r + 1)))

       MC(function(x) {

            con * pfun(x)^(r - 1) * (1 - pfun(x))^(n - r) * dfun(x)

          },

          list(con = con, pfun = pfun, dfun = dfun, r = r, n = n))

     }

   Given the appropriate definitions of the closure operator, this works in

both R and S, and is much "cleaner" than a substitute/eval solution (or one

which overrules the default scoping rules by using explicit access to

evaluation frames, as is of course possible in both R and S).

   For R, `MC()' simply is

     MC <- function(f, env) f

(lexical scope!), a version for S is

     MC <- function(f, env = NULL) {

       env <- as.list(env)

       if (mode(f) != "function")

         stop(paste("not a function:", f))

       if (length(env) > 0 && any(names(env) == ""))

         stop(paste("not all arguments are named:", env))

       fargs <- if(length(f) > 1) f[1:(length(f) - 1)] else NULL

       fargs <- c(fargs, env)

       if (any(duplicated(names(fargs))))

         stop(paste("duplicated arguments:", paste(names(fargs)),

              collapse = ", "))

       fbody <- f[length(f)]

       cf <- c(fargs, fbody)

       mode(cf) <- "function"

       return(cf)

     }

   Similarly, most optimization (or zero-finding) routines need some

arguments to be optimized over and have other parameters that depend on the

data but are fixed with respect to optimization.  With R scoping rules,

this is a trivial problem; simply make up the function with the required

definitions in the same environment and scoping takes care of it.  With S,

one solution is to add an extra parameter to the function and to the

optimizer to pass in these extras, which however can only work if the

optimizer supports this.

   Lexical scoping allows using function closures and maintaining local

state.  A simple example (taken from Abelson and Sussman) is obtained by

typing `demo("scoping")' at the R prompt.  Further information is provided

in the standard R reference "R: A Language for Data Analysis and Graphics"

(*note What documentation exists for R?::) and in Robert Gentleman and Ross

Ihaka (2000), "Lexical Scope and Statistical Computing", _Journal of

Computational and Graphical Statistics_, *9*, 491-508.

   Lexical scoping also implies a further major difference.  Whereas S

stores all objects as separate files in a directory somewhere (usually

`.Data' under the current directory), R does not.  All objects in R are

stored internally.  When R is started up it grabs a piece of memory and

uses it to store the objects.  R performs its own memory management of this

piece of memory, growing and shrinking its size as needed.  Having

everything in memory is necessary because it is not really possible to

externally maintain all relevant "environments" of symbol/value pairs.

This difference also seems to make R _faster_ than S.

   The down side is that if R crashes you will lose all the work for the

current session.  Saving and restoring the memory "images" (the functions

and data stored in R's internal memory at any time) can be a bit slow,

especially if they are big.  In S this does not happen, because everything

is saved in disk files and if you crash nothing is likely to happen to

them.  (In fact, one might conjecture that the S developers felt that the

price of changing their approach to persistent storage just to accommodate

lexical scope was far too expensive.)  Hence, when doing important work,

you might consider saving often (see *Note How can I save my workspace?::)

to safeguard against possible crashes.  Other possibilities are logging

your sessions, or have your R commands stored in text files which can be

read in using `source()'.

     *Note:*  If you run R from within Emacs (see *Note R and Emacs::), you

     can save the contents of the interaction buffer to a file and

     conveniently manipulate it using `ess-transcript-mode', as well as

     save source copies of all functions and data used.

3.3.2 Models

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

There are some differences in the modeling code, such as

   * Whereas in S, you would use `lm(y ~ x^3)' to regress `y' on `x^3', in

     R, you have to insulate powers of numeric vectors (using `I()'), i.e.,

     you have to use `lm(y ~ I(x^3))'.

   * The glm family objects are implemented differently in R and S.  The

     same functionality is available but the components have different

     names.

   * Option `na.action' is set to `"na.omit"' by default in R, but not set

     in S.

   * Terms objects are stored differently.  In S a terms object is an

     expression with attributes, in R it is a formula with attributes.  The

     attributes have the same names but are mostly stored differently.  The

     major difference in functionality is that a terms object is

     subscriptable in S but not in R.  If you can't imagine why this would

     matter then you don't need to know.

   * Finally, in R `y~x+0' is an alternative to `y~x-1' for specifying a

     model with no intercept.  Models with no parameters at all can be