3. Interacting with statistical programs

As well as using ESS to edit your source files for statistical programs, you can use ESS to run these statistical programs. In this chapter, we mostly will refer by example to running S from within emacs. The emacs convention is to name such proceses running under its control as `inferior processes'. This term can be slightly misleading, in which case these processes can be thought of `interactive processes'. Either way, we use the term `iESS' to refer to the Emacs mode used to interact with statistical programs.

3.1 Starting an ESS process

To start an S session, simply type M-x S RET.

S will then (by default) ask the question

S starting data directory?

You will then be popped into a buffer with name `*S*' which will be used for interacting with the ESS process, and you can start entering commands.

3.2 Running more than one ESS process

ESS allows you to run more than one ESS process simultaneously in the same session. Each process has a name and a number; the initial process (process 1) is simply named (using S-PLUS as an example) `S+3:1'. The name of the process is shown in the mode line in square brackets (for example, `[S+3:2]'); this is useful if the process buffer is renamed. Without a prefix argument, M-x S starts a new ESS process, using the first available process number. With a prefix argument (for R), C-u M-x R allows for the specification of command line options.

You can switch to any active ESS process with the command `M-x ess-request-a-process'. Just enter the name of the process you require; completion is provided over the names of all running S processes. This is a good command to consider binding to a global key.

3.3 ESS processes on Remote Computers

ESS works with processes on remote computers as easily as with processes on the local machine. The recommended way to access a statistical program on remote computer is to start it from a telnet or ssh buffer and then connect ESS to that buffer.

1. Start a new telnet or ssh buffer and connect to the remote computer (e.g. use `M-x telnet' or `M-x ssh'; ssh.el is available at ftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.el).

2. Start the ESS process on the remote machine, for example with one of the commands `Splus', or `R', or `sas -stdio'.

3. Enter the ESS command `M-x ess-remote'. You will be prompted for a program name. Enter `sp6' or `r' or `sas' or another valid name. Your telnet process is now known to ESS. All the usual ESS commands (`C-c C-n' and its relatives) now work with the S language processes. For SAS you need to use a different command `C-c i' (that is a regular `i', not a `C-i') to send lines from your `myfile.sas' to the remote SAS process. `C-c i' sends lines over invisibly. With ess-remote you get teletype behavior--the data input, the log, and the listing all appear in the same buffer. To make this work, you need to end every PROC and DATA step with a "RUN;" statement. The "RUN;" statement is what tells SAS that it should process the preceding input statements.

4. Graphics (interactive) on the remote machine. If you run X11 (See section 12.2.2 Using ESS with windowing devices, X-windows) on both the local and remote machines then you should be able to display the graphs locally by setting the `DISPLAY' environment variable appropriately. Windows users can download `xfree86' from cygwin.

5. Graphics (static) on the remote machine. If you don't run the X window system on the local machine, then you can write graphics to a file on the remote machine, and display the file in a graphics viewer on the local machine. Most statistical software can write one or more of postscript, GIF, or JPEG files. Depending on the versions of emacs and the operating system that you are running, emacs itself may display `.gif' and `.jpg' files. Otherwise, a graphics file viewer will be needed. Ghostscript/ghostview may be downloaded to display `.ps' and `.eps' files. Viewers for GIF and JPEG are usually included with operating systems. See section 10.5 ESS[SAS]--Function keys for batch processing, for more information on using the F12 key for displaying graphics files with SAS.

Should you or a colleague inadvertently start a statistical process in an ordinary `*shell*' buffer, the `ess-remote' command can be used to convert it to an ESS buffer and allow you to use the ESS commands with it.

We have two older commands, now deprecated, for accessing ESS processes on remote computers. See section 3.4 S+elsewhere and ESS-elsewhere.

3.4 S+elsewhere and ESS-elsewhere

These commands are now deprecated. We recommend `ess-remote'. We have two versions of the elsewhere function. `S+elsewhere' is specific for the S-Plus program. The more general function `ESS-elsewhere' is not as stable.

1. Enter `M-x S+elsewhere'. You will be prompted for a starting directory. I usually give it my project directory on the local machine, say `~myname/myproject/'

   Or enter `M-x ESS-elsewhere'. You will be prompted for an ESS program and for a starting directory. I usually give it my project directory on the local machine, say `~myname/myproject/'

2. The `*S+3*' buffer will appear with a prompt from the local operating system (the unix prompt on a unix workstation or with cygwin bash on a PC, or the msdos prompt on a PC without bash). emacs may freeze because the cursor is at the wrong place. Unfreeze it with `C-g' then move the cursor to the end with `M->'. With `S+elsewhere' the buffer name is based on the name of the ESS program.
3. Enter `telnet myname@other.machine' (or `ssh myname@other.machine'). You will be prompted for your password on the remote machine. Use `M-x send-invisible' before typing the password itself.

4. Before starting the ESS process, type `stty -echo nl' at the unix prompt. The `-echo' turns off the echo, the `nl' turns off the newline that you see as `^M'.

5. You are now talking to the unix prompt on the other machine in the `*S+3*' buffer. cd into the directory for the current project and start the ESS process by entering `Splus' or `R' or `sas -stdio' as appropriate. If you can login remotely to your Windows 2000, then you should be able to run `Sqpe' on the Windows machine. I haven't tested this and noone has reported their tests to me. You will not be able to run the GUI through this text-only connection.

6. Once you get the S or R or SAS prompt, then you are completely connected. All the `C-c C-n' and related commands work correctly in sending commands from `myfile.s' or `myfile.r' on the PC to the `*S+3*' buffer running the S or R or SAS program on the remote machine.

7. Graphics on the remote machine works fine. If you run the X window sysyem on the remote unix machine you should be able to display them in `xfree86' on your PC. If you don't run X11, then you can write graphics to the postscript device and copy it to your PC with dired and display it with ghostscript.

3.5 Changing the startup actions

If you do not wish ESS to prompt for a starting directory when starting a new process, set the variable ess-ask-for-ess-directory to nil. In this case, the value of the variable ess-directory is used as the starting directory. The default value for this variable is your home directory. If ess-ask-for-ess-directory has a non-nil value (as it does by default) then the value of ess-directory provides the default when prompting for the starting directory. Incidentally, ess-directory is an ideal variable to set in ess-pre-run-hook.

If you like to keep a record of your S sessions, set the variable ess-ask-about-transfile to t, and you will be asked for a filename for the transcript before the ESS process starts.

User Option: ess-ask-about-transfile

If non-nil, as for a file name in which to save the session transcript.

Enter the name of a file in which to save the transcript at the prompt. If the file doesn't exist it will be created (and you should give it a file name ending in `.St'); if the file already exists the transcript will be appended to the file. (Note: if you don't set this variable but you still want to save the transcript, you can still do it later -- see section 4.4.4 Keeping a record of your S session.)

Once these questions are answered (if they are asked at all) the S process itself is started by calling the program name specified in the variable inferior-ess-program. If you need to pass any arguments to this program, they may be specified in the variable inferior-S_program_name-args (e.g. if inferior-ess-program is "S+" then the variable to set is inferior-S+-args. It is not normally necessary to pass arguments to the S program; in particular do not pass the `-e' option to Splus, since ESS provides its own command history mechanism.

By default, the new process will be displayed in another window in the current frame. If you wish your S process to appear in a separate variable, customize the variable inferior-ess-own-frame.