/
FAQ
4342 lines (3287 loc) · 158 KB
/
FAQ
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
R FAQ
Frequently Asked Questions on R
Version 1.9-54 2004-09-28
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?
2.13 What is the R Foundation?
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 How can I set components of a list to NULL?
7.2 How can I save my workspace?
7.3 How can I clean up my workspace?
7.4 How can I get eval() and D() to work?
7.5 Why do my matrices lose dimensions?
7.6 How does autoloading work?
7.7 How should I set options?
7.8 How do file names work in Windows?
7.9 Why does plotting give a color allocation error?
7.10 How do I convert factors to numeric?
7.11 Are Trellis displays implemented in R?
7.12 What are the enclosing and parent environments?
7.13 How can I substitute into a plot label?
7.14 What are valid names?
7.15 Are GAMs implemented in R?
7.16 Why is the output not printed when I source() a file?
7.17 Why does outer() behave strangely with my function?
7.18 Why does the output from anova() depend on the order of factors in the model?
7.19 How do I produce PNG graphics in batch mode?
7.20 How can I get command line editing to work?
7.21 How can I turn a string into a variable?
7.22 Why do lattice/trellis graphics not work?
7.23 How can I sort the rows of a data frame?
7.24 Why does the help.start() search engine not work?
7.25 Why did my .Rprofile stop working when I updated R?
7.26 Where have all the methods gone?
7.27 How can I create rotated axis labels?
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?
8.5 How can I debug S4 methods?
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 via email to <Kurt.Hornik@R-project.org> 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 Mac OS 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 Mac OS X FAQ
(http://cran.R-project.org/bin/macosx/RMacOSX-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 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 ended with R 1.7.1.
The current version of R will configure and build under a number of
common Unix platforms including CPU-linux-gnu for the i386, alpha, arm,
hppa, ia64, m68k, mips/mipsel, powerpc, s390, sparc (e.g.,
`http://buildd.debian.org/build.php?&pkg=r-base'), and x86_64 CPUs,
i386-freebsd, i386-sun-solaris, powerpc-apple-darwin, mips-sgi-irix,
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.9.1. Based on this
`major.minor.patchlevel' numbering scheme, there are two development
versions of R, a patched version of the current release (`r-patched') and
one working towards the next 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 `https://svn.r-project.org/R/', the R
Subversion repository, but currently not via anonymous rsync (nor CVS).
2.5 How can R be installed?
===========================
2.5.1 How can R be installed (Unix)
-----------------------------------
If R is already installed, it can be started by typing `R' at the shell
prompt (of course, provided that the executable is in your path).
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 perhaps `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.5).
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 Guido Masarotto, 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 Mac OS X
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 Mac OS X is maintained
by Stefano Iacus <Stefano.Iacus@R-project.org>. The "R for Mac OS X FAQ
(http://cran.R-project.org/bin/macosx/RMacOSX-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 Mac OS 8.6 to Mac OS 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.1/9.2/10.0 i386 packages by Michele Alzetta, Red Hat
8.x/9/Fedora1/Fedora2 i386 and Fedora1 x86_64 packages by Martyn Plummer
and James Henstridge, respectively, SuSE 7.3/8.0/8.1/8.2 i386 and 9.0/9.1
i586 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/'.
Printed copies of the R reference manual for some version(s) are
available from Network Theory Ltd, at
`http://www.network-theory.co.uk/R/base/'. For each set of manuals sold,
the publisher donates USD 10 to the R Foundation (*note What is the R
Foundation?::).
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.
`http://www.biostat.ku.dk/~pd/ISwR.html'.
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),
`http://www.ateneonline.it/LibroAteneo.asp?item_id=1436'.
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.
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 = 2004,
note = {3-900051-00-3},
url = {http://www.R-project.org}
}
Citation strings (or BibTeX entroes) for R and R packages can also be
obtained by `citation()'.
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 major 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, proposals of new
functionality, and pre-testing of new versions. It is meant for those
who maintain an active position in the development of R.
Convenient access to information on these lists, subscription, and archives
is provided by the web interface at
`http://stat.ethz.ch/mailman/listinfo/'. One can also subscribe (or
unsubscribe) via email, e.g. to R-help by sending `subscribe' (or
`unsubscribe') in the _body_ of the message (not in the subject!) to
<R-help-request@lists.R-project.org>.
Send email to <R-help@lists.R-project.org> to send a message to everyone
on the R-help mailing list. Subscription and posting to the other lists is
done analogously, with `R-help' replaced by `R-announce', `R-packages', and
`R-devel', respectively. 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.
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.
Please read the posting guide
(http://www.R-project.org/posting-guide.html) _before_ sending anything to
any mailing list.
See `http://www.R-project.org/mail.html' for more information on the R
mailing lists.
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/'
Daily mirrors are available at URLs including
`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.dk.R-project.org/' (SunSITE, Denmark)
`http://cran.es.R-project.org/' (Spanish National Research
Network, Madrid, Spain)
`http://cran.fr.R-project.org/' (INRA, Toulouse, France)
`http://cran.hu.R-project.org/' (Semmelweis U, Hungary)
`http://cran.pt.R-project.org/' (Universidade do Porto,
Portugal)
`http://cran.uk.R-project.org/' (U of Bristol, United
Kingdom)
`http://cran.us.R-project.org/' (pair Networks, USA)
`http://cran.za.R-project.org/' (Rhodes U, South Africa)
See `http://cran.R-project.org/mirrors.html' for a complete list of
mirrors. 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 source trees), as gzipped and bzipped
tar files, a wealth of additional contributed code, as well as prebuilt
binaries for various operating systems (Linux, Mac OS Classic, Mac OS 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. In particular, binary
packages for Windows and Mac OS X are provided by the respective binary
package maintainers.
*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?::).
2.13 What is the R Foundation?
==============================
The R Foundation is a not for profit organization working in the public
interest. It was founded by the members of the R Core Team in order to
provide support for the R project and other innovations in statistical
computing, provide a reference point for individuals, instititutions or
commercial enterprises that want to support or interact with the R
development community, and to hold and administer the copyright of R
software and documentation. See `http://www.R-project.org/foundation/' for
more information.
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.
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.
* 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
specified by `y~0'.
3.3.3 Others
------------
Apart from lexical scoping and its implications, R follows the S language
definition in the Blue and White Books as much as possible, and hence
really is an "implementation" of S. There are some intentional differences
where the behavior of S is considered "not clean". In general, the
rationale is that R should help you detect programming errors, while at the
same time being as compatible as possible with S.
Some known differences are the following.
* In R, if `x' is a list, then `x[i] <- NULL' and `x[[i]] <- NULL'
remove the specified elements from `x'. The first of these is
incompatible with S, where it is a no-op. (Note that you can set
elements to `NULL' using `x[i] <- list(NULL)'.)
* In S, the functions named `.First' and `.Last' in the `.Data'
directory can be used for customizing, as they are executed at the
very beginning and end of a session, respectively.
In R, the startup mechanism is as follows. R first sources the system
startup file ``$R_HOME'/library/base/R/Rprofile'. Then, it searches
for a site-wide startup profile unless the command line option
`--no-site-file' was given. The name of this file is taken from the
value of the `R_PROFILE' environment variable. If that variable is
unset, the default is ``$R_HOME'/etc/Rprofile.site'
(``$R_HOME'/etc/Rprofile' in versions prior to 1.4.0). This code is
loaded in package *base*. Then, unless `--no-init-file' was given, R
searches for a file called `.Rprofile' in the current directory or in
the user's home directory (in that order) and sources it into the user