forked from rstats-wtf/what-they-forgot
-
Notifications
You must be signed in to change notification settings - Fork 0
/
12_r-startup.Rmd
117 lines (84 loc) · 4.83 KB
/
12_r-startup.Rmd
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
# R Startup
R has been designed to be used from shared computing resources such as linux
servers. As a result R's startup offers lots of opportunity for customization;
both for every user of a system as well as for each individual user. However
this flexibility comes at a cost: _complexity_.
And for sure, R's startup procedures are complex:
```{r, echo = FALSE, fig.cap = "R Startup flowchart - [Thomas Lin Pedersen](https://twitter.com/thomasp85/status/961553618196418560)"}
knitr::include_graphics("images/R-startup.svg")
```
However most R users can ignore the majority of this complexity and focus on two main files.
1. [`.Renviron`](#renviron) - which contains environment variables to be set in R sessions.
2. [`.Rprofile`](#rprofile) - which contains R code to be run in each session.
These files are R specific instances of a broader family of customization files
commonly referred to as [dotfiles](https://www.quora.com/What-are-dotfiles). These are used to tailor the behavior of many programs, particularly those with roots in
the unix command line.
Many people store their [dotfiles on GitHub](https://dotfiles.github.io/) and a
great way to find inspiration for what you can do with them is to browse other
people's dotfile repositories.
One way to find R specific dotfiles is to do a [GitHub search for
filename:.Rprofile](https://github.com/search?q=filename%3A.Rprofile+interactive&type=Code).
## `.Renviron`
The `.Renviron` file is most useful for defining sensitive information such as
API keys (such as GitHub or twitter) as well as R specific environment
variables like the history size (`R_HISTSIZE=100000`) and default library locations `R_LIBS_USER`.
The `.Renviron` file contains lists of environment variables to set. This is
_not_ R code, it uses a format similar to that used on the command line shell.
The easiest way to edit `.Renviron` is by running `usethis::edit_r_environ()`.
A simple example of a `.Renviron` file is
```shell
R_HISTSIZE=100000
GITHUB_PAT=abc123
R_LIBS_USER=~/R/%p/%v
```
```{block type="rmdinfo"}
[Try the activity](https://raw.githubusercontent.com/rstats-wtf/wtf-startup/master/01_startup_spartan.R) `usethis::use_course("rstd.io/wtf-source-package")`
to learn how to set a GitHub PAT to your `.Renviron` and then use it with `usethis::use_github()` to upload a project to GitHub.
```
## `.Rprofile`
The `.Rprofile` file contains R code to be run when R starts up. It is run
after the `.Renviron` file is sourced. Typically `.Rprofile` is located in the
users' home directory (`~/.Rprofile`), however a different location can be
configured by setting the `R_PROFILE_USER` environment variable.
The easiest way to edit `.Rprofile` is by running `usethis::edit_r_profile()`.
Some common things people often add to their `.RProfile`
1. Set a default CRAN mirror
3. Write a welcome message
2. Customize their R prompt
4. Change options, screen width, numeric display
5. Load frequently used packages (but be very careful)
6. Aliases / shortcuts for frequently used functions
### Reproducibility
A good rule of thumb is you should only put things in your `.Rprofile` that you
run interactively in the R terminal. If it ever appears in a R script or R
Markdown file it should _not_ be in your `.Rprofile`.
If you set these options in your
`.Rprofile`, then try to run one of your scripts on another system without your
`.Rprofile` it will no longer be reproducible. Some problematic examples are
loading packages _used_ in analysis (such as `dplyr` or `ggplot2`) or
changing default options which change the _value_ of outputs, such as
`options(stringsAsFactors = FALSE)`.
In addition because the `.Rprofile` is run by _every_ R process (including
those started by R itself) it is important to guard most of the code with
`interactive()`, so it is only run in interactive sessions (sessions you are
controlling with a terminal).
A simple example of a `.Rprofile` is
```r
options(repos = c(CRAN = "https://cran.rstudio.org"))
if (interactive()) {
options(width = 120)
}
```
```{block type="rmdinfo"}
[Try the activity](https://raw.githubusercontent.com/rstats-wtf/wtf-startup/master/02_startup_spartan.R) `usethis::use_course("rstd.io/wtf-source-package")`
to learn how to create a `.Rprofile` with a default CRAN repository and add a startup message to it.
```
## Disabling startup files
You can run R without any startup files by using the `--vanilla` argument when
starting R. In RStudio you can do this by checking the option `Project Options -> Disable .Rprofile execution on
session start / resume`. You can also selectively disable only the user or site
`.Rprofile` with `--no-init-file` and `--no-site-file` respectively, and disable
the environment files with `--no-environ`.
```{block type = 'rmdwarning'}
Both `.Renviron` and `.Rprofile` _must_ end with a newline character. If they do not the last line with be ignored without a warning or error.
```