-
Notifications
You must be signed in to change notification settings - Fork 86
/
Copy pathR-FAQ.texi
3437 lines (2781 loc) · 129 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
@paragraphindent 0
@c %**end of header
@dircategory Programming
@direntry
* R FAQ: (R-FAQ). The R statistical system FAQ.
@end direntry
@finalout
@include R-defs.texi
@c <FIXME>
@c Getting FAQ_YEAR from version.texi causes too much trouble for now,
@c as making ${top_builddir}/doc/FAQ in front-matter is done ahead of
@c building version.texi (which in turn currently needs having built R)
@c as it uses R_EXE to compute RWVERSION.
@c Need to revisit more generally whether we still want the front-matter
@c things.
@c For now, simply hard-wire the year again.
@c @include version.texi
@set FAQ_YEAR 2024
@c </FIXME>
@macro CRAN{}
@acronym{CRAN}
@end macro
@macro FORTRAN{}
FORTRAN
@end macro
@macro XML{}
@acronym{XML}
@end macro
@macro XSL{}
@acronym{XSL}
@end macro
@macro doi {d}
doi:@tie{}@url{https://doi.org/\d\, \d\}
@end macro
@titlepage
@title R @acronym{FAQ}
@subtitle Frequently Asked Questions on R
@author @I{Kurt Hornik}
@author and the R Core Team
@end titlepage
@ifinfo
@c We do not really see this in info, but in plain text output.
R FAQ @*
Frequently Asked Questions on R @*
@I{Kurt Hornik} and the R Core Team @*
@sp 2
@end ifinfo
@c @ifnothtml
@contents
@c @end ifnothtml
@ifnottex
@node Top
@top R FAQ
@c @ifhtml
@c @html
@c <h2>Frequently Asked Questions on R</h2>
@c <h3 style="text-align: center;">Kurt Hornik and the R Core Team</h3>
@c <hr/>
@c @end html
@c @end ifhtml
This document contains answers to some of the most frequently asked
questions about R.
@end ifnottex
@node Introduction
@chapter Introduction
@node Legalese
@section Legalese
Copyright @copyright{} 1998--2020 @I{Kurt Hornik} @*
@Rcopyright{2021}
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
@I{MERCHANTABILITY} or FITNESS FOR A PARTICULAR PURPOSE. See the
@acronym{GNU} General Public License for more details.
Copies of the @acronym{GNU} General Public License versions are
available at
@display
@url{https://www.R-project.org/Licenses/}
@end display
@node Obtaining this document
@section Obtaining this document
The latest version of this document is always available from
@display
@url{https://CRAN.R-project.org/doc/manuals/}
@end display
From there, you can obtain versions converted to
@url{https://CRAN.R-project.org/doc/manuals/R-FAQ.html,, @HTML{}} and
@url{https://CRAN.R-project.org/doc/manuals/R-FAQ.pdf,, PDF}.
@node Citing this document
@section Citing this document
In publications, please refer to this @acronym{FAQ} as @I{Hornik} and R Core Team
(@value{FAQ_YEAR}), ``The R @acronym{FAQ}'', and give the above,
@emph{official} @acronym{URL}:
@example
@group
@@Misc@{,
author = @{Kurt Hornik and the R Core Team@},
title = @{@{R@} @{FAQ@}@},
year = @{@value{FAQ_YEAR}@},
url = @{https://CRAN.R-project.org/doc/manuals/R-FAQ.html@}
@}
@end group
@end example
@node Notation
@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
@section Feedback
Feedback via email to @email{R-devel@@R-project.org} is most welcome.
Features specific to the Windows and macOS ports of R are
described in the
@url{https://CRAN.R-project.org/bin/windows/base/rw-FAQ.html, ``R for
Windows @acronym{FAQ}''} and the
@url{https://CRAN.R-project.org/bin/macosx/RMacOSX-FAQ.html, ``R for Mac
OS X @acronym{FAQ}''}. If you have information on Mac or Windows
systems that you think should be added to this document, please let us
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
@chapter R Basics
@node What is R?
@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 & @I{Wilks}' S (@pxref{What is S?}) and @I{Sussman}'s
@url{http://community.schemewiki.org/?scheme-faq, 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, @I{Ross Ihaka}}
and @email{Robert.Gentleman@@R-project.org, @I{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 archive, currently consisting of
@display
@I{John Chambers},
@I{Peter Dalgaard},
@I{Robert Gentleman},
@I{Kurt Hornik},
@I{Ross Ihaka},
@I{Tomas Kalibera},
@I{Michael Lawrence},
@I{Uwe Ligges},
@I{Thomas Lumley},
@I{Martin Maechler},
@I{Sebastian Meyer},
@I{Paul Murrell},
@I{Martyn Plummer},
@I{Brian Ripley},
@I{Deepayan Sarkar},
@I{Duncan Temple Lang},
@I{Luke Tierney}, and
@I{Simon Urbanek},
@end display
@noindent
plus
@I{Heiner Schwarte} up to October 1999,
@I{Guido Masarotto} up to June 2003,
@I{Stefano Iacus} up to July 2014,
@I{Seth Falcon} up to August 2015,
@I{Duncan Murdoch} up to September 2017,
@I{Martin Morgan} up to June 2021,
@I{Douglas Bates} up to March 2024, and
@I{Friedrich Leisch} up to April 2024.
R has a home page at @url{https://www.R-project.org/}. It is
@url{https://www.gnu.org/philosophy/free-sw.html, free software}
distributed under a @acronym{GNU}-style
@url{https://www.gnu.org/copyleft/copyleft.html, copyleft}, and an
official part of the @url{https://www.gnu.org/, @acronym{GNU}} project
(``@acronym{GNU} S'').
@node What machines does R run on?
@section What machines does R run on?
R is being developed for the Unix-like, 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-like (e.g., @uref{https://en.wikipedia.org/wiki/Unix-like})
platforms including @var{cpu}-linux-gnu for the @I{i386},
@I{amd64}/@I{x86_64}, @I{alpha}, @I{arm}, @I{arm64}, @I{hppa},
@I{mips}/@I{mipsel}, @I{powerpc}, @I{s390x} and @I{sparc}
@acronym{CPU}s (e.g.,
@url{https://buildd.debian.org/build.php?&pkg=r-base}),
@I{386-hurd-gnu},
@var{cpu}-@I{kfreebsd}-gnu for @I{i386} and @I{amd64},
@c <FIXME>
@c Not sure anymore ...
@c alpha-dec-osf4,
@c <COMMENT>
@c i386-freebsd reported by B. Gian James" <[email protected]> on
@c 2009-01-11
@c (Architecture: i386, OS: FreeBSD 7.1-PRERELEASE, Vendor: PC-BSD)
@c i386-freebsd,
@c but all recent reports are on x86_64
@c </COMMENT>
@c hppa-hp-hpux,
@c mips-sgi-irix,
@c </FIXME>
@I{i386-pc-solaris},
@I{rs6000-ibm-aix},
@I{sparc-sun-solaris},
@I{x86_64-apple-darwin},
@I{aarch64-apple-darwin},
@I{x86_64-unknown-freebsd} and
@I{x86_64-unknown-openbsd}.
@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?
@section What is the current version of R?
R uses a `major.minor.patchlevel' numbering scheme. Based on this,
there are the current release version of R (`r-release') as well as 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. New features are typically
introduced in r-devel, while r-patched is for bug fixes mostly.
See @url{https://CRAN.R-project.org/sources.html} for the current
versions of r-release, r-patched and r-devel.
@node How can R be obtained?
@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 @url{https://svn.R-project.org/R/}, the
R Subversion repository, but currently not via anonymous @I{rsync} (nor
CVS).
Tarballs with daily snapshots of the r-devel and r-patched development
versions of R can be found at
@url{https://cran.r-project.org/src/base-prerelease/}. An alternative
source is
@url{https://stat.ethz.ch/R/daily/}.
@c Sources are also available via anonymous rsync. Use
@c @example
@c rsync -rptC --delete rsync.R-project.org::@var{module} R
@c @end example
@c @noindent
@c to create a copy of the source tree specified by @var{module} in the
@c subdirectory @file{R} of the current directory, where @var{module}
@c specifies one of the three existing flavors of the R sources, and can be
@c one of @samp{r-release} (current released version), @samp{r-patched}
@c (patched released version), and @samp{r-devel} (development version).
@c The rsync trees are created directly from the master CVS archive and are
@c updated hourly. The @option{-C} and in the @command{rsync} command
@c is to cause it to skip the CVS directories. Further information on
@c @command{rsync} is available at @url{http://rsync.samba.org/rsync/}.
@c @c <NOTE>
@c @c Keep in sync with R-admin.
@c Note that the sources available via rsync do not include the recommended
@c packages, whereas these are included in the tarballs of released
@c versions. To install the appropriate sources for the recommended
@c packages, run @command{./tools/rsync-recommended} from the top-level of
@c the R sources that you pulled by rsync.
@c @c </NOTE>
@c The sources of the development version are also available via anonymous
@c CVS. See @url{http://anoncvs.R-project.org} for more information.
@node How can R be installed?
@section How can R be installed?
@node How can R be installed (Unix-like)
@subsection How can R be installed (Unix-like)
If R is already installed, it can be started by typing @kbd{R} at the
shell prompt (of course, provided that the executable is in your path).
If binaries are available for your platform (see @ref{Are there
Unix-like 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-like 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{} 90 compiler as well as a C compiler to
build R.
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,
@HTML{} versions of the R manuals (e.g., @file{R-exts.html}, the
``Writing R Extensions'' manual) are built in the @file{doc/manual}
subdirectory (if a suitable @command{texi2any} program was found).
Use @kbd{make pdf} to build PDF (Portable Document Format)
versions of the R manuals, including
@file{fullrefman.pdf} (an R object reference index). Manuals written in the
@acronym{GNU} @I{Texinfo} system can also be converted to @file{.info} files
suitable for reading online with Emacs or stand-alone @acronym{GNU}
Info; use @kbd{make info} to create these files.
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 info and PDF versions of the manuals, use
@kbd{make install-info} and @kbd{make install-pdf},
respectively.
@node How can R be installed (Windows)
@subsection How can R be installed (Windows)
The @file{bin/windows} directory of a @CRAN{} site contains binaries for
a base distribution and add-on packages from @CRAN{} to run on 64-bit
versions of Windows 7 and later on x86_64 chips (R 4.1.3 was the last
version of R to support 32-bit Windows). The Windows version of R was
created by @I{Robert Gentleman} and @I{Guido Masarotto}; @I{Brian
Ripley} and @I{Duncan Murdoch} made substantial contributions and it is
now being maintained by other members of the R Core team.
The same directory has links to snapshots of the r-patched and r-devel
versions of R.
See the @url{https://CRAN.R-project.org/bin/windows/base/rw-FAQ.html,
``R for Windows @acronym{FAQ}''} for more details.
@node How can R be installed (Mac)
@subsection How can R be installed (Mac)
The @file{bin/macosx} directory of a @CRAN{} site contains a standard
Apple installer package to run on macOS 10.13 (`High Sierra') or later,
and another which runs only on `Apple Silicon' Macs under macOS 11
(`@I{Big Sur}') or later. Once downloaded and executed, the installer will
install the current release of R and R.app, the macOS @acronym{GUI}.
This port of R for macOS is maintained by
@email{Simon.Urbanek@@R-project.org, @I{Simon Urbanek}} (and previously by
@I{Stefano Iacus}). The
@url{https://CRAN.R-project.org/bin/macosx/RMacOSX-FAQ.html, ``R for
macOS @acronym{FAQ}''} has more details.
Snapshots of the r-patched and r-devel versions of R are available as
Apple installer packages at @uref{https://mac.R-project.org}.
@node Are there Unix-like binaries for R?
@section Are there Unix-like binaries for R?
Binary distributions of R are available on many Unix-like OSes: only
some can be mentioned here so check your OS's search facilities to see
if one is available for yours.
The @file{bin/linux} directory of a @CRAN{} site contains R packages for
Debian and Ubuntu.
Debian packages, maintained by @I{Dirk Eddelbuettel}, have long been part of
the Debian distribution, and can be accessed through APT, the Debian
package maintenance tool. Use e.g.@: @code{apt-get install r-base
r-recommended} to install the R environment and recommended packages.
If you also want to build R packages from source, also run @code{apt-get
install r-base-dev} to obtain the additional tools required for this.
So-called ``backports'' of the current R packages for at least the
@dfn{stable} distribution of Debian are provided by @I{Johannes Ranke}, and
available from @CRAN{}. See
@url{https://CRAN.R-project.org/bin/linux/debian/index.html} for details on R
Debian packages and installing the backports, which should also be
suitable for other Debian derivatives. Native backports for Ubuntu are
provided by @I{Michael Rutter}, see
@url{https://CRAN.R-project.org/bin/linux/ubuntu/index.html} for
instructions.
R binaries for Fedora, maintained by @I{Tom ``Spot'' Callaway} and
@I{Iñaki Ucar}, are provided as part of the Fedora distribution and can
be accessed through @command{dnf}, the @abbr{RPM} installer/updater.
The Fedora R @abbr{RPM} is a ``meta-package'' which installs all the
user and developer components of R (available separately as
@code{R-core} and @code{R-core-devel}), as well as @code{R-java} and
@code{R-java-devel}, which ensures that R is configured for use with
Java. The R @abbr{RPM} also installs the standalone R math library
(@code{libRmath} and @code{libRmath-devel}), although this is not
necessary to use R. When a new version of R is released, there may be a
delay of up to 2 weeks until the Fedora @abbr{RPM} becomes publicly
available, as it must pass through the Fedora update process.
The Extra Packages for Enterprise Linux (@abbr{EPEL}) project
(@url{https://docs.fedoraproject.org/en-US/epel/}) provides ports of the
Fedora @abbr{RPM}s for @I{RedHat Enterprise Linux} and compatible
distributions (e.g., @I{CentOS Stream}, @I{Scientific Linux}, @I{Oracle
Linux}, @I{AlmaLinux}, or @I{Rocky Linux} among others).
@abbr{RPM}s for selection of R packages are also provided by Fedora.
Additional @abbr{RPM}s for R packages are maintained by @I{Iñaki Ucar}
on @I{Fedora Copr}. See @url{https://CRAN.R-project.org/bin/linux/fedora/}
for further details and installation instructions.
No other binary distributions are currently publicly available via
@CRAN{}.
@node What documentation exists for R?
@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
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 @ref{How can R be installed?}. An up-to-date @HTML{}
version is always available for web browsing at
@url{https://stat.ethz.ch/R-manual/}.
@c Printed copies of the R reference manual for some version(s) are
@c available from Network Theory Ltd, at
@c @c https: is untrusted
@c @url{http://www.network-theory.co.uk/R/base/}. For each set of manuals
@c sold, the publisher donates USD 10 to the R Foundation (@pxref{What is
@c the R Foundation?}).
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 @I{Bill Venables} and @I{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 ``@I{Kernighan} & @I{Ritchie} of R'', explains
evaluation, parsing, object oriented programming, computing on the
language, and so forth.
@item ``R Installation and Administration'' (@file{R-admin}).
@item ``R Internals'' (@file{R-ints})
is a guide to R's internal structures.
(Added in R 2.4.0.)
@end itemize
An annotated bibliography (Bib@TeX{} format) of R-related publications
can be found at
@display
@url{https://www.R-project.org/doc/bib/R.bib}
@end display
Books on R by R Core Team members include
@quotation
@I{John M. Chambers} (2008),
``Software for Data Analysis: Programming with R''.
@I{Springer}, New York, ISBN 978-0-387-75935-7,
@url{https://johnmchambers.su.domains/Rbook/}.
@I{Peter Dalgaard} (2008),
``Introductory Statistics with R'',
@I{2nd} edition.
@I{Springer}, ISBN 978-0-387-79053-4,
@url{http://publicifsv.sund.ku.dk/~pd/ISwR.html}.
@I{Robert Gentleman} (2008),
``R Programming for @I{Bioinformatics}''.
@I{Chapman & Hall/CRC}, @I{Boca Raton}, FL, ISBN 978-1-420-06367-7,
@url{https://bioconductor.org/help/publications/books/r-programming-for-bioinformatics/}.
@I{Stefano M. Iacus} (2008),
``Simulation and Inference for Stochastic Differential Equations: With R
Examples''.
@I{Springer}, New York, ISBN 978-0-387-75838-1.
@I{Deepayan Sarkar} (2007),
``Lattice: Multivariate Data Visualization with R''.
@I{Springer}, New York, ISBN 978-0-387-75968-5.
@I{W. John Braun} and @I{Duncan J. Murdoch} (2007),
``A First Course in Statistical Programming with R''.
Cambridge University Press, Cambridge, ISBN 978-0521872652.
@I{P. Murrell} (2005), ``R Graphics'',
@I{Chapman & Hall/CRC}, ISBN 1-584-88486-X,
@url{https://www.stat.auckland.ac.nz/~paul/RGraphics/rgraphics.html}.
@I{William N. Venables} and @I{Brian D. Ripley} (2002),
``Modern Applied Statistics with S'' (@I{4th} edition).
@I{Springer}, ISBN 0-387-95457-0,
@url{https://www.stats.ox.ac.uk/pub/MASS4/}.
@I{Jose C. Pinheiro} and @I{Douglas M. Bates} (2000),
``Mixed-Effects Models in S and S-Plus''.
@I{Springer}, ISBN 0-387-98957-0.
@end quotation
Last, but not least, Ross' and Robert's experience in designing and
implementing R is described in @I{Ihaka} & @I{Gentleman} (1996),
``R: A Language for Data Analysis and Graphics'',
@emph{Journal of Computational and Graphical Statistics}, @strong{5}, 299--314
(@doi{10.1080/10618600.1996.10474713}).
@node Citing R
@section Citing R
To cite R in publications, use
@example
@group
@@Manual@{,
title = @{R: A Language and Environment for Statistical
Computing@},
author = @{@{R Core Team@}@},
organization = @{R Foundation for Statistical Computing@},
address = @{Vienna, Austria@},
year = @var{YEAR},
url = @{https://www.R-project.org@}
@}
@end group
@end example
@noindent
where @var{YEAR} is the release year of the version of R used and can
determined as @code{R.version$year}.
Citation strings (or Bib@TeX{} entries) for R and R packages can also be
obtained by @code{citation()}.
@node What mailing lists exist for R?
@section What mailing lists exist for R?
Thanks to @email{Martin.Maechler@@R-project.org, Martin Maechler}, there
are several mailing lists devoted to R, including the following:
@table @code
@item R-announce
A moderated list for major 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
encountered using R, including using R packages in the standard R distribution
and on CRAN; announcements (not covered by `R-announce' or `R-packages');
the availability of new functionality for R and documentation of R;
and for posting nice examples and benchmarks.
@c about the development of R and the availability of new code.
@c enhancements and patches to the source code and documentation of R,
@c comparison and compatibility with S and @SPLUS{}, and for the posting of
@c nice examples and benchmarks.
@item R-devel
This list is for questions and discussion about code development in R.
@c discussions about the future of R, proposals of new functionality, and
@c pre-testing of new versions. It is meant for those who maintain an
@c active position in the development of R.
@item R-package-devel
A list which provides a forum for those developing R packages.
@end table
@noindent
Please read the @url{https://www.R-project.org/posting-guide.html,
posting guide} @emph{before} sending anything to any mailing list.
Note in particular that R-help is intended to be comprehensible to
people who want to use R to solve problems but who are not necessarily
interested in or knowledgeable about programming. Questions likely to
prompt discussion unintelligible to non-programmers (e.g., questions
involving C or C++) should go to R-devel.
Convenient access to information on these lists, subscription, and
archives is provided by the web interface at
@url{https://stat.ethz.ch/mailman/listinfo/}. One can also subscribe
(or unsubscribe) via email, e.g.@: to R-help by sending @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}.
Send email to @email{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 @samp{R-help} replaced by
@samp{R-announce}, @samp{R-packages}, and @samp{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
@ref{R Bugs} for more details.
See @url{https://www.R-project.org/mail.html} for more information on
the R mailing lists.
@c >> No longer want such comments and reports addressed to R-core :
@c The R Core Team can be reached at @email{R-core@@lists.R-project.org}
@c for comments and reports.
@c <FIXME>
@c As of 2017-10, accessing GMANE's gmane.comp.lang.r still says
@c Not all of Gmane is back yet ...
@c Hence comment out for the time being.
@c Many of the R project's mailing lists are also available via
@c @url{http://gmane.org, Gmane}, from which they can be read with a web
@c browser, using an NNTP news reader, or via RSS feeds. See
@c @uref{http://dir.gmane.org/index.php?prefix=gmane.comp.lang.r.}@: for
@c the available mailing lists, and @uref{http://www.gmane.org/rss.php} for
@c details on RSS feeds.
@c </FIXME>
@node What is CRAN?
@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{} main site at WU (@I{Wirtschaftsuniversit@"at Wien}) in Austria
can be found at the @acronym{URL}
@quotation
@c @multitable @columnfractions .45 .30
@c @item
@url{https://CRAN.R-project.org/}
@c @tab (Austria)
@c @end multitable
@end quotation
@noindent
and is mirrored daily to many sites around the world.
See @url{https://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
@I{bzipped} tar files, a wealth of additional contributed code, as well as
prebuilt binaries for various operating systems (Linux, Mac OS Classic,
macOS, and MS Windows). @CRAN{} also provides access to
documentation on R, existing mailing lists and the R Bug Tracking
system.
Since March 2016, ``old'' material is made available from a central
@CRAN{} archive server (@url{https://CRAN-archive.R-project.org/}).
Please always use the @acronym{URL} of the master site when referring to
@CRAN{}.
@node Can I use R for commercial purposes?
@section Can I use R for commercial purposes?
R is released under the
@url{https://www.gnu.org/licenses/old-licenses/gpl-2.0.html,,
@acronym{GNU} General Public License (@acronym{GPL}), version 2 or
version 3}. 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 @acronym{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
@url{https://opensource.org/osd, 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 Why is R named R?
@section Why is R named R?
The name is partly based on the (first) names of the first two R authors
(@I{Robert Gentleman} and @I{Ross Ihaka}), and partly a play on the name of the
Bell Labs language `S' (@pxref{What is S?}).
@c At the time the name was coined no one expected that the software would
@c get used outside of Auckland, so it seemed ok to make a joke of it.
@node What is the R Foundation?
@section 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, institutions 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
@url{https://www.R-project.org/foundation/} for more information.
@node What is R-Forge?
@section What is R-Forge?
R-Forge (@url{https://R-Forge.R-project.org/}) offers a central platform
for the development of R packages, R-related software and further
projects. It is based on @url{https://en.wikipedia.org/wiki/GForge, GForge} offering
easy access to the best in SVN, daily built and checked packages,
mailing lists, bug tracking, message boards/forums, site hosting,
permanent file archival, full backups, and total web-based
administration. For more information, see the R-Forge web page and
@I{Stefan Theu@ss{}l} and @I{Achim Zeileis} (2009), ``Collaborative software
development using R-Forge'', @url{https://journal.R-project.org/, ,
@emph{The R Journal}}, @strong{1}(1):9--14.
@node R and S
@chapter R and S
@node What is 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
(@abbr{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
@I{Richard A. Becker} and @I{John M. Chambers} (1984),
``S. An Interactive Environment for Data Analysis and Graphics,''
Monterey: @I{Wadsworth and Brooks/Cole}.
This is also referred to as the ``@emph{Brown Book}'', and of historical
interest only.
@item
@I{Richard A. Becker}, @I{John M. Chambers} and @I{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
@I{John M. Chambers} and @I{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
@I{John M. Chambers} (1998),
``Programming with Data,''
New York: @I{Springer},
ISBN 0-387-98503-4
(@url{https://johnmchambers.su.domains/Sbook/}).
This ``@emph{Green Book}'' describes version 4 of S, a major revision of
S designed by @I{John Chambers} to improve its usefulness at every stage
of the programming process.
@end itemize
See @url{https://johnmchambers.su.domains/papers/96.7.ps}
for further information on the ``Evolution of the S Language''.
@c There is a huge amount of user-contributed code for S, available at the
@c @url{http://lib.stat.cmu.edu/S/, S Repository} at @acronym{CMU}.
@c The @url{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?
@section What is @sc{S-Plus}?
@SPLUS{} is a value-added version of S sold by
@url{https://www.tibco.com/, TIBCO Software Inc} as `@I{TIBCO Spotfire S+}'.
See @url{https://en.wikipedia.org/wiki/S-PLUS} for more information.
@node What are the differences between 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.
@node Lexical scoping
@subsection Lexical scoping
Contrary to other implementations of the S language, R has adopted an
evaluation model in which nested function definitions are lexically
scoped. This is analogous to the evaluation model in 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). In S, the
values of free variables are determined by a set of global variables
(similar to C, there is only local and global scope). In R, they are
determined by the environment in which 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 @}