Emacs and R Integration via ESS: Installation How-To Caroline R.H. Wiley December 29, 2008 Contents 1 Installation 1 2 Mac OS 10.5 2 2.1 How-To Test System .................................... 2 2.2 Preparation ......................................... 2 2.3 Downloads .......................................... 2 2.4 Installation ......................................... 2 2.5 Emacs and R Integration ................................. 3 2.6 Testing ........................................... 3 3 Windows XP 4 3.1 How-To Test System .................................... 4 3.2 Preparation ......................................... 4 3.3 Downloads .......................................... 5 3.4 Installation ......................................... 5 3.5 Emacs and R Integration ................................. 5 3.6 Testing ........................................... 6 4 Windows Vista 7 4.1 How-To Test System .................................... 7 4.2 Preparation ......................................... 7 4.3 Downloads .......................................... 8 4.4 Installation ......................................... 8 4.5 Emacs and R Integration ................................. 8 4.6 Testing ........................................... 9 5 Operating Emacs and ESS 10 6 What are Emacs and ESS? 10 7 How to use Emacs and ESS 10 1 Installation This How-To is broken down into 3 sections: Mac OS, Windows XP, and Windows Vista. The procedures and requirements for each OS are slightly different, however the main components are 1 2 MAC OS 10.5 the same for all. You will be using R through a text editor called Emacs. Emacs and R are integrated through a program called Emacs Speaks Statistics (ESS). Although you may prefer to use R through its native GUI, for the workshop we will use Emacs since there is more utility in doing so. There are other text editor options as well, but given the general computing level of the attendees, it will be easier if we are all using the same program. 2 Mac OS 10.5 2.1 How-To Test System 1. Mac OS 10.5.7 2. Aquamacs Emacs 1.5 3. R 2.8.0 4. ESS-5.3.8 5. Estimated total time, including download time (20-30min) 2.2 Preparation 1. Check if X11 is installed. X11 is the graphics viewer that R uses for Mac OS. R and Emacs will technically run without X11 open, but you will not be able to preview your graphics in the current R session. (a) Go to Finder → Applications. If X11.app does not appear in your Applications list then X11 was not installed when your OS was installed. (b) To install X11, insert your 10.5 OS disk and navigate through the menu to install X11. It should be under Custom Options or something similarly named. If you bought your Mac with 10.5, X11 should already be installed. If you have trouble finding X11 from your 10.5 install disk, skip this part for now, continue with the How-To and I will assist with X11 afterwards. 2.3 Downloads 1. Create a folder on your Desktop called Rdownloads. This will make the installation process easier. Download all files to this folder. 2. Download R from http://cran.r-project.org/ (a) Click MacOS X (b) Download R-2.8.0.dmg 3. Download Aquamacs from http://aquamacs.org/download.shtml (Aquamacs is Emacs for Macs with “Mac flavor.” It makes switching from the Mac OS to Emacs very easy.) (a) Download the Universial Binary Aquamacs Emacs 1.5.dmg 4. Download Emacs Speaks Statistics (ESS) from http://ess.r-project.org/downloads/ess/ (a) Download ess-5.3.8.tgz 2.4 Installation 1. Install R; accept all defaults (a) Open R.app and make sure it opens correctly (b) If so, Quit R (CMD-Q) 2. Unpack ESS to /Users/YOURUSERNAME (a) You are unpacking it to your HOME DIR, which is ˜/ or /Users/YOURUSERNAME 2 of 11 2.5 Emacs and R Integration 2 MAC OS 10.5 (b) Once unpacked you should have a folder in your HOME DIR named ess-5.3.8 3. Install Aquamacs; accept all defaults (a) Open Aquamacs.app and make sure it opens correctly (b) If so, Quit Aquamacs (CMD-Q) 4. YOU NOW HAVE ALL THE NECESSARY COMPONENTS INSTALLED! On to the Emacs and R integration. 2.5 Emacs and R Integration 1. Set up your Emacs initialization file (a) Open Aquamacs (b) Type Ctrl-x Ctrl-f. In the bottom of the Aquamacs buffer you will see Find file: ˜/ (c) Type in .emacs i. This creates a file called .emacs in your HOME DIR, which is the Emacs (Aquamacs) setup or initialization file. This is a hidden file and so can only be accessed when in a text editor like Emacs. (d) In the .emacs buffer paste the following text: ;;Load ESS (load "/Users/YOURUSERNAME/ess-5.3.8/lisp/ess-site") ;;Customizations to make Emacs better (custom-set-variables ’(column-number-mode t) ’(global-font-lock mode t nil (font-lock)) ’(global-hl-line-mode t nil (hl-line)) ’(pc-select-meta-moves-sexps t) ’(pc-select-selection-keys-only t) ’(pc-selection-mode t nil (pc-select)) ’(save-place t nil (saveplace)) ’(show-paren-mode t nil (paren)) ’(transient-mark-mode t)) (e) Be sure to replace YOURUSERNAME with your Username (f) You will have to retype all of the single quotes (’) in Emacs. (g) Save the .emacs file (CMD-S) (h) If you get an error in the bottom of the buffer regarding a coding system, you did not replace all of the single quotes. Double-check and re-save. (i) Quit Aquamacs 2.6 Testing 1. This is the last phase. You’re almost done. 2. Open Aquamacs 3. Now Type CMD-2; this splits the screen into 2 buffers 4. Test R process (a) Put your cursor in the top buffer if it’s not already there (b) Type Alt-x R (Shift-r) and then hit Enter 3 of 11 3 WINDOWS XP (c) You’ll see a prompt at the bottom of the buffer for a starting data directory. Just hit Enter (d) You should see an R process that starts off with R version 2.8.0.... (e) Scroll down to the first command line and type in 4+2 and hit Enter (f) [1] 6 should show up on next line 5. Open X11; Let it fully load 6. Switch back to Aquamacs 7. Test ESS (a) Now put your cursor in the bottom buffer and save the empty buffer as test.R. Just go to File → Save As (b) Bottom buffer should now say test.R (c) In bottom buffer type: x<-c(1:10) y<-c(21:30) (d) Highlight the two lines of code and type Ctrl-c Ctrl-r i. If the bottom of your buffer says Process to load into R:, hit Enter (e) Type: plot(x,y) (f) Keep cursor on that line and type Ctrl-c Ctrl-j (g) A simple scatterplot of x and y should appear in X11 8. Just quit Aquamacs for now and say yes to kill active processes 9. CONGRATS! Go Grab a celebratory beverage! You have successfully installed Emacs, R, and ESS. 3 Windows XP 3.1 How-To Test System 1. Windows XP SP2 2. GNU Emacs 22.3.1 3. R 2.8.0 4. ESS-5.3.8 5. Estimated time, including downloads: 20-30min 3.2 Preparation 1. Edit your system settings (a) Go to Control Panel → System (b) Click on the Advanced tab, then click Environment Variables (c) Under User variables Select New i. Create HOME and type C:\ in the Path location (Variable value) (d) Under System variables (e) Scroll down to PATH and highlight it (f) Select Edit 4 of 11 3.3 Downloads 3 WINDOWS XP (g) Go to end of the text. DO NOT DELETE WHAT IS IN THERE. YOU ARE SIMPLY ADDING DIRECTORIES TO WHAT’S ALREADY THERE. i. Once you cursor to the end Type: ;C:\Program Files\R\R-2.8.0\bin ii. OK out of System Settings 3.3 Downloads 1. Create a folder on your Desktop called Rdownloads. This will make the installation process easier. Download all files to this folder. 2. Download R from http://cran.r-project.org/ (a) Click Windows→base (b) Download R-2.8.0-win32.exe 3. Download GNU Emacs from http://ftp.gnu.org/pub/gnu/emacs/windows (a) Download the .zip file emacs-22.3-bin-i386.zip 4. Download Emacs Speaks Statistics (ESS) from http://ess.r-project.org/downloads/ess/ (a) Download ess-5.3.8.zip 3.4 Installation 1. Install R; accept defaults (can change options for icons and the such, just don’t change Destination Path) (a) Open R and make sure it opens correctly (b) If so, Close it. 2. Install Emacs (a) Extract emacs-22.3 to C:\Program Files (b) There should now be a folder emacs-22.3 in \Program Files (c) Create a Desktop shorcut: i. Go to C:\Program Files\emacs-22.3\bin ii. Right-click on runemacs.exe and click Create Shortcut iii. Place shorcut on Desktop and rename to emacs 3. Unzip ESS (a) Extract ess-5.3.8 to C:\Program Files\emacs-22.3\site-lisp (b) There should now be a folder ess-5.3.8 in C:\Program Files\emacs-22.3\site-lisp 4. YOU NOW HAVE ALL THE NECESSARY COMPONENTS INSTALLED! On to the Emacs and R integration. 3.5 Emacs and R Integration 1. Set up your Emacs initialization file (a) Open Emacs (b) Type Ctrl-x Ctrl-f. In the bottom of the Aquamacs buffer you will see Find file: C:\AND A PATH NAME (c) Delete the path and Type in C:\.emacs i. This creates a file called .emacs in your HOME DIR, which is the Emacs setup or initialization file.