03-install-packages.Rmd

---
title: "Installing R Packages"
output:
  dcTemplate::dc_lesson_template:
    fig_width: 6
    fig_height: 6
    highlight: pygments
---


```{r knitr_init, echo = FALSE, cache = FALSE}
library(knitr)

## Global options
options(max.print = "75")
opts_chunk$set(cache = TRUE,
               prompt = FALSE,
               tidy = TRUE,
               comment = "> #",
               message = FALSE,
               warning = FALSE)
opts_knit$set(width = 75)
```

## Installing R Packages within RStudio

You can install R packages with RStudio in the browser, like you would on a desktop-RStudio-session, by using `install.packages`. Let's launch a *verse* Docker container to run RStudio as we did previously, and try to install the gapminder package, and load it and peek at the data.

~~~
# install package
install.packages('gapminder')

# load library
library(gapminder)

# peek at data
head(gapminder)
~~~

Great! Now we have the Gapminder package installed so we can work with the whole dataset. But wait, what is going to happen when we exit the container? It will be deleted and since we didn't save this version of the Docker image, when we open another instance of the container we will have to install the Gapminder package again if we want to use it. 

To avoid this, lets save the image by running `Docker commit` and then the next time we run a Docker container we can run an instance of this image which includes the Gapminder package. To do this we need to open another terminal window **before** we close our Docker container. 

To save this specific version of the image we need to find this containers specific hash. We can see this by typing the following command in the new terminal window, and it will list all running Docker containers:

~~~
docker ps
~~~

The output should look something like what is shown below, and the specific hash for this container is the alphanumeric text in the first column.

~~~
4a6a528b35da        rocker/verse        "/init"             2 minutes ago       Up 2 minutes        0.0.0.0:8787->8787/tcp   silly_meninsky
~~~

Now to save this version of the image, in the new terminal window type:

~~~
docker commit -m "verse + gapminder" 4a6a528b35da verse_gapminder
~~~

To save this Docker image we have to provide a commit message to describe the change that we have made to the image. We do this by passing the `-m` flag followed by the message in quotes. We also need to provide the specific hash for this version of the container (here 4a6a528b35da). Finally, we also provide a new name for the new image. We called this new image `verse_gapminder`.

We can see that we now have two Docker images saved on our laptops by typing:

~~~
docker images 
~~~

~~~
REPOSITORY                           TAG                 IMAGE ID            CREATED             SIZE
verse_gapminder                      latest              bb38976d03cf        57 seconds ago      1.955 GB
rocker/verse                         latest              0168d115f220        3 days ago          1.954 GB
~~~

You can test that this worked by running a Docker container from each image. You will find that the Gapminder package is only installed on the verse_gapminder image and not on the rocker/verse image.

### Installing Dependencies external to the R system

Many R packages have dependencies external to R, for example GSL, GDAL, JAGS and so on. To install these on a running rocker container you need to go to the docker command line (in a new terminal window) and type the following:

```{r external-dependencies, eval=FALSE}
docker ps # find the ID of the running container you want to add a package to
docker exec -it <container-id> bash # a docker command to start a bash shell in your container
apt-get install libgsl0-dev # install the package, in this case GSL
```

If you get an error message when running `apt-get install libgsl0-dev` try running
`apt-get update` first.

To save these changes go to yet another terminal window and save as above using `docker commit`, e.g.
```
docker commit -m "verse + gapminder + GSL" <container id>  verse_gapminder_gsl
```
Now you can go to the terminal window in which you typed the `docker exec` command and close the docker container
by typing `exit`.


## Challenge Questions 
You or someone else will probably want to check at some point later, what the 
docker image contains. Write a README file which documents the details of the 
`verse_gapminder_gsl` image. For the R packages you can use the output of
`installed.packages()`.


Next: Go to [Lesson 04 Dockerhub](04-Dockerhub.html) or back to the 
[main page](http://jsta.github.io/r-docker-tutorial/).