[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B. Starting the ESS process

To start an S session, simply type M-x S RET, i.e. press ESC, then x, then capital S and then the RETURN key.

S will then (by default) ask the question

 
S starting data directory?
Enter the name of the directory you wish to start S from (that is, the directory you would have cd'd to before starting S from the shell). This directory should have a `.Data' subdirectory.

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.

B.1 Running more than one ESS process  
B.2 ESS processes on Remote Computers  
B.4 Changing the startup actions  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B.1 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 for the size of memory allocated to the R process, for example.

You can switch to any active ESS process with the command C-c C-k (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.

For the predecessor to ESS (S-mode 4.8), the initial process was not visibly numbered, i.e. S instead of S1 was used in the mode-line. To obtain this behavior, set the variable ess-plain-first-buffername to t. See `ess-site' for how to set this for all users.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B.2 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.

  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 and lets SAS display them formatted correctly as in a SAS log file.

  4. Graphics (interactive) on the remote machine. If you run X11 (See section I.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 X-windows 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 D.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 B.3 S+elsewhere and ess-elsewhere.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B.3 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 X-windows graphics on the remote unix machine you should be able to display them in `xfree86' on your PC. If you don't run X-windows, then you can write graphics to the postscript device and copy it to your PC with dired and display it with ghostscript.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B.4 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 records 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 E.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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by on July, 28 2004 using texi2html