{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Jupyter and R: Getting Started\n", "\n", "#### Author: Michael Mooney (mooneymi@ohsu.edu)\n", "\n", "## Introduction\n", "\n", "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.\n", "\n", "What you will need:\n", "\n", "1. The `conda` package manager (this will also install Python)\n", "2. That's it!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 1. Install the `conda` Package Manager\n", "\n", "1. Conda Documentation: [http://conda.pydata.org/docs/get-started.html](http://conda.pydata.org/docs/get-started.html)\n", "2. Download Anaconda here: [https://www.continuum.io/downloads](https://www.continuum.io/downloads)\n", "3. Download Conda here: [http://conda.pydata.org/miniconda.html](http://conda.pydata.org/miniconda.html) \n", "4. 'Conda for R': [https://www.continuum.io/conda-for-r](https://www.continuum.io/conda-for-r)\n", "5. 'Jupyter and conda for R' (from Continuum Analytics Developer Blog): [https://www.continuum.io/blog/developer/jupyter-and-conda-r](https://www.continuum.io/blog/developer/jupyter-and-conda-r)\n", "\n", "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. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 2. Use `conda` to install R and r-essentials\n", "\n", "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):\n", "\n", " conda install -c r r-essentials\n", "\n", "[Using R and R essentials with conda](http://conda.pydata.org/docs/r-and-r-essentials.html)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 3. Locate the Anaconda R Installation and Libraries\n", "\n", "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**.\n", "\n", "Within this directory there should be an **R** subdirectory holding the **bin** (R executables) and **library** (R packages) subdirectories." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 4. Install Additional R Packages (Optional)\n", "\n", "### Use `conda` to install R packages\n", "\n", "Some R packages are already available from within Conda, so you can install them very easily. The example below installs the gdata R package:\n", "\n", " conda config --add channels r\n", " conda install r-gdata\n", "\n", "What these commands do:\n", "1. The `conda config` command adds the R channel (where `conda` searches for packages).\n", "2. The `conda install` command finds and installs the gdata package into the default Conda environment." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Because `conda` for R is relatively new, **not all R packages are available within `conda`**. Developers are working on making all packages on [CRAN](https://cran.r-project.org/) available through `conda`: \n", "\n", "- [Preliminary Support for R with conda](https://www.continuum.io/content/preliminary-support-r-conda)\n", "- [Conda for Data Science](https://www.continuum.io/content/conda-data-science)\n", "\n", "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. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Use the `skeleton` Command to Build a Conda Package from a CRAN R Package\n", "\n", "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):\n", "\n", " conda config --add channels r\n", " conda skeleton cran colorRamps\n", " conda build r-colorramps/\n", " conda install r-colorramps --use-local\n", "\n", "What these commands do:\n", "1. 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.\n", "2. 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.\n", "3. 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)`.\n", "4. 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. \n", "5. 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:\n", "\n", "\n", " conda build --R 3.1.3 r-colorramps/\n", "\n", "You can check that the package was installed with the following command, which lists all installed Conda packages:\n", "\n", " conda list\n", "\n", "
\n", "Conda Command Reference: [http://conda.pydata.org/docs/commands.html](http://conda.pydata.org/docs/commands.html)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Install the R package manually\n", "\n", "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). \n", "\n", "- [https://stat.ethz.ch/R-manual/R-devel/library/utils/html/install.packages.html](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/install.packages.html)\n", "- [https://cran.r-project.org/doc/manuals/r-release/R-admin.html#Installing-packages](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#Installing-packages)\n", "\n", "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`)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Step 5. Start the Jupyter Notebook Server\n", "\n", "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:\n", "\n", " jupyter notebook\n", "\n", "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.\n", "\n", "![Jupyter Screenshot](./images/jupyter_tree_screenshot.png)" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "## Step 6. Select an Existing Notebook or Create a New One\n", "\n", "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Last Updated: 28-Jan-2016" ] } ], "metadata": { "kernelspec": { "display_name": "R", "language": "R", "name": "ir" }, "language_info": { "codemirror_mode": "r", "file_extension": ".r", "mimetype": "text/x-r-source", "name": "R", "pygments_lexer": "r", "version": "3.3.2" } }, "nbformat": 4, "nbformat_minor": 1 }