Notebook

Jupyter and R: Getting Started¶

Author: Michael Mooney (mooneymi@ohsu.edu)¶

Introduction¶

This document will tell you how to quickly set up your computer so you can start using and creating Jupyter notebooks for the R language.

What you will need:

The conda package manager (this will also install Python)
That's it!

Step 1. Install the `conda` Package Manager¶

Conda Documentation: http://conda.pydata.org/docs/get-started.html
Download Anaconda here: https://www.continuum.io/downloads
Download Conda here: http://conda.pydata.org/miniconda.html
'Conda for R': https://www.continuum.io/conda-for-r
'Jupyter and conda for R' (from Continuum Analytics Developer Blog): https://www.continuum.io/blog/developer/jupyter-and-conda-r

The first link above will help you decide what version of conda to install. Links 2 and 3 will take you to pages were you can download installers for Anaconda or Conda (also called Miniconda). Simply download the appropriate installer (available for Windows, Mac, or Linux) and run it.

Step 2. Use `conda` to install R and r-essentials¶

Conda is a command line program, so you will first need to open a shell (a.k.a. 'Terminal' on Mac OS X, or 'Command Prompt' on Windows). On the command line, type the following command to install R and r-essentials, a bundle of R packages useful for data science (including the IRKernel needed for creating Jupyter Notebooks with R):

conda install -c r r-essentials

Using R and R essentials with conda

Step 3. Locate the Anaconda R Installation and Libraries¶

You should be aware of where conda installed R and the R libraries. This is particularly important if you have other versions of R installed, or if you ever run into a situation where you need to install a package manually (not using the conda package manager). Anaconda is usually installed in your user directory. On my Windows machine is located at: C:\Users\Michael\Anaconda2. On my Mac OS X machine it is located at: /Users/mooneymi/anaconda.

Within this directory there should be an R subdirectory holding the bin (R executables) and library (R packages) subdirectories.

Step 4. Install Additional R Packages (Optional)¶

Use `conda` to install R packages¶

Some R packages are already available from within Conda, so you can install them very easily. The example below installs the gdata R package:

conda config --add channels r
conda install r-gdata

What these commands do:

The conda config command adds the R channel (where conda searches for packages).
The conda install command finds and installs the gdata package into the default Conda environment.

Because conda for R is relatively new, not all R packages are available within conda. Developers are working on making all packages on CRAN available through conda:

However, even if a package is not available in conda there are a couple of options for installing it and making it available to the Anaconda R installation.

Use the `skeleton` Command to Build a Conda Package from a CRAN R Package¶

You can build a Conda package for any R package using the skeleton command. Once you have this Conda package on your local machine, you can install it easily with conda. Below is an example for installing the colorRamps package (read the discussion below the commands):

conda config --add channels r
conda skeleton cran colorRamps
conda build r-colorramps/
conda install r-colorramps --use-local

What these commands do:

The conda config command is the same as in the previous section. You don't have to repeat it if you've already added the r channel.
The conda skeleton command creates a sub-directory, called 'r-colorramps' in the current working directory. The 'recipe' for building the package is saved in this directory.
Note: conda changes the name of the package for consistency and to avoid name conflicts (colorRamps is changed to r-colorramps). But within R you will still load the package with library(colorRamps).
The conda build command creates a conda package in the 'conda-bld' subdirectory of your Anaconda installation directory. For instance, on my machine the file 'r-colorramps-2.3-r3.1.3_0.tar.bz2' was created in the 'C:\Users\Michael\Anaconda2\conda-bld\win-64' directory.
Note: if your R installation is not the most up-to-date version, you may have to specify the version of R to build against. For example, the conda build command above should be changed to:

conda build --R 3.1.3 r-colorramps/

You can check that the package was installed with the following command, which lists all installed Conda packages:

conda list

Conda Command Reference: [http://conda.pydata.org/docs/commands.html](http://conda.pydata.org/docs/commands.html)

Install the R package manually¶

You can install any R package from within R as you would do normally (using the install.packages() R function). You can also install an R package from the command line, making sure the package is installed in the correct library folder (the one for the Anaconda R installation).

The one disadvantage to installing packages manually, is that conda will not be aware of the package and not keep track of its version, etc. (it won't show up when running conda list).

Step 5. Start the Jupyter Notebook Server¶

To edit or create a new Jupyter notebook, you first must start the notebook server. From the command line, you should first move to the directory that holds your notebooks (or where you want to save a new notebook), then type the following:

jupyter notebook

This will start the notebook server, and will open a new tab in your Web browser that shows a list of the notebooks in the current directory.

Jupyter Screenshot

Step 6. Select an Existing Notebook or Create a New One¶

Now you can click on the notebook that you want to view/edit (it will open in a new tab). Or if you want to create a new notebook, click on the 'New' button at the upper-right and select 'R' to use the R kernel.