RPR-Installation
Installing R and RStudio
(Notation; installing R and RStudio; packages; first experiments.)
Abstract:
This unit works through the installation of R and RStudio and introduces R's packages of additional functions.
|
Objectives:
|
Outcomes:
|
Deliverables:
- Time management: Before you begin, estimate how long it will take you to complete this unit. Then, record in your course journal: the number of hours you estimated, the number of hours you worked on the unit, and the amount of time that passed between start and completion of this unit.
- Journal: Document your progress in your Course Journal. Some tasks may ask you to include specific items in your journal. Don't overlook these.
- Insights: If you find something particularly noteworthy about this unit, make a note in your insights! page.
Prerequisites:
This unit builds on material covered in the following prerequisite units:
Contents
Evaluation
Evaluation: NA
Contents
R
Introduction
The R statistics environment and programming language is an exceptionally well engineered, free (as in free speech) and free (as in free beer) platform for data manipulation and analysis. The number of functions that are included by default is large, there is a very large number of additional, community-generated analysis modules that can be simply imported from dedicated sites (e.g. the Bioconductor project for molecular biology data), or via the CRAN network, and whatever function is not available can be easily programmed. The ability to filter and manipulate data to prepare it for analysis is an absolute requirement in research-centric fields such as ours, where the strategies for analysis are constantly shifting and prepackaged solutions become obsolete almost faster than they can be developed. Besides numerical analysis, R has very powerful and flexible functions for plotting graphical output.
Be realistic. One can't learn a programming language in a single day.
Work through this material unit by unit; constant repetition will bring the principles into active memory. Make sure you understand every step. Taking shortcuts and/or cramming everything into a single, desperate effort will not get you far.
Before you begin: Notation and Formatting
In this tutorial, I use specific notation and formatting to mean different things.
If you see footnotes[1], click on the number to read more.
This is normal text for explanations. It is written in a proportionally spaced font.
Code formatting is for code examples, file- and function names, directory paths etc. Code is written in a monospaced font[2].
Bold emphasis and underlining are to mark words as particularly important.
Sometimes I highlight examples of the right way to do something in green.
... and examples of the wrong way to do something may be highlighted red.
Task:
Tasks and exercises are described in boxes with a blue background. You have to do them, they are not optional. If you have problems, you must contact your instructor, or discuss the issue on the mailing list. Don't simply continue. All material builds on previous material, and evaluation is cumulative.
What could possibly go wrong? ... Click to expand.→
These sections have information about issues I encounter more frequently. They are required reading when you need to troubleshoot problems but also give background information that may be useful to avoid problems in the first place.
Click to collapse.↗
"Metasyntactic variables": When I use notation like <Year> in instructions, you type the year, the whole year and nothing but the year (e.g the four digits 2020). You never type the angle brackets! I use the angle brackets only to indicate that you should not type Year literally, but substitute the correct value. You might encounter this notation as <path>, <filename>, <firstname lastname> and similar. To repeat: if I specify
<your name>
... and your name is Elcid Barrett, You type
Elcid Barret
... and not your name or <Elcid Barret> or similar. (Oh the troubles I've seen ...)
The sample code on this page sometimes copies text from the console, and sometimes shows the actual commands only. The > character at the beginning of the line is always just R's input prompt, it tells you that you can type something now - you never actually type > at the beginning of a line. If you read:
> getwd()
... you need to type:
getwd()
If a line starts with [1] or similar, this is R's output on the console.[3] The # character marks the following text as a comment which is not executed by R. These are lines that you do not type. They are program output, or comments, not commands.
- Characters
- Different characters mean different things for computers, and it is important to call them by their right name.
/◁ this is a forward-slash. It leans forward in the reading direction.\◁ this is a backslash. It leans backward in the reading direction.( )◁ these are parentheses.[ ]◁ these are (square) brackets.< >◁ these are angle brackets.{ }◁ these are (curly) braces."◁ this, and only this is a quotation mark or double quote. All of these are not: “”„«» . They will break your code. Especially the first two are often automatically inserted by MSWord and hard to distinguish.[4]'◁ this, and only this is a single quote. All of these are not: ‘’‚‹› . They will break your code. Especially the first two are often automatically inserted by MSWord and hard to distinguish.
MSWord is not useful as a code editor.
The environment
In this section we discuss how to download and install the software, how to configure an R session and how to work in the R environment.
Install R
Task:
1. Navigate to CRAN (the Comprehensive R Archive Network)[5] and follow the link to Download R for your computer's operating system.
2. Download a precompiled binary (or "build") of the R "framework" to your computer and follow the instructions for installing it. Make sure that the program is the correct one for your version of your operating system.
3. Launch R.
The program should open a window – this window is called the "R console" – and greet you with its input prompt, awaiting your input:
>
Task:
Once you see that R is running correctly, you may quit the program for now.
What could possibly go wrong?...
- I can't install R.
- Make sure that the version you downloaded is the right one for your operating system. Also make sure that you have the necessary permissions on your computer to install new software.
Install RStudio
RStudio is a free IDE (Integrated Development Environment) for R. RStudio is a wrapper[6] for R and as far as basic R is concerned, all the underlying functions are the same, only the user interface is different (and there are a few additional functions that are very useful e.g. for managing projects).
Here is a small list of differences between R and RStudio.
- pros (some pretty significant ones actually)
- Integrated version control.
- Support for "projects" that package scripts and other assets.
- Syntax-aware code colouring.
- A consistent interface across all supported platforms. (Base R GUIs are not all the same for e.g. Mac OS X and Windows.)
- Code autocompletion in the script editor. (Depending on your point of view this can be a help or an annoyance. I used to hate it. After using it for a while I find it useful.)
- "Function signatures" (a list of named parameters) displayed when you hover over a function name.
- The ability to set breakpoints for debugging in the script editor.
- Support for knitr, and rmarkdown; also support for R notebooks ... (This supports "literate programming" and is actually a big advance in software development)
- Support for R notebooks.
- cons (all minor actually)
- The tiled interface uses more desktop space than the windows of the R GUI.
- There are sometimes (rarely) situations where R functions do not behave in exactly the same way in RStudio.
- The supported R version is not always immediately the most recent release.
Task:
- Navigate to the RStudio Website.
- Find the right version of the RStudio Desktop installer for your computer, download it and install the software.
- Open RStudio.
- Focus on the bottom left pane of the window, this is the "console" pane.
- Type
getwd().
This prints out the path of the current working directory. Make a (mental) note where this is. We usually always need to change this "default directory" to a project directory.
Packages
R has many powerful functions built in, but one of it's greatest features is that it is easily extensible. Extensions have been written by legions of scientists for many years, most commonly in the R programming language itself, and made available through CRAN–The Comprehensive R Archive Network or through the Bioconductor project.
A package is a collection of code, documentation and (often) sample data. To use packages, you need to install the package (once). You can then use all of the package's functions by prefixing them with the package name and a double colon (eg. package::function()); that's the preferred way. Or you can load all of the package's functions with a library(package) command, and then use the functions without a prefix. That's less typing, but it's also less explicit and you may end up constantly wondering where exactly a particular function came from. In the teaching code for this course, I use the package::function() idiom wherever possible, since it is more explicit.
To repeat:
install.packages("<package-name")downloads the package files from CRAN and places them in the appropriate location on your computer.packagename::function()is usually the preferred idiom to use functionality that is providedby a package.- For some packages, or when you use a particular package a lot, you can "load" the package with
library(packagename)(note: no quotation marks in this case.) Then you can use the functions simply by typingfunction().
You can get an overview of installed and loaded packages by opening the Package Manager window from the Packages & Data Menu item. It gives a list of available packages you currently have installed, and identifies those that have been loaded at startup, or interactively. But note, a package does not have to be loaded to be used.
Task:
- Navigate to http://cran.r-project.org/web/packages/ and read the page.
- Navigate to http://cran.r-project.org/web/views/ (the curated CRAN task-views).
- Follow the link to Genetics and read the synopsis of available packages. The library
sequinrsounds useful, but check first whether it has been installed.
library() opens a window that lists the packages that are installed on your computer; search() shows which one are currently loaded.
> library() > search() [1] ".GlobalEnv" "tools:RGUI" "package:stats" "package:graphics" [5] "package:grDevices" "package:utils" "package:datasets" "package:methods" [9] "Autoloads" "package:base"
- In the Packages tab of the lower-right pane in RStudio, confirm that
seqinris not yet installed. - Follow the link to seqinr to see what standard information is available with a package. Then follow the link to the Reference manual to access the documentation pdf. This is also sometimes referred to as a "vignette" and contains usage hints and sample code.
Read the help for vignette. Note that there is a command to extract R sample code from a vignette, to experiment with it.
> ?vignette
Install seqinr from the closest CRAN mirror and load it for this session. Explore some functions.
> ??install
> ?install.packages
> install.packages("seqinr") # Note: the parameter is a quoted string!
also installing the dependency ‘ade4’
trying URL 'https://cran.rstudio.com/bin/macosx/mavericks/contrib/3.2/ade4_1.7-2.tgz'
Content type 'application/x-gzip' length 3365088 bytes (3.2 MB)
==================================================
downloaded 3.2 MB
trying URL 'https://cran.rstudio.com/bin/macosx/mavericks/contrib/3.2/seqinr_3.1-3.tgz'
Content type 'application/x-gzip' length 2462893 bytes (2.3 MB)
==================================================
downloaded 2.3 MB
The downloaded binary packages are in
/var/folders/mx/ld0hdst54jjf11hpcjh8snfr0000gn/T//Rtmpsy5GMx/downloaded_packages
> library(help="seqinr")
> ls("package:seqinr")
[1] "a" "aaa" "AAstat"
[4] "acnucclose" "acnucopen" "al2bp"
[...]
[205] "where.is.this.acc" "words" "words.pos"
[208] "write.fasta" "zscore"
> ?seqinr::a
> seqinr::a("Tyr")
[1] "Y"
> seqinr::words(3, c("A", "G", "C", "U"))
[1] "AAA" "AAG" "AAC" "AAU" "AGA" "AGG" "AGC" "AGU" "ACA" "ACG" "ACC" "ACU" "AUA" "AUG"
[15] "AUC" "AUU" "GAA" "GAG" "GAC" "GAU" "GGA" "GGG" "GGC" "GGU" "GCA" "GCG" "GCC" "GCU"
[29] "GUA" "GUG" "GUC" "GUU" "CAA" "CAG" "CAC" "CAU" "CGA" "CGG" "CGC" "CGU" "CCA" "CCG"
[43] "CCC" "CCU" "CUA" "CUG" "CUC" "CUU" "UAA" "UAG" "UAC" "UAU" "UGA" "UGG" "UGC" "UGU"
[57] "UCA" "UCG" "UCC" "UCU" "UUA" "UUG" "UUC" "UUU"
What could possibly go wrong?...
- The installation fails.
- You might see an error message such as this:
Warning message:package ‘XYZ’ is not available (for R version 3.2.2)
- This can mean several things:
- The package is not available on CRAN. Try Bioconductor instead or Google for the name to find it.
- The package requires a newer version of R than the one you have. Upgrade, or see if a legacy version exists.
- A comprehensive set of reasons and their resolution is here on stackoverflow.
- We have seen the following on Windows systems when typing
library(help="seqinr") Error in formatDL(nm, txt, indent = max(nchar(nm, "w")) + 3) :incorrect values of 'indent' and 'width'
Anecdotally this was due to a previous installation problem with a mixup of 32-bit and 64-bit R versions, although another student told us that the problem simply went away when trying the command again. Whatever: Make sure you have the right R version installed for your operating system. Uninstall and reinstall when in doubt. Conflicting libraries can be the source of strange misbehaviour.
Task:
- The fact that these methods work, shows that the package has been downloaded, installed, its functions are now available with the package name prefix and any datasets it contains can be loaded. Just like many other packages,
seqinrcomes with a number of datafiles. Try:
?data
data(package="seqinr") # list the available data
data(aaindex, package="seqinr") # load ''aaindex''
?aaindex # what is this?
aaindex$FASG890101 # two of the indices ...
aaindex$PONJ960101
# Lets use the data: plot amino acid single-letter codes by hydrophobicity
# and volume. The values come from the dataset. Copy and paste the commands,
# we'll discuss them in detail later.
plot(aaindex$FASG890101$I,
aaindex$PONJ960101$I,
xlab="hydrophobicity", ylab="volume", type="n")
text(aaindex$FASG890101$I,
aaindex$PONJ960101$I,
labels=a(names(aaindex$FASG890101$I)))
- Now, just for fun, let's use functions from the seqinr package functions to download a sequence and calculate some statistics (however, not to digress too far, without further explanation at this point). Copy the code below and paste it into the R-console.
seqinr::choosebank("swissprot")
mySeq <- seqinr::query("mySeq", "N=MBP1_YEAST")
mbp1 <- seqinr::getSequence(mySeq)
seqinr::closebank()
x <- seqinr::AAstat(mbp1[[1]])
barplot(sort(x$Compo), cex.names = 0.6)
We could have "loaded" the package with library(), and then used the functions without prefix. Less typing, but also less explicit.
library(seqinr)
choosebank("swissprot")
mySeq <- query("mySeq", "N=MBP1_YEAST")
mbp1 <- getSequence(mySeq)
closebank()
x <- AAstat(mbp1[[1]])
barplot(sort(x$Compo), cex.names = 0.6)
In general we will be using the idiom with the package prefix throughout the course.
The function requireNamespace() is useful because it does not produce an error when a package has not been installed. It simply returns TRUE if successful or FALSE if not. Therefore one can use the following code idiom in R scripts to avoid downloading the package every time the script is called.
if (! requireNamespace("seqinr", quietly=TRUE)) {
install.packages("seqinr")
}
# You can get package information with the following commands:
library(help = seqinr) # basic information
browseVignettes("seqinr") # available vignettes
data(package = "seqinr") # available datasets
Note that install.packages() takes a (quoted) string as its argument, but library() takes a variable name (without quotes). New users usually get this wrong :-)
Note that the Bioconductor project has its own installation system, the Biocmanager::install() function. It is explained here.
Note, just to mention it at this point: to install packages that are not on CRAN or Bioconductor, you need the devtools package.
Finding packages
One of the challenges of working with R is the overabundance of options. CRAN has over 10,000 packages and Bioconductor has over 1,300 more. How can you find ones that are useful to your work? There's actually a package to help you do that, the sos package on CRAN. Try this:
if (! requireNamespace(sos, quietly=TRUE)) {
install.packages("sos")
}
library(help = sos) # basic information
browseVignettes("sos") # available vignettes
sos::findFn("moving average")
- Or ...
- Read a CRAN Task View for your area of interest ...
- ... or the Bioconductor Views;
- Search on "Metacran" ([ "regex" example here"]) ...
- ... or "MRAN" ("regex" example here", not that the results are not identical);
- ... and, as always, Google.
Self-evaluation
Question 1
What is the purpose of this code?
if (! requireNamespace("seqinr", quietly = TRUE)) {
install.packages("seqinr")
}
Why not just use ...
install.packages("seqinr")
... in your script instead?
Answer ...
This code idiom is useful in scripts, to ensure a package is installed before we try to use its functions. If we would simply use install.packages("seqinr"), the package would be downloaded from CRAN every time the script is run. That would make our script slow, and require available internet access for the script to run.
In the code above, the package is downloaded only when requireNamespace() returns FALSE, which presumably means the package has not yet been downloaded.
Further reading, links and resources
Notes
- ↑ ... and when you click on the arrow to the left, this will take you back to where you came from.
- ↑ Proportional fonts are for elegant document layout. Monospaced fonts are needed to properly align characters in columns. For code and sequences, we alway use monospaced font. Code editors always use monospaced fonts, but since I need to eMail a lot of code and sequences, I have also set my eMail client to use monospaced font by default (Courier, or Monaco). I highly encourage you to do the same.
- ↑
[1]means: the following is the first element of a vector - and this is often the only one. - ↑ Never, ever edit code in MS Word. Use R or RStudio. Actually, don't use notepad or TextEdit either.
- ↑ You can also use one of the mirror sites, if CRAN is down - for example the mirror site at the University of Toronto. A choice of mirror sites is listed on the R-project homepage.
- ↑ A "wrapper" program uses another program's functionality in its own context. RStudio is a wrapper for R since it does not duplicate R's functions, it runs the actual R in the background.
About ...
Author:
- Boris Steipe <boris.steipe@utoronto.ca>
Created:
- 2017-08-05
Modified:
- 2020-09-17
Version:
- 1.1.1
Version history:
- 1.1.1 Introduce two-column layout
- 1.1 Change from require() to requireNamespace() and use <package>::<function>() idiom.
- 1.02 Maintenance
- 1.0.1 Removed mention of Sweave - obsolete, and broken link. Added mention of "literate programming".
- 1.0 Completed to first live version
- 0.1 Material collected from previous tutorial
This copyrighted material is licensed under a Creative Commons Attribution 4.0 International License. Follow the link to learn more.
