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.
5 of 11 3.6 Testing 3 WINDOWS XP
(d) In the .emacs buffer paste the following text:
;;Load ESS (load "C:/Program Files/emacs-22.3/site-lisp/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) You will have to retype all of the single quotes (’) in Emacs. (f) Save the .emacs file (Ctrl-x Ctrl-s) or (File→Save) (g) 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. (h) You should now see a .emacs file in C:\ (i) Quit Emacs
3.6 Testing 1. This is the last phase. You’re almost done. 2. Open Emacs 3. Now Type Ctrl-x 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 (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.... i. If you get an error and you do not see the R process, double check that you typed the path in right in Step 3.2.1g (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. Test ESS (a) Now put your cursor in the bottom buffer and create a new buffer called test.R. i. Type Ctrl-x Ctrl-f. In the bottom of the Emacs buffer you will see Find file: C:\AND A PATH NAME. Type: C:\Documents and Settings\YOURUSERNAME\Desktop\Rdownloads\test.R (b) Bottom buffer should now say test.R i. If the buffer has a bunch of text in it, read it over if you’d like, but delete it all so that you just have a blank buffer (c) In bottom buffer type:
6 of 11 4 WINDOWS VISTA
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 a separate window called R Graphics Device (h) Just close Emacs and the R Graphics Device Window for now and say yes to kill active processes (i) CONGRATS! Go Grab a celebratory beverage! You have successfully installed Emacs, R, and ESS.
4 Windows Vista
4.1 How-To Test System 1. Windows Vista SP1 2. GNU Emacs 22.3.1 3. R 2.8.0 4. ESS-5.3.8 5. Estimated time (Due to the volatility of Vista, total install time is inestimable)
4.2 Preparation 1. Grab a soothing beverage, or two, to help you cope throughout this process 2. Vista appears to be very emotional. Be prepared to reinforce Vista’s constant need of approval (as you will be doing this many times). 3. Edit your system settings (a) Go to Control Panel → System → Advanced System Settings is on the left side (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 (d) Under System variables (e) Scroll down to PATH and highlight it (f) Select Edit (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
7 of 11 4.3 Downloads 4 WINDOWS VISTA
4.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
4.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.
4.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. (d) In the emacs buffer paste the following text:
8 of 11 4.6 Testing 4 WINDOWS VISTA
;;Load ESS (load "C:/Program Files/emacs-22.3/site-lisp/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) You will have to retype all of the single quotes (’) in Emacs. (f) Save the emacs file (Ctrl-x Ctrl-s) or (File→Save) (g) 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. (h) You should now see a emacs file in C:\ (i) Quit Emacs
4.6 Testing 1. This is the last phase. You’re almost done. 2. Open Emacs 3. Now Type Ctrl-x 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 (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.... i. If you get an error and you do not see the R process, double check that you typed the path in right in Step 4.2.3g (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. Test ESS (a) Now put your cursor in the bottom buffer and create a new buffer called test.R. i. Type Ctrl-x Ctrl-f. In the bottom of the Emacs buffer you will see Find file: C:\AND A PATH NAME. Type in C:\Users\YOURUSERNAME\Desktop\Rdownloads\test.R (b) Bottom buffer should now say test.R i. If the buffer has a bunch of text in it, read it over if you’d like, but delete it all so that you just have a blank buffer (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
9 of 11 7 HOW TO USE EMACS AND ESS
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 a separate window called R Graphics Device 6. Just close Emacs and the R Graphics Device Window for now and say yes to kill active processes 7. CONGRATS! Go Grab a celebratory beverage! You have successfully installed Emacs, R, and ESS.
5 Operating Emacs and ESS
Now that you have Emacs, ESS, and R integrated into one powerful system it might be helpful to know a little about what Emacs and ESS are. Take a few minutes to skim over this brief introduction to Emacs and ESS.
6 What are Emacs and ESS?
Emacs is a text editor. It has many customizable options (that I have already set you up with the essentials). ESS is a way for Emacs to speak to R. By running the R process through ESS you can save your work as well as any commenting that you make within your .R file. A .R file is the extension that ESS recognizes as an “R” file. All files you create should have the extension .R. By hitting Meta-x R (Meta is the Alt key) you are starting the R process. You type your syntax in the .R file and can run the commands by using shortcut keystrokes. You also have the ability to run commands directly in the R process (buffer) as you would in the R GUI.
7 How to use Emacs and ESS
Knowing how to navigate in Emacs and ESS before learning R will be helpful. Note that there are many other keystrokes not included here. In Aquamacs, you can use some of the general MacOS shortcuts, but Emacs for Windows has limitations. Things like Page Up and Page Down work, but you mostly will have to use the Emacs keystrokes.
10 of 11 7 HOW TO USE EMACS AND ESS
Basic keystrokes for Emacs: The following table includes basic shortcuts for Emacs and ESS.
Action MacOS MacOS & Windows Native MacOS Shortcuts Native Emacs Shortcuts Open file Cmd-o C-x C-f Save file Cmd-s C-x C-s New buffer Cmd-n C-x 5 2 Close Emacs C-x C-c Close buffer Cmd-w Split buffer Cmd-2 C-x 2 Switch buffers in split mode C-x o Remove split buffer Cmd-1 C-x 1 Select All Cmd-a Copy,Cut,Paste Cmd-c, Cmd-x, Cmd-v Delete from cursor C-k Yank here C-y Move 1 buffer to the right C-x
When you have a .R file open you have the ability to use ESS shortcut keystrokes to run the commands in R. The keystrokes can be found in the ESS menu when you have a .R file open; these are just a few of the more essential actions.
Action Keystroke Run current line C-c C-j Run highlighted region C-c C-r Run entire buffer C-c C-b Run current line and go to R buffer C-c M-j Run highlighted region and go to R buffer C-c M-r Run enter buffer and go to R buffer C-c M-b Comment # Arrow to assign objects in R [VERY HELPFUL] Shift- [underscore symbol]
11 of 11