S-Plus/R with ESS

helpdesk@stat.rice.edu

What is ESS? Why is it important?

ESS (Emacs Speaks Statistics) is an Emacs extension. It is designed to make S-Plus/R easier to use, especially on Unix platforms. This guide will lead you through some of the most useful ESS features.

How to install ESS?

ESS is installed under helpdesk. To make use of ESS, you need to add the following line to your .emacs file in /home/username/ folder:

(load "/home/helpdesk/trial/ess/ess-site")

ESS provides 50+ functions which are bound to keys like C-c C-f. Since these key-bindings are not easy enough to remember, we have bound some of the most important functions to F1, F9, F10, F11, F12. If you would like to use these bindings, download the sample .emacs file (created by Blair Christian) from http://www.stat.rice.edu/ helpdesk/dotfiles/.emacs.blair to your /home/username folder. You can use wget url command, where url is the url location of the file. Throughout this guide, I will use these bindings, instead of the standard ones.

A Step by step Tutorial:

Starting ESS

Start emacs with command: emacs &
Enter command M-x R

M-x means hold down the Meta key and press x. The meta key is usually located near the space bar on a SUN keyboard. If you are using a windows 102/105 keyboard with X-win32, the right Alt key is usually used as the meta key. If there is no meta key at all, press Esc, release it, then press x. You can also use M-x S to start S-Plus.

If ESS is properly installed, emacs will open a buffer named *R* and start an instance of R in it. If emacs returns an error, check your .emacs file. The easiest way to correct your .emacs problem is to use the sample .emacs file. You can copy the sample .emacs file directly from the helpdesk if you are on stat007, just use command:

cp /home/helpdesk/download/ess.emacs ~/.emacs

Interact with the S-Plus/R process

Enter

vector1 <- c(1,2,3)<CR>

Now, you would like to enter another command:

vector2 <- c(3,3,3)<CR>

You have several ways to input the second command. Instead of inputing the whole command again, you can use one of the following features of ESS:

Edit the previous command directly
Click on the previous command, make appropriate changes, press <CR>. ESS will copy the edited command to the last command line and execute it. The drawback of this method is that since you changed the first command, you would not be able to get a clean transcript of the command sequence.
Navigate the command history and call back the previous commands
Use Ctrl-Uparrow/Downarrow to navigate the previous commands. In our case, use Ctrl-Uparrow to call back the previous command and edit it. This method is preferred if the output of the previous commands are long.

Note:

If you use gnome, Ctrl-Arrow keys are intercepted by gnome to do something else. In this case, try Alt-Up/Down.

Then, you want to add the two vectors together, using command:

vector <- vector1 + vector2

The shortest key sequence is:

ve<tab>_ve<tab>1 + ve<tab>2

Here we used two features of ESS:

Automatic translation of _ to <-.
Although many user prefers _, <- is surely easier to follow. ESS let you input <- with less key strokes.
Completion
<TAB> key lets ESS complete your object name as much as it can. Since there are only two objects with names starting with ve, ESS will complete ve to vector. If object vector2 does not exist, ESS will complete ve to vector1.

Note:

Unfortunately, S-Plus 6.0 for Sun Solaris (the version we are using) has a bug which prevents ESS from getting the right completion list. I have sent a bug report to ESS and newer version of ESS (or S-Plus) is supposed to solve or work around this problem.

Now, try to input more commands... Here is more tricks:

Help on command: F1
Press F1 if you would like to loook up the manual of a function. Input the function name after Help on: in the mini-buffer (the last line of the emacs window.)
Go to the last line of the command window: F12
Whenever you are in the command windows, press F12 to go to the last line to input new command.

Open or create a script file

Files with extension .r .ssc or .s will be opened in ESS/S mode. You can tell this be the ESS[S] string on the status line. Press

C-x C-f test.r

to open file test.r. If this file does not exist, a new file will be created.

Edit a script file

Input the following commands

vector1 <- c(2,3,4)
vector2 <- c(3,3,3)
vector <- vector1 + vector2

You can not use completion here but you have all the editing capacity of emacs at hand. The best part of the ESS/S mode is the syntax coloring. With the help of colors, the program is easier to read and it is easy to pick out minor grammar mistakes like unbalanced )'s .

Submit commands

Put the cursor on the first line, make sure you have a R process running. press

F9

ESS will ask you which process to load, if you only have one S-Plus/R process, press enter. ESS will then send the current line to the R process and execute. The actual ESS command is ess-eval-line-and-step. It is possible to use other commands like ess-eval-line-and-go, ess-eval-line. The first command evaluate the current line and go to the command window, the second command just execute the current line. If you would like to see all ess comand, type

M-x ess-<tab>

Similarly, use F10 to send selected text and F11 to send the whole buffer to the S-Plus/R process. So you have your choice of stepping through, evaluating part of the script or source the whole buffer.

F1 and F12 keep their meaning as they do in command window.

ESS for window

The windows version of S-Plus is fairly easy to use but the windows version of R is not. As a result, you might want to install the windows version of R, Emacs and ESS. An outline of the steps is:

Download and install Emacs and R
Download ESS and decompress.
set $HOME and
add the path of R-term to $PATH from control panel.
change ess-site.el and optionally compile it with emacs command.
put an .emacs file under $HOME.

helpdesk

$Date: 2003/08/12 04:51:00 $

About this document ...

S-Plus/R with ESS

This document was generated using the LaTeX2HTML translator Version 2002-1 (1.68)

The command line arguments were:
latex2html -local_icons -no_subdir -split 0 ess.tex

The translation was initiated by Statistics Helpdesk on 2003-08-15

Statistics Helpdesk 2003-08-15