Purpose in short: to ease the pain when installing/updating R
and R
packages.
Note: I mainly work under CentOS and Windows environment, so, I am not familiar with Mac OS system.
Basic R configuration
Before we start talking about installing packages, it would be better to do some basic configuration relating to the R
library. There are several advantages of doing this:
- help you understand how
R
starts up - make it easy to set or change the configurations (saving time)
- make it easy to manage your R enrionment
Basic R environment variables
There are several basic enrionment variables for R. These variables are not the same as variables of the system (like those in .bashrc
or .bash_profile
).
Variables for important directories for R
.
-
HOME
, user’s home directory. This can be got frompath.expand('~')
orSys.getenv('HOME')
.1
2
3
4
5
6
7
8
9
10# windows
> path.expand('~')
[1] "C:/Users/NIU/Documents"
> path.expand('~')
[1] "C:/Users/NIU/Documents"
# Linux
> Sys.getenv('HOME')
[1] "/home/niuyw" -
R_HOME
, the directory in which R is installed. This can be got fromR.home()
orSys.getenv('R_HOME')
.1
2
3
4
5
6
7
8
9
10
11
12# windows
> Sys.getenv('R_HOME')
[1] "C:/PROGRA~1/R/R-35~1.3"
> R.home()
[1] "C:/PROGRA~1/R/R-35~1.3"
# Linux
> R.home()
[1] "/home/niuyw/software/R.3.5.3/lib64/R"
> Sys.getenv('R_HOME')
[1] "/home/niuyw/software/R.3.5.3/lib64/R" -
Current working directory. This is reported by
getwd()
.1
2> getwd()
[1] "D:/test/R"
Variables for libraries.
R_LIBS
, a colon-separated list of directoriesR_LIBS_USER
, a colon-separated list of directoriesR_LIBS_SITE
, a colon-separated list of directories
By default R_LIBS
and R_LIBS_SITE
are unset, and R_LIBS_USER
is set to directory R/R.version$platform-library/x.y
of the home directory (or Library/R/x.y/library
for CRAN macOS builds), for R.x.y.z.
1 | # windows |
Package search paths
Search paths for packages are paths where R
search/install/uninstall packages. This can be reported by .libPaths()
function.
1 | # windows |
.libPaths()
can also be used to set the search paths for packages.
1 | .libPaths(new) |
If called with argument new
, the library search path is set to the existing directories in unique(c(new, .Library.site, .Library))
and this is returned. If given no argument, a character vector with the currently active library trees is returned.
.Library
is a character string giving the location of the default library, the ‘library’ subdirectory ofR_HOME
..Library.site
is a (possibly empty) character vector giving the locations of the site libraries, by default the ‘site-library’ subdirectory ofR_HOME
(which may not exist).
At startup, the library search path is initialized from the environment variables: first R_LIBS, then R_LIBS_USER and finally R_LIBS_SITE. Only directories which exist at the time will be included.
1 | # Linux |
As can be seen, both R_LIBS
and R_LIBS_SITE
are empty by default. Although variable R_LIBS_USER
was set, the directory was not included in .libPaths()
since the directory did not exist.
Calling .libPaths('')
(with an empty string) will remove all other entries but the library sub-directory of the distribution.
R startup
R: Initialization at Start of an R Session has a clear descriptions about how R starts up.
In R, the startup mechanism is as follows.
Unless
--no-environ
was given on the command line, R searches for site and user files to process for setting environment variables. The name of the site file is the one pointed to by the environment variableR_ENVIRON
; if this is unset,R_HOME/etc/Renviron.site
is used (if it exists, which it does not in a ‘factory-fresh’ installation). The name of the user file can be specified by theR_ENVIRON_USER
environment variable; if this is unset, the files searched for are.Renviron
in the current or in the user’s home directory (in that order).Then R searches for the site-wide startup profile file of R code unless the command line option
--no-site-file
was given. The path of this file is taken from the value of the R_PROFILE environment variable (after tilde expansion). If this variable is unset, the default isR_HOME/etc/Rprofile.site
, which is used if it exists (which it does not in a ‘factory-fresh’ installation). This code is sourced into the base package. Users need to be careful not to unintentionally overwrite objects in base, and it is normally advisable to uselocal
if code needs to be executed: see the examples.Then, unless
--no-init-file
was given, R searches for a user profile, a file of R code. The path of this file can be specified by theR_PROFILE_USER
environment variable (and tilde expansion will be performed). If this is unset, a file called.Rprofile
is searched for in the current directory or in the user’s home directory (in that order). The user profile file is sourced into the workspace.Note that when the site and user profile files are sourced only the base package is loaded, so objects in other packages need to be referred to by e.g.
utils::dump.frames
or after explicitly loading the package concerned.R then loads a saved image of the user workspace from ‘.RData’ in the current directory if there is one (unless --no-restore-data or --no-restore was specified on the command line).
Next, if a function
.First
is found on the search path, it is executed as.First()
. Finally, function.First.sys()
in the base package is run. This callsrequire
to attach the default packages specified byoptions]
(“defaultPackages”). If the methods package is included, this will have been attached earlier (by function.OptRequireMethods()
) so that namespace initializations such as those from the user workspace will proceed correctly.A function
.First
(and.Last
) can be defined in appropriate ‘.Rprofile’ or ‘Rprofile.site’ files or have been saved in ‘.RData’. If you want a different set of packages than the default ones when you start, insert a call tooptions
in the.Rprofile
orRprofile.site
file. For example,options(defaultPackages = character())
will attach no extra packages on startup (only the base package) (or setR_DEFAULT_PACKAGES=NULL
as an environment variable before running R). Usingoptions(defaultPackages = "")
orR_DEFAULT_PACKAGES=""
enforces the R system default.On front-ends which support it, the commands history is read from the file specified by the environment variable
R_HISTFILE
(default ‘.Rhistory’ in the current directory) unless --no-restore-history or --no-restore was specified.The command-line option --vanilla implies --no-site-file, --no-init-file, --no-environ and (except for
R CMD
) --no-restore
There are two sorts of files used in startup: environment files which contain lists of environment variables to be set, and profile files which contain R code.
At startup, R will try to read a number of files in a particular order. The contents in these files would determine how R performs in the session opened.
Files in three folders are important in this process:
-
R_HOME
R_HOME/etc/Renviron.site
R_HOME/etc/Rprofile.site
-
HOME
.Renviron
.Rprofile
-
Current working directory.
.Renviron
.Rprofile
R only uses one .Rprofile
and one .Renviron
in any session:
.Rprofile
file in your current project overrides.Rprofile
inR_HOME
andHOME
. Likewise,.Rprofile
inHOME
overrides.Rprofile
inR_HOME
.- The same applies to
.Renviron
.Renviron
The .Renviron
file is used to store system variables. We can create this file in HOME
or in current working directory.
A typical use of the .Renviron
file is to specify the R_LIBS
path:
1 | # Linux |
This variable points to a directory where R packages will be installed. When install.packages
is called, new packages will be stored in R_LIBS
.
.Rprofile
.Rprofile
file contains R scirpts that run each time R starts.
Use help(Rprofile)
in R to get help information about the setting.
We can set the CRAN mirror in .Rprofile
.
1 | ## local creates a new, empty environment |
From: Efficient R programming - 3.3 R startup
The RStudio mirror is a virtual machine run by Amazon’s EC2 service, and it syncs with the main CRAN mirror in Austria once per day. Since RStudio is using Amazon’s CloudFront, the repository is automatically distributed around the world, so no matter where you are in the world, the data does not need to travel very far, and is therefore fast to download.
Install/update packages
From CRAN
Choose mirror before installing packages. See the mirrors available: https://cran.r-project.org/mirrors.html
1 | chooseCRANmirror() |
Or specify the mirror when installing the packages.
1 | install.packages('RMySQL', repos='https://mirrors.tuna.tsinghua.edu.cn/CRAN/') |
Or through Biocmanager
1 | BiocManager::install('ggplot2') |
From Bioconductor
Choose mirror. See the mirror list here: https://www.bioconductor.org/about/mirrors/
1 | ## Change default Bioconductor mirrors |
R < 3.5.0
1 | source("https://bioconductor.org/biocLite.R") |
Or through package BiocInstaller
.
1 | library(BiocInstaller) |
R >= 3.5.0
1 | if (!requireNamespace("BiocManager", quietly = TRUE)) |
Package BiocManager
can also be used to install packages not in Bioconductor.
BiocManager::repositories()
returns the Bioconductor and CRAN repositories used by install()
.
See: https://cran.r-project.org/web/packages/BiocManager/vignettes/BiocManager.html
Specify a version
Use the version=
argument to update all packages to a specific Bioconductor version
1 | BiocManager::install(version="3.7") |
A special version, version="devel"
, allows use of Bioconductor packages that are under development.
From Github
1 | # check the devtools package |
Or through Biocmanager
1 | BiocManager::install('MadsAlbertsen/ampvis2') |
From source
The packages can also be installed from source. First the package should be downloaded.
1 | install.packages("M3Drop_3.05.00.tar.gz", type="source") |
Update R
Reference
Upgrade packages after installing a new R
Copy the library to the new library path. Then use the code to update packages.
1 | update.packages(checkBuilt=TRUE, ask=FALSE) |
Upgrade packages of Bioconductor
Install packages from a newer version of Bioconductor.
1 | BiocManger::install(version = 'xx') |
Special tools
Since the troublesome work of installing/updating R and R packages, there are tools specialized for this job.
rvcheck
rvcheck, created by Guangchuang Yu, is a simple and easy-to-use package to check R/Package version.
1 | # install |
installr
installr, created by Tal Galili, includes functions for installing softwares from within R (currently, only on Windows OS), with a special focus on R itself.
1 | # install |
Further reading: Updating R from R (on Windows) – using the {installr} package
Reference
- R: Search Paths for Packages
- R: Initialization at Start of an R Session
- Efficient R programming - 3.3 R startup
- Rbloggers - Fun with .Rprofile and customizing R startup
- Rbloggers - Package Paths in R
- Quick-R - Customizing Startup
Change log
- 20180703: create the note.
- 20190717: complete the note.