Introduction

This tutorial is intended to teach users how to install R packages on Atmosphere (for a brief intro to Atmosphere you can view this video). These packages could be publicly available on CRAN (Comprehensive R Archive Network) or they could be packages developed for personal use. Although this tutorial is specific to R packages, many of the same principles also apply when installing other software on an Atmosphere instance.

Preparation

In order to install an R package on an Atmosphere instance, some prep work must first be done.

1. If the R package you would like to install is available on CRAN (Comprehensive R Archive Network), skip to Step 4.
2. If the R package is not available on CRAN, you must download the source file. For this tutorial we will be using the package randomForest_4.6-6.tar.gz (click here to download), but the steps will be similar for any R package.
3. Upload the R package (which most likely has a tar.gz extension) and any other necessary files to your directory in the CyVerse Data Store. If you have a lot of files, it's recommended that you create a dedicated folder for them. See Downloading and Uploading Data for the different methods of how to get data into the Data Store.
4. Decide how you would like to access your Atmosphere instance. If you prefer interacting with a graphical desktop, you can use VNC Viewer. If you prefer using ssh, then you can access your instance using Terminal on a Mac or PuTTY on a PC. Either method will work for this tutorial, but VNC Viewer is recommended for those who are not command-line savvy.

Launching the instance

Now that you have all the necessary software uploaded to your data store on CyVerse you're ready to launch your Atmosphere instance.

1. Log in to Atmosphere using your iPlant credentials.
2. Click the "Launch New Instance" button.
3. Search for "RStudio", and choose the image titled "R 3.01 and RStudio 0.9.943". This image has R 3.0.1 installed on it, along with all basic R packages. 
   1. This tutorial was written with the R 3.01 image, but it should work fine with any image that has R installed. You may want to use a newer image.
      
4. Choose an instance size and launch the instance. For this tutorial, you can use a tiny instance.
5. Wait for the instance to finish building. This could take anywhere from 5 to 30 minutes.

Once your instance has finished launching, Atmosphere will supply you with an IP address for accessing it. If you're using VNC Viewer to do this, make sure to append ":1" to the end of the IP address so that VNC knows which port to use. See Launching a New Instance.

Transferring files to the instance

Now that you have access to the base R image, you'll need to transfer all of the necessary files over to it. If you're using VNC Viewer, you have the option to use iDROP or CyberDuck for this. However, we will be using iCommands, which is far more reliable. For this tutorial we only have one file, randomForest_4.6-6.tar.gz, which is attached above.

1. Within the instance. open up a terminal to begin the file transfer process.

2. Create a new folder in your home directory called "randomForest":

   mkdir randomForest
   cd randomForest
   

   

3. Initialize iCommands:

   iinit
   Enter the host name (DNS) of the server to connect to: data.iplantcollaborative.org
   Enter the port number: 1247
   Enter your irods user name: myiplantusername
   Enter your irods zone: iplant
   Enter your current iRODS password: myiplantpassword
   

   

4. If you have a lot of files to transfer over to your instance, you can mount your Data Store by following the tutorial found here. However, since we only have one file to transfer, we will use the "iget" command to transfer a single file.

   iget /iplant/home/myiplantusername/randomForest_4.6-6.tar.gz
   

Installing the R Package

Once you have all of your files transferred over to your instance, you're ready to begin the installation process.

1. Launch R and install the R package. If the package is available on CRAN, use the first block of code. If you are using the file transferred in the last step, install it from source using the second block of code.

   Installing from CRAN

   R
   install.packages("randomForest")
   

   Installing from source code

   R
   install.packages("/iplant/home/myiplantusername/randomForest/randomForest_4.6-6.tar.gz", type="source")
   

   R will ask you if it is okay to install the package in a personal directory. Say yes by typing "y" when prompted.

   

   (Notice that the file path for the install package is different than the code mentioned above, make sure that your file paths are correct)

2. The R package should now be installed in the directory /home/myiplantusername/R/x86_64-unknown-linux-gnu-library/3.0/. We need to move it to /usr/local/lib/R/library.

   sudo mv /home/myiplantusername/R/x86_64-unknown-linux-gnu-library/3.0/randomForest /usr/local/lib/R/library
   

3. Run the following command to verify that the package was installed correctly.

   R
   library(randomForest)
   

   

If no errors pop up, that means the package was successfully installed. You can now use the randomForest package (or whatever R package you installed) to perform whatever function you need. And if you like, you can request that your instance be imaged so that other iPlant users can benefit from your installation.

Requesting Imaging

Once you have verified that everything in your instance is working as intended, you're ready to request that it be imaged.

If you have any other files (e.g. documentation, readme files, etc.) that you want to be preserved, move them to a safe location that won't be wiped upon imaging (e.g. the /opt/ directory).

sudo mv /home/myiplantusername/randomForest/readme.txt /opt/randomForest/doc/

Once everything is in its correct place, you can return to Atmosphere's website and click the "Image" button. For more information on requesting imaging, see Requesting an Image of an Instance.