/
R-FAQ.texi
3960 lines (3405 loc) · 155 KB
/
R-FAQ.texi
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
\input texinfo
@c %**start of header
@setfilename R-FAQ.info
@settitle R FAQ
@setchapternewpage on
@set FAQ-YEAR 2003
@set FAQ-VERSION 1.7-48, @value{FAQ-YEAR}-10-02
@set REL-VERSION 1.7.1
@set FAQ-ISBN 3-901167-51-X
@documentlanguage en
@documentencoding ISO-8859-1
@c %**end of header
@dircategory Programming
@direntry
* R FAQ: (R-FAQ). The R statistical system FAQ.
@end direntry
@finalout
@macro SPLUS{}
@sc{S-Plus}
@end macro
@macro CRAN{}
@acronym{CRAN}
@end macro
@macro HTML{}
@acronym{HTML}
@end macro
@macro FORTRAN{}
FORTRAN
@end macro
@macro XML{}
@acronym{XML}
@end macro
@macro XSL{}
@acronym{XSL}
@end macro
@titlepage
@title R @acronym{FAQ}
@subtitle Frequently Asked Questions on R
@subtitle Version @value{FAQ-VERSION}
@subtitle ISBN @value{FAQ-ISBN}
@author Kurt Hornik
@end titlepage
@ifinfo
@c We do not really see this in info, but in plain text output.
R FAQ @*
Frequently Asked Questions on R @*
Version @value{FAQ-VERSION} @*
ISBN @value{FAQ-ISBN} @*
Kurt Hornik @*
@sp 2
@end ifinfo
@ifnothtml
@contents
@end ifnothtml
@ifnottex
@node Top, Introduction, (dir), (dir)
@top R FAQ
@ifhtml
@html
<h2>Frequently Asked Questions on R</h2>
<h2>Version @value{FAQ-VERSION}</h2>
<h2>ISBN @value{FAQ-ISBN}</h2>
<address>Kurt Hornik</address>
<p><p><hr><p>
@end html
@end ifhtml
@end ifnottex
@menu
* Introduction::
* R Basics::
* R and S::
* R Web Interfaces::
* R Add-On Packages::
* R and Emacs::
* R Miscellanea::
* R Programming::
* R Bugs::
* Acknowledgments::
@end menu
@node Introduction, R Basics, Top, Top
@chapter Introduction
This document contains answers to some of the most frequently asked
questions about R.
@menu
* Legalese::
* Obtaining this document::
* Citing this document::
* Notation::
* Feedback::
@end menu
@node Legalese, Obtaining this document, Introduction, Introduction
@section Legalese
This document is copyright @copyright{} 1998--@value{FAQ-YEAR} by Kurt
Hornik.
This document is free software; you can redistribute it and/or modify it
under the terms of the @acronym{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
@acronym{GNU} General Public License for more details.
A copy of the @acronym{GNU} General Public License is available via WWW
at
@display
@uref{http://www.gnu.org/copyleft/gpl.html}.
@end display
@noindent
You can also obtain it by writing to the Free Software Foundation, Inc.,
59 Temple Place --- Suite 330, Boston, MA 02111-1307, USA.
@node Obtaining this document, Citing this document, Legalese, Introduction
@section Obtaining this document
The latest version of this document is always available from
@display
@uref{http://www.ci.tuwien.ac.at/~hornik/R/}
@end display
From there, you can obtain versions converted to
@uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.txt,, plain
@acronym{ASCII} text},
@uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.dvi.gz,, DVI},
@uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.info.gz,, @acronym{GNU}
info}, @uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html,, @HTML{}},
@uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.pdf,, PDF},
@uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.ps.gz,, PostScript} as
well as the @uref{http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.texi,,
Texinfo source} used for creating all these formats using the
@uref{http://texinfo.org/, @acronym{GNU} Texinfo system}.
You can also obtain the R @acronym{FAQ} from the @file{doc/FAQ}
subdirectory of a @CRAN{} site (@pxref{What is CRAN?}).
@node Citing this document, Notation, Obtaining this document, Introduction
@section Citing this document
In publications, please refer to this @acronym{FAQ} as Hornik
(@value{FAQ-YEAR}), ``The R @acronym{FAQ}'', and give the above,
@emph{official} @acronym{URL} and the ISBN @value{FAQ-ISBN}.
@node Notation, Feedback, Citing this document, Introduction
@section Notation
Everything should be pretty standard. @samp{R>} is used for the R
prompt, and a @samp{$} for the shell prompt (where applicable).
@node Feedback, , Notation, Introduction
@section Feedback
Feedback is of course most welcome.
In particular, note that I do not have access to Windows or Mac systems.
Features specific to the Windows and Mac OS ports of R are described in
the @uref{http://www.stats.ox.ac.uk/pub/R/rw-FAQ.html, ``R for Windows
@acronym{FAQ}''} and the
@uref{http://cran.r-project.org/bin/macosx/RAqua-FAQ.html, ``R for
Macintosh @acronym{FAQ}/DOC''}. If you have information on Mac or
Windows systems that you think should be added to this document, please
let me know.
@c <FIXME>
@c Should we maybe have direct links inside the R tree to the various
@c rw-FAQ versions?
@c </FIXME>
@node R Basics, R and S, Introduction, Top
@chapter R Basics
@menu
* What is R?::
* What machines does R run on?::
* What is the current version of R?::
* How can R be obtained?::
* How can R be installed?::
* Are there Unix binaries for R?::
* What documentation exists for R?::
* Citing R::
* What mailing lists exist for R?::
* What is CRAN?::
* Can I use R for commercial purposes?::
@end menu
@node What is R?, What machines does R run on?, R Basics, R Basics
@section 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 (@pxref{What is S?}) and Sussman's
@uref{http://www.cs.indiana.edu/scheme-repository/home.html, Scheme}.
Whereas the resulting language is very similar in appearance to S, the
underlying implementation and semantics are derived from Scheme.
@xref{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 (@pxref{R Add-On Packages}).
R was initially written by @email{Ross.Ihaka@@R-project.org, Ross Ihaka}
and @email{Robert.Gentleman@@R-project.org, Robert Gentleman} 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 @uref{http://www.R-project.org/}. It is free
software distributed under a @acronym{GNU}-style copyleft, and an
official part of the @acronym{GNU} project (``@acronym{GNU} S'').
@node What machines does R run on?, What is the current version of R?, What is R?, R Basics
@section 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, @var{cpu}-linux-gnu for
the i386, alpha, arm, hppa, ia64, m68k, powerpc, and sparc CPUs (see
e.g.@: @uref{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.
@c and according to @email{jlindsey@@luc.ac.be, Jim Lindsey} also on
@c Mac, Amiga and Atari under m68k-linux.
If you know about other platforms, please drop us a note.
@node What is the current version of R?, How can R be obtained?, What machines does R run on?, R Basics
@section What is the current version of R?
The current released version is @value{REL-VERSION}. 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.
@node How can R be obtained?, How can R be installed?, What is the current version of R?, R Basics
@section How can R be obtained?
Sources, binaries and documentation for R can be obtained via @CRAN{},
the ``Comprehensive R Archive Network'' (see @ref{What is CRAN?}).
Sources are also available via anonymous rsync. Use
@example
rsync -rC --delete rsync.R-project.org::@var{module} R
@end example
@noindent
to create a copy of the source tree specified by @var{module} in the
subdirectory @file{R} of the current directory, where @var{module}
specifies one of the three existing flavors of the R sources, and can be
one of @samp{r-release} (current released version), @samp{r-patched}
(patched released version), and @samp{r-devel} (development version).
The rsync trees are created directly from the master CVS archive and are
updated hourly. The @option{-C} and in the @command{rsync} command
is to cause it to skip the CVS directories. Further information on
@command{rsync} is available at @uref{http://rsync.samba.org/rsync/}.
@node How can R be installed?, Are there Unix binaries for R?, How can R be obtained?, R Basics
@section How can R be installed?
@menu
* How can R be installed (Unix)::
* How can R be installed (Windows)::
* How can R be installed (Macintosh)::
@end menu
@node How can R be installed (Unix), How can R be installed (Windows), How can R be installed?, How can R be installed?
@subsection How can R be installed (Unix)
If binaries are available for your platform (see @ref{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 @ref{What
machines does R run on?}). The file @file{INSTALL} that comes with the
R distribution contains a brief introduction, and the ``R Installation
and Administration'' guide (@pxref{What documentation exists for R?})
has full details.
Note that you need a @FORTRAN{} compiler or @command{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):
@example
$ ./configure
$ make
@end example
If these commands execute successfully, the R binary and a shell script
front-end called @file{R} are created and copied to the @file{bin}
directory. You can copy the script to a place where users can invoke
it, for example to @file{/usr/local/bin}. In addition, plain text help
pages as well as @HTML{} and La@TeX{} versions of the documentation are
built.
Use @kbd{make dvi} to create DVI versions of the R manuals, such as
@file{refman.dvi} (an R object reference index) and @file{R-exts.dvi},
the ``R Extension Writers Guide'', in the @file{doc/manual}
subdirectory. These files can be previewed and printed using standard
programs such as @command{xdvi} and @command{dvips}. You can also use
@kbd{make pdf} to build PDF (Portable Document Format) version of the
manuals, and view these using e.g.@: Acrobat. Manuals written in the
@acronym{GNU} Texinfo system can also be converted to info files
suitable for reading online with Emacs or stand-alone @acronym{GNU}
Info; use @kbd{make info} to create these versions (note that this
requires @command{makeinfo} version 4).
Finally, use @kbd{make check} to find out whether your R system works
correctly.
You can also perform a ``system-wide'' installation using @kbd{make
install}. By default, this will install to the following directories:
@table @file
@item $@{prefix@}/bin
the front-end shell script
@item $@{prefix@}/man/man1
the man page
@item $@{prefix@}/lib/R
all the rest (libraries, on-line help system, @dots{}). This is the ``R
Home Directory'' (@env{R_HOME}) of the installed system.
@end table
@noindent
In the above, @code{prefix} is determined during configuration
(typically @file{/usr/local}) and can be set by running
@command{configure} with the option
@example
$ ./configure --prefix=/where/you/want/R/to/go
@end example
@noindent
(E.g., the R executable will then be installed into
@file{/where/you/want/R/to/go/bin}.)
To install DVI, info and PDF versions of the manuals, use @kbd{make
install-dvi}, @kbd{make install-info} and @kbd{make install-pdf},
respectively.
@node How can R be installed (Windows), How can R be installed (Macintosh), How can R be installed (Unix), How can R be installed?
@subsection How can R be installed (Windows)
The @file{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 @email{murdoch@@stats.uwo.ca, Duncan Murdoch} and
@email{Brian.Ripley@@R-project.org, Brian D. Ripley}.
@c Note that when uncompressing the zip files, the pkunzip program needs to
@c be invoked with the @samp{-D} flag to create subdirectories. Also, be
@c aware that some decompression programs do not preserve long file names
@c properly.
For most installations the Windows installer program will be the easiest
tool to use.
See the @uref{http://www.stats.ox.ac.uk/pub/R/rw-FAQ.html, ``R for
Windows @acronym{FAQ}''} for more details.
@node How can R be installed (Macintosh), , How can R be installed (Windows), How can R be installed?
@subsection How can R be installed (Macintosh)
The @file{bin/macosx} directory of a @CRAN{} site contains a standard
Apple installer package named @file{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 with Aqua GUI.
Inside @file{bin/macosx/@var{x}.@var{y}} there are prebuilt binary
version of packages ready to be used with RAqua corresponding to R major
release ``@var{x}.@var{y}''. The installation of these packages is
available through the ``Package'' menu of the RAqua GUI.
This port of R for MacOSX is maintained by
@email{Stefano.Iacus@@R-project.org, Stefano Iacus}. The
@uref{http://cran.r-project.org/bin/macosx/RAqua-FAQ.html, ``R for
Macintosh @acronym{FAQ}/DOC''} has more details.
The @file{bin/macos} directory of a @CRAN{} site contains bin-hexed
(@file{hqx}) and stuffit (@file{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.
@node Are there Unix binaries for R?, What documentation exists for R?, How can R be installed?, R Basics
@section Are there Unix binaries for R?
@c Linux binaries as of 2003-07-15:
@c
@c debian woody i386 1.7.1 Dirk Eddelbuettel <edd@debian.org>
@c sarge i386 1.7.1 Dirk Eddelbuettel <edd@debian.org>
@c mandrake 8.0 i386 1.7.1 Michele Alzetta <mikalzet@libero.it>
@c 8.1 i386 1.7.1 Michele Alzetta <mikalzet@libero.it>
@c 8.2 i386 1.7.1 Michele Alzetta <mikalzet@libero.it>
@c 9.0 i386 1.7.1 Michele Alzetta <mikalzet@libero.it>
@c 9.1 i386 1.7.1 Michele Alzetta <mikalzet@libero.it>
@c redhat 7.x alpha 1.6.0 Naoki Takebayashi <ntakebay@bio.indiana.edu>
@c i386 1.7.1 Martyn Plummer <plummer@iarc.fr>
@c 8.x i386 1.7.1 Martyn Plummer <plummer@iarc.fr>
@c 9 i386 1.7.1 Martyn Plummer <plummer@iarc.fr>
@c suse 7.3 i386 1.7.1 Detlef Steuer <Detlef.Steuer@unibw-hamburg.de>
@c 8.0 i386 1.7.1 Detlef Steuer <Detlef.Steuer@unibw-hamburg.de>
@c 8.1 i386 1.7.1 Detlef Steuer <Detlef.Steuer@unibw-hamburg.de>
@c 8.2 i386 1.7.1 Detlef Steuer <Detlef.Steuer@unibw-hamburg.de>
@c vinelinux 2.6 i386 1.7.1 Susunu Tanimura <stanimura-ngs@umin.ac.jp>
The @file{bin/linux} directory of a @CRAN{} site contains Debian
stable/testing packages for the i386 platform (now part of the Debian
distribution and maintained by Dirk Eddelbuettel), Mandrake
8.0/8.1/8.2/9.0/9.1 i386 packages by Michele Alzetta, Red Hat 7.x/8.x/9
i386 and 7.x alpha packages (maintained by Martyn Plummer and Naoki
Takebayashi, respectively), SuSE 7.3/8.0/8.1/8.2 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
@example
deb http://cran.R-project.org/bin/linux/debian @var{distribution} main
@end example
@noindent
(where @var{distribution} is either @samp{stable} or @samp{testing};
feel free to use a @CRAN{} mirror instead of the master) to the file
@file{/etc/apt/sources.list}. Once you have added that line the
programs @command{apt-get}, @command{apt-cache}, and @command{dselect}
(using the apt access method) will automatically detect and install
updates of the R packages.
@c The @file{bin/osf} directory of a @CRAN{} site contains RPMs
@c by Albrecht Gebhardt for alpha systems running Alpha Unix
@c (OSF/Tru64).
@c There are also `tar' distributions for NEXTSTEP on the i386 and m68k
@c platforms in @file{bin/nextstep/i386} and @file{bin/nextstep/m68k},
@c created by Stephen Shiboski <steve@biostat.ucsf.edu>.
No other binary distributions are currently publically available.
@node What documentation exists for R?, Citing R, Are there Unix binaries for R?, R Basics
@section 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 @kbd{help(@var{name})}
(or @kbd{?@var{name}}) at the R prompt, where @var{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
La@TeX{}, see @ref{How can R be installed?}. An up-to-date @HTML{}
version is always available for web browsing at
@uref{http://stat.ethz.ch/R-manual/}.
The R distribution also comes with the following manuals.
@itemize @bullet
@item ``An Introduction to R'' (@file{R-intro})
includes information on data types, programming elements, statistical
modeling and graphics. This document is based on the ``Notes on
@SPLUS{}'' by Bill Venables and David Smith.
@item ``Writing R Extensions'' (@file{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
@acronym{API}.
@item ``R Data Import/Export'' (@file{R-data})
is a guide to importing and exporting data to and from R.
@item ``The R Language Definition'' (@file{R-lang}),
a first version of the ``Kernighan & Ritchie of R'', explains
evaluation, parsing, object oriented programming, computing on the
language, and so forth.
@item ``R Installation and Administration'' (@file{R-admin}).
@end itemize
Books on R include
@quotation
Peter Dalgaard (2002), ``Introductory Statistics with R'', Springer: New
York, ISBN 0-387-95475-9.
J. Fox (2002), ``An R and @SPLUS{} Companion to Applied Regression'',
Sage Publications, ISBN 0-761-92280-6 (softcover) or 0-761-92279-2
(hardcover), @uref{http://www.socsci.mcmaster.ca/jfox/Books/Companion/}.
@end quotation
@noindent
The book
@quotation
W. N. Venables and B. D. Ripley (2002), ``Modern Applied Statistics with
S. Fourth Edition''. Springer, ISBN 0-387-95457-0
@end quotation
@noindent
has a home page at @uref{http://www.stats.ox.ac.uk/pub/MASS4/} providing
additional material. Its companion is
@quotation
W. N. Venables and B. D. Ripley (2000), ``S Programming''. Springer,
ISBN 0-387-98966-8
@end quotation
@noindent
and provides an in-depth guide to writing software in the S language
which forms the basis of both the commercial @SPLUS{} and the Open
Source R data analysis software systems. See
@uref{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/@SPLUS{} (see @ref{R and S}) can be used in
combination with this @acronym{FAQ} (@pxref{What are the differences
between R and S?}). Introductory books include
@quotation
P. Spector (1994), ``An introduction to S and @SPLUS{}'', Duxbury Press.
A. Krause and M. Olsen (2002), ``The Basics of @SPLUS{}'' (Third
Edition). Springer, ISBN 0-387-95456-2
@end quotation
The book
@quotation
J. C. Pinheiro and D. M. Bates (2000), ``Mixed-Effects Models in S and
@SPLUS{}'', Springer, ISBN 0-387-98957-0
@end quotation
@noindent
provides a comprehensive guide to the use of the @strong{nlme} package
for linear and nonlinear mixed-effects models. This has a home page at
@uref{http://nlme.stat.wisc.edu/MEMSS/}.
As an example of how R can be used in teaching an advanced introductory
statistics course, see
@quotation
D. Nolan and T. Speed (2000), ``Stat Labs: Mathematical Statistics
Through Applications'', Springer Texts in Statistics, ISBN
0-387-98974-9
@end quotation
@noindent
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
@uref{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'',
@uref{http://www.amstat.org/publications/jcgs/, , @emph{Journal of
Computational and Graphical Statistics}}, @strong{5}, 299--314.
@xref{Citing R}.
An annotated bibliography (Bib@TeX{} format) of R-related publications
which includes most of the above references can be found at
@display
@uref{http://www.R-project.org/doc/bib/R.bib}
@end display
@node Citing R, What mailing lists exist for R?, What documentation exists for R?, R Basics
@section Citing R
To cite R in publications, use
@example
@group
@@article@{,
author = @{Ross Ihaka and Robert Gentleman@},
title = @{R: A Language for Data Analysis and Graphics@},
journal = @{Journal of Computational and Graphical Statistics@},
year = 1996,
volume = 5,
number = 3,
pages = @{299--314@}
@}
@end group
@end example
@node What mailing lists exist for R?, What is CRAN?, Citing R, R Basics
@section What mailing lists exist for R?
Thanks to @email{Martin.Maechler@@R-project.org, Martin Maechler}, there
are four mailing lists devoted to R.
@table @code
@item R-announce
A moderated list for announcements about the development of R and the
availability of new code.
@item R-packages
A moderated list for announcements on the availability of new or
enhanced contributed packages.
@item 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 @SPLUS{}, and for the posting of
nice examples and benchmarks.
@item 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.
@end table
@noindent
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 @email{R-help@@lists.R-project.org} to reach everyone on
the R-help mailing list. To subscribe (or unsubscribe) to this list
send @samp{subscribe} (or @samp{unsubscribe}) in the @emph{body} of the
message (not in the subject!) to
@email{R-help-request@@lists.R-project.org}. Information about the list
can be obtained by sending an email with @samp{info} as its contents to
@email{R-help-request@@lists.R-project.org}.
Subscription and posting to the other lists is done analogously, with
@samp{R-help} replaced by @samp{R-announce}, @samp{R-packages}, and
@samp{R-devel}, respectively.
Subscriptions to the R-help and R-devel mailing lists are also available
in digest (plain or MIME) format, see the @file{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
@ref{R Bugs} for more details.
Archives of the above three mailing lists are made available on the net
in a monthly schedule via the @file{doc/html/mail.html} file in @CRAN{}.
Searchable archives of the lists are available via
@uref{http://maths.newcastle.edu.au/~rking/R/}.
The R Core Team can be reached at @email{R-core@@lists.R-project.org}
for comments and reports.
@node What is CRAN?, Can I use R for commercial purposes?, What mailing lists exist for R?, R Basics
@section What is @acronym{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
@acronym{URL}
@quotation
@c @multitable @columnfractions .45 .30
@c @item
@uref{http://cran.R-project.org/}
@c @tab (Austria)
@c @end multitable
@end quotation
@noindent
@c (which is the same as @uref{http://cran.at.R-project.org/})
and is currently being mirrored daily at
@quotation
@multitable @columnfractions .45 .40
@item @uref{http://cran.at.R-project.org/}
@tab (TU Wien, Austria)
@item @uref{http://cran.au.R-project.org/}
@tab (PlanetMirror, Australia)
@item @uref{http://cran.br.R-project.org/}
@tab (Universidade Federal de Paran@'a, Brazil)
@item @uref{http://cran.ch.R-project.org/}
@tab (ETH Z@"urich, Switzerland)
@item @uref{http://cran.de.R-project.org/}
@tab (APP, Germany)
@item @uref{http://cran.dk.R-project.org/}
@tab (SunSITE, Denmark)
@item @uref{http://cran.hu.R-project.org/}
@tab (Semmelweis U, Hungary)
@c @item @uref{http://cran.it.R-project.org/}
@c @tab (Italy)
@item @uref{http://cran.uk.R-project.org/}
@tab (U of Bristol, United Kingdom)
@item @uref{http://cran.us.R-project.org/}
@tab (U of Wisconsin, USA)
@item @uref{http://cran.za.R-project.org/}
@tab (Rhodes U, South Africa)
@end multitable
@end quotation
@noindent
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
@uref{ftp://cran.R-project.org/incoming/} and send an email to
@email{cran@@R-project.org}. Note that @CRAN{} generally does not
accept submissions of precompiled binaries due to security reasons.
@quotation
@strong{Note:} It is very important that you indicate the copyright
(license) information (@acronym{GPL}, @acronym{BSD}, Artistic, @dots{})
in your submission.
@end quotation
Please always use the @acronym{URL} of the master site when referring to
@CRAN{}.
@node Can I use R for commercial purposes?, , What is CRAN?, R Basics
@section Can I use R for commercial purposes?
R is released under the @uref{http://www.gnu.org/copyleft/gpl.html,, 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 @uref{http://www.opensource.org/docs/definition.html,
Open Source Definition}:
@quotation
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.
@end quotation
@noindent
It is also explicitly stated in clause 0 of the GPL, which says in part
@quotation
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.
@end quotation
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.
@node R and S, R Web Interfaces, R Basics, Top
@chapter R and S
@menu
* What is S?::
* What is S-PLUS?::
* What are the differences between R and S?::
* Is there anything R can do that S-PLUS cannot?::
* What is R-plus?::
@end menu
@node What is S?, What is S-PLUS?, R and S, R and S
@section 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
(@acronym{ACM}) presented its Software System Award to John M. Chambers,
the principal designer of S, for
@quotation
the S system, which has forever altered the way people analyze,
visualize, and manipulate data @dots{}
S is an elegant, widely accepted, and enduring software system, with
conceptual integrity, thanks to the insight, taste, and effort of John
Chambers.
@end quotation
The evolution of the S language is characterized by four books by John
Chambers and coauthors, which are also the primary references for S.
@itemize @bullet
@item
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 ``@emph{Brown Book}'', and of historical
interest only.
@item
Richard A. Becker, John M. Chambers and Allan R. Wilks (1988), ``The New
S Language,'' London: Chapman & Hall.
This book is often called the ``@emph{Blue Book}'', and introduced what
is now known as S version 2.
@item
John M. Chambers and Trevor J. Hastie (1992), ``Statistical Models in
S,'' London: Chapman & Hall.
This is also called the ``@emph{White Book}'', and introduced S version
3, which added structures to facilitate statistical modeling in S.
@item
John M. Chambers (1998), ``Programming with Data,'' New York: Springer,
ISBN 0-387-98503-4
(@url{http://cm.bell-labs.com/cm/ms/departments/sia/Sbook/}).
This ``@emph{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.
@end itemize
See @uref{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
@uref{http://lib.stat.cmu.edu/S/, S Repository} at @acronym{CMU}.
@c The @uref{http://lib.stat.cmu.edu/S/faq, ``Frequently Asked Questions
@c about S''} contains further information about S, but is not
@c up-to-date.
@node What is S-PLUS?, What are the differences between R and S?, What is S?, R and S
@section What is @sc{S-Plus}?
@SPLUS{} is a value-added version of S sold by Insightful Corporation.
Based on the S language, @SPLUS{} 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 @uref{http://www.insightful.com/products/splus/, Insightful
@SPLUS{} page} for further information.
@node What are the differences between R and S?, Is there anything R can do that S-PLUS cannot?, What is S-PLUS?, R and S
@section 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; @SPLUS{} 3.x and 4.x),
the ``new S engine'' (S version 4; @SPLUS{} 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 @emph{engines}.
For the remainder of this section, ``S'' refers to the S engines and not
the S language.
@menu
* Lexical scoping::
* Models::
* Others::
@end menu
@node Lexical scoping, Models, What are the differences between R and S?, What are the differences between R and S?
@subsection Lexical scoping
Contrary to other implementations of the S language, R has adopted the
evaluation model of Scheme.
This difference becomes manifest when @emph{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 @emph{static} scoping, R (like Scheme) has
adopted @emph{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:
@example
@group
cube <- function(n) @{
sq <- function() n * n
n * sq()
@}
@end group
@end example
Under S, @code{sq()} does not ``know'' about the variable @code{n}
unless it is defined globally:
@example
@group
S> cube(2)
Error in sq(): Object "n" not found
Dumped
S> n <- 3
S> cube(2)
[1] 18
@end group
@end example
In R, the ``environment'' created when @code{cube()} was invoked is
also looked in:
@example
@group
R> cube(2)
[1] 8
@end group
@end example
@c The following more `realistic' example illustrating the differences in
@c scoping is due to @email{tlumley@@u.washington.edu, Thomas Lumley}.
@c The function
@c @example
@c jackknife.lm <- function(lmobj) @{
@c n <- length(resid(lmobj))
@c jval <- sapply(1:n, function(i) coef(update(lmobj, subset = -i)))
@c (n - 1) * (n - 1) * var(jval) / n
@c @}
@c @end example
@c @noindent
@c does something useful in R, but does not work in S. In order to make it
@c work in S you need to explicitly pass the linear model object into the
@c function nested in @code{apply()}. If you don't and you are lucky you
@c will get @samp{Error: Object "lmobj" not found}. If you are unlucky
@c enough to have a linear model called @code{lmobj} in your global
@c environment you will get the wrong answer with no warning.
@c The following version works in S.
@c @example
@c jackknife.S.lm <- function(lmobj) @{
@c n <- length(resid(lmobj))
@c jval <- sapply(1:n,
@c function(i, lmobj) coef(update(lmobj, subset = -i)),
@c lmobj = lmobj)