emacs speaks statistics

7/29/2019 Emacs speaks statistics

1/80

ESS Emacs Speaks Statistics

ESS version 5.8

The ESS Developers (A.J. Rossini, R.M. Heiberger, K. Hornik,M. Maechler, R.A. Sparapani, S.J. Eglen,S.P. Luque and H. Redestig)Current Documentation by The ESS DevelopersCopyright c 20022010 The ESS DevelopersCopyright c 19962001 A.J. RossiniOriginal Documentation by David M. SmithCopyright c 19921995 David M. SmithPermission is granted to make and distribute verbatim copies o thismanual provided the copyright notice and this permission notice are

preserved on all copies.Permission is granted to copy and distribute modied versions o thimanual under the conditions or verbatim copying, provided that theentire resulting derived work is distributed under the terms o apermission notice identical to this one.


2/80

Chapter 1: Introduction to ESS 1

1 Introduction to ESS

The S amily (S, Splus and R) and SAS statistical analysis packages provide sophisticatedstatistical and graphical routines or manipulating data. Emacs Speaks Statistics (ESS) is

based on the merger o two pre-cursors, S-mode and SAS-mode, which provided supportor the S amily and SAS respectively. Later on, Stata-mode was also incorporated.

ESS provides a common, generic, and useul interace, through emacs, to many statisticalpackages. It currently supports the S amily, SAS, BUGS/JAGS, Stata and XLisp-Stat withthe level o support roughly in that order.

A bit o notation beore we begin. emacs reers to both GNU Emacs by the FreeSotware Foundation, as well as XEmacs by the XEmacs Project. The emacs major modeESS[language], where language can take values such as S, SAS, or XLS. The ineriorprocess interace (the connection between emacs and the running process) reerred to asinerior ESS (iESS), is denoted in the modeline by ESS[dialect], where dialect can takevalues such as S3, S4, S+3, S+4, S+5, S+6, S+7, R, XLS, VST, SAS.

Currently, the documentation contains many reerences to S where actually any sup-ported (statistics) language is meant, i.e., S could also mean XLisp-Stat or SAS.

For exclusively interactive users o S, ESS provides a number o eatures to make lieeasier. There is an easy to use command history mechanism, including a quick prex-searchhistory. To reduce typing, command-line completion is provided or all S objects and hotkeys are provided or common S unction calls. Help les are easily accessible, and a pagingmechanism is provided to view them. Finally, an incidental (but very useul) side-efect oESS is that a transcript o your session is kept or later saving or editing.

No special knowledge o Emacs is necessary when using S interactively under ESS.

For those that use S in the typical edittestrevise cycle when programming S unctions,ESS provides or editing o S unctions in Emacs edit bufers. Unlike the typical use o S

where the editor is restarted every time an object is edited, ESS uses the current Emacssession or editing. In practical terms, this means that you can edit more than one unctionat once, and that the ESS process is still available or use while editing. Error checking isperormed on unctions loaded back into S, and a mechanism to jump directly to the erroris provided. ESS also provides or maintaining text versions o your S unctions in speciedsource directories.

1.1 Why should I use ESS?

Statistical packages are powerul sotware systems or manipulating and analyzing data, buttheir user interaces oten leave something something to be desired: they ofer weak editorunctionality and they difer among themselves so markedly that you have to re-learn how

to do those things or each package. ESS is a package which is designed to make editing andinteracting with statistical packages more uniorm, user-riendly and give you the power oemacs as well.

ESS provides several eatures which make it easier to interact with the ESS process (aconnection between your bufer and the statistical package which is waiting or you to inputcommands). These include:

Command-line editing or xing mistakes in commands beore they are entered. The-e ag or S-plus provides something similar to this, but here you have the ull range


3/80


o Emacs commands rather than a limited subset. However, other packages such asXLisp-Stat and S3 do not necessarily have eatures like this built-in. See Section 4.1[Command-line editing], page 26.

Searchable command history or recalling previously-submitted commands. This pro-vides all the eatures o the Splus -e history mechanism, plus added eatures such ashistory searching. See Section 4.5 [Command History], page 30.

Command-line completion o both object and le names or quick entry. This is similarto tcshs acility or lenames; here it also applies to object names and list components.See Section 4.2 [Completion], page 26.

Hot-keys or quick entry o commonly-used commands in S such as objects() andsearch(). See Section 4.7 [Hot keys], page 32.

Transcript recording or a complete record o all the actions in an S session. SeeSection 4.4 [Transcript], page 28.

Interace to the help system, with a specialized mode or viewing S help les. See

Chapter 9 [Help], page 51.

I you commonly create or modiy S unctions, you will have ound the standard acilitiesor this (the fix() unction, or example) severely limiting. Using Ss standard eatures,one can only edit one unction at a time, and you cant continue to use S while editing.ESS corrects these problems by introducing the ollowing eatures:

Object editing. ESS allows you to edit more than one unction simultaneously indedicated Emacs bufers. The ESS process may continue to be used while unctionsare being edited. See Section 7.1 [Edit bufer], page 42.

A specialized editing mode or S code, which provides syntactic indentation and high-lighting. See Section 7.5 [Indenting], page 44.

Facilities or loading and error-checking source fles, including a keystroke to jumpstraight to the position o an error in a source le. See Section 7.3 [Error Checking],page 43.

Source code revision maintenance, which allows you to keep historic versions o S sourceles. See Section 7.7 [Source Files], page 46.

Facilities or evaluating S code such as portions o source les, or line-by-line evaluationo les (useul or debugging). See Section 7.4 [Evaluating code], page 43.

Finally, ESS provides eatures or re-submitting commands rom saved transcript les,including:

Evaluation o previously entered commands, stripping away unnecessary prompts. SeeSection 4.4.3 [Transcript resubmit], page 29.

1.2 New eatures in ESS

Changes/New Features in 5.8:

ESS[R]: New ess-rutils.el with utilities or listing, loading, installing, and updat-ing packages, as well as object manipulation (listing, viewing, and deleting). Italso provides an alternative to RSiteSearch() that uses the browse-url unction, soresults can be viewed in an Emacs web browser.


4/80


ESS[R]: much more extensive Roxygen interace, via ess-roxy.el rom Henning Re-destig. Ess-roxy supports lling o roxygen elds, generation and updating roxygentemplates, completion o roxygen tags, basic navigation (marking and moving be-tween entries), oling using hs-minor-mode and preview o the Rd le.

Emacs lisp les have got better names (partly, or now).


ESS[R]: loading a source le (C-c C-l) now works in Windows, similarly to otherplatorms; (urther; it had accidentally been broken in ESS 5.6 on all platorms)


ESS[R]: help() calls have to difer rom old deault, with newer versions o R;currently via .help.ESS


5/80


ESS[R]: added support or Roxygen, potentially to be extended.

ESS[S] (and R): inerior (*R*) and transcript modes no longer ontiy languagekeywords (such as for, in, etc).

iESS[Stata]: Customize the ess-sta-delimiter-friendly setting to t to convertembedded semi-colons to newlines or Stata processing.

Sweave x or embedded blanks in PDF reader and PDF les

Several xes or Major Mode Convention violations in ess-mode and noweb-mode.

ESS[JAGS]: M-x comment-region now available!

ESS[S] The ess-swv-* commands (and keybindings) are now in a submenu o theNoweb menu, when editing Sweave les.

Changes/New Features in 5.3.8:

ESS[JAGS]: more separation rom ESS[BUGS] (as much as is currently planned);now C-c C-c on an empty .jmd creates a template as it should; symbolic links

are created or CODA output so BOA is happy: rom index.txt to .ind andchain#.txt to #.out

ESS[SAS]: bufer-local ess-sas-submit-command and ess-sas-submit-command-options now recognized by ess-sas-submit-region

ESS[S]: When trying to evaluate code in an S language bufer and there is noassociated process, now start R automatically instead o signalling an error. Also,restart R i there is an associated process which is not running. However, do notstart R just via the electric ( (ess-r-args-auto-show).

ESS[S]: For (one-line) unctions withOUT { .. } bodys, the end o unction is nowcorrectly ound more oten. This notably improves C-c C-c (ess-eval-function-or-paragraph-and-step).

ESS[JAGS]: cleanup/re-organization o elisp code; symbolic links or CODA outputare now only created by the new JAGS system command in version 1.0.3; speciywhether this command is available via ess-jags-system; i not present, then nolinks are created so that the *shell* bufer does not become unresponsive duringthe batch run


ESS: ess-default-style now *is* customizable, i.e., changing its value in~/.emacs now does have the desired efect.

ESS: ess-font-lock-mode is a new variable (deault: t) which controls whetheront-locking is enabled in ESS bufers.

ESS[R]: or XEmacs on Windows; another tweak to nd R versions ESS[SAS]: ont-locking updated or ODS and SAS Bayesian Procedures; a more

consistent handling o SAS options by ess-sas-submit-command-options whichis bufer-local; portable snooze or MS Windows via customize-able ess-sleep-for (oats welcome); Xpd now supported as a PDF viewer

ESS[Rnw]: now also works with emacs -nw and Emacs 22.

ESS[JAGS]: now requires JAGS 1.0 (see the new ESS or JAGS help section ormore inormation): both need work; suggestions welcome


6/80


ESS[R]: [TAB] completion now uses the R-internal completion mechanism (or R>= 2.5.0).

ESS[R], [S]: interpretation o as assignment has been removed iness-continued-statement-p

or R and S. several internal code cleanups.

ESS[R]: An experimental version o a new command Rgui on MS Windows tosend lines directly rom emacs to Rgui is available in le lisp/essd-rgui.el.Preliminary documentation is in le doc/rgui-doc.txt.


ESS: or XEmacs, using gnuclient (without a -q) works or things like x()ater M-x gnuserv-start has been done.

ESS[R]: M-x R-newest should now work in more situations on MS Windows, e.g.,when R has been installed in a non-deault "ProgramFiles" directory tree. Inthese cases, theres no need to speciy the name (and ull path) o the R program

anymore.

ESS[R]: For XEmacs, startup (with new tooltip code) works again.


ESS[R] a new deun is available, M-x R-newest, which will start the newest versiono R that it can nd on your system.

ESS[R] add Sven Hartensteins R unction arguments tips unctionality, via newle ../lisp/essd-r-args.el. Note that this includes an electric "(" behaviorinside R-mode which is active by deault and can be customized via ess-r-args-electric-paren; i.e., use (setq ess-r-args-electric-paren nil) to turn it of.Further, ess-r-args-show-as allows to switch to the tooltip mode.

ESS: unctions ess-get-pdf-viewer and *-ps-viewer; built on new customizablevariables ess-pdf-viewer-pref and ess-ps-viewer-pref; currently used in ess-swv-PDF and *-PS.

ESS[R] Improved ess-swv-PDF to run pd viewer only i pdatex was ok

ESS[R] Improved ess-swv-weave to start R automatically i none is running.

ESS: Do no longer ask which ESS process to use i there is only one.


ESS[R] now better work with options(error=recover); and the new deault o CHMhelp les on windows.

ESS[R] some more cleanup in the sweave unctions

miscellaneous xes


ESS[S] x buglet (5.3.2 only) which let command prompt in execute bufer andhence help les.

new customizable variable ess-display-buffer-reuse-frames set to true (whichchanges deault behavior) such that execution or help *rames* are reused.



7/80


Classic BUGS now supported by (require essd-bugs) with ESS[BUGS] andJAGS by (require essd-jags) with ESS[JAGS]. But, only one o them can beused at a time since they dont play nice together. Also, C-c C-c is now boundto the unction ess-bugs-next-action (F12 has been retired). And nally, notethat essl-bug.el is deprecated and the replacement is essl-bugs.el.

ESS[R] Improved some o the Sweave-make unctions (yet scarcely documented)in ess-swv.el.

ESS[S] No longer mess with .Last.value (nor in other languages).


See the docs or 2 ways to install ESS or XEmacs

1. by uncommenting the XEmacs part o Section 1 o Makeconf and perormingmake install

2. by unpacking either ess-5.3.1.tgz or ess-5.3.1.zip intoPREFIX/lib/xemacs/site-packages on unix or PREFIX\XEmacs\site-packages

on windows

ESS[R]: xed bugs so that Rterm.exe can be ound by XEmacs

ESS[S]: ess-toggle-S-assign-key is slightly changed; in particular, the deaultess-assign-key is now C-x =.

ESS[R]: M-x R-site-search is a new (slightly experimental) utility similar to RsRSiteSearch(..) but with the advantage o using Emacs preerred browser, seebrowse-url-browser-function


ESS[BUGS]: sanely re-ormat statistical output, .bog, rom scientic notation tonumbers rounded with 4 decimal places with M-x ess-bugs-sci-round-to-4-dp.

The keys or navigating among section headings in help bufers worked, but onlyor one language per session; they should now work or multiple languages. (Theywere also broken on Windows machines.)

ESS[S] long standing buglets in the internal logic or loading lisp code on Windows.Particularly xed behavior in help mode with S-plus GUI.

New variable, ess-use-inferior-program-name-in-buffer-name , which enablesusing the executable name instead o the dialect name or R. Feature request.

ESS[S] ess-execute-screen-options now also works correctly when there is morethan one window *side-by-side* in the same rame and runs in the correct buferalso when there is more than one S bufer.

iESS[S] new unctions ess-eval-paragraph-and-step and ess-eval-function-or-paragraph-and-step are bound to keys C-c C-p and C-c C-c respectively andto the menu in ESS-mode; also bound in the help mode (or evaluating examples).

ESS[S] new unction ess-toggle-S-assign-key allows to assign the


8/80


PROCs are ontied which is very helpul nding syntax errors (currently sup-ported: BASE, ETS, FSP, GRAPH, IML, INSIGHT and STAT); the eaturewhere F-keys take you to an empty bufer when the requested destination is a lethat does not exist has been xed, now the request results in a no-op. Further,sas-mode now also works in simple terminals.

Rterm/Cygwin combination works under Microsot Windows.

ESS[R]: internal calls use baseenv() instead o NULL and dene baseenv whereneeded.

New experimental support or installing ESS. See the le lisp/ess-install.el.


ESS Ino entry and dir handled more efectively or GNU Emacs users

ESS[SAS]: temporary les created or batch submission o a region are now namedbased on the current le; see ess-sas-file-root or details; all lag and dif

unctions now ontied correctly iESS[SAS]: xed a ew nagging bugs, however, still does not appear to work at this

time; please let us know i you have any ideas.

ESS[S]: Support or running other versions o Splus has been added or unix. Twonew variables, ess-s-versions and ess-s-versions-list, are used to tell ESSwhat other versions o Splus you would like to run.


ESS[R]: ess-r-versions can no longer be customized (since the customization wasnot taking efect unless customizations were loaded beore ESS). Its value hasbeen changed so that it will also nd R executables beginning R-devel and R-patched. I you wish to change this variable, it must be set in your .emacsbeore ESS is loaded.

Installation with GNU Make enhanced: unix and unix-like operating systems willnow be able to install ESS or all users in either a GNU Emacs site-lisp or anXEmacs package conguration by editing lisp/ess-site.el and Makeconf ac-cordingly, then issuing make install

ESS[S]: Filename completion (inside strings) now also works in XEmacs or R andS-plus.


ESS[R] or Windows: the \ directory character bug with respect to ess-load-le hasbeen eradicated.

iESS[SAS]: C-c C-r and C-c C-b once again work as intended and documented.

ESS[S]: M-x ess-x-EQ-assign is a bit more agressive.

ESS[S]: Imenu now also shows setAs(), etc.

ESS[R]: R unction pattern enhanced with underlying code such that M-C-a (ess-beginning-of-function) etc now work or many more cases, including S4 methoddenitions.

iESS[R]: myOwnhelp(1) no longer wrongly triggers help(1).


9/80


ESS[R]: Improved detection o bogus help bufers: valid help bufers containingwith the string no documentation(e.g. contour) were being treated as bogus.

ESS[R]: In R help bufers, i options("help.try.all.packages" = TRUE) then?rlm

will list which packages rlm is dened in. This help bufer is not bogus, butinstead is now relabelled *help[R](rlm in packages)*.

ESS[STA]: add // as comment starting character to syntax-table.


iESS: [Tab] completes fle names inside string as in earlier (0 and your .log grows to more than ess-

sas-log-max bytes, just the rst ess-sas-log-max bytes are rereshed; this is helpulwhen your .sas program generates lots o error messages and gets too big or emacsto display

ESS[R/S]: M-; in R/S editing modes will now indent with either one or two hashesdepending on context.

ESS[R]: David Whitings Sweave extensions (to noweb) are now available (romess-swv.el loaded by deault).


Removed non-ASCII characters in a ew les.

ESS[R]: now works better when UTF-8 locale is active; in particular, you getcorrect directional quotes in Rs startup message or R-devel (unstable develop-ment version o R 2.1.0) when using environment variables LANGUAGE=en@quotLC ALL=en US.UTF-8

ESS[SAS]: toggling o .log mode improved (F10); toggling o .lst mode now alsoavailable (C-F10); killing all bufers associated with .sas program no longer boundto C-F10 since its a bit overzealous.

S-Plus 7 or Windows is now recognized.

ESS[S] (incl. R): in auto-ll mode, strings are not wrapped anymore.

ESS[S] (incl. R): ont-lock now correctly difers between R and S, e.g., or " "; bothnow ontiy warning(.) and S does terminate() additionally.

Support or bell aka beep aka ding aka alarm in all inerior modes: When \a

is output to the the console at the beginning o a line, the bell is rung.Changes/New Features in 5.2.5:

ESS[R]: C-c C-q or Quit S rom the menu now should work (again and lessklunkily) and do not append -exited to the bufer name. Further, the behavioro (ess-cleanup), called rom ess-quit, now depends on the new customizablevariable ess-S-quit-kill-buffers-p which deaults to nil. Consequently, thequestion Delete all bufers associated with ..? will not be asked anymore bydeault.


10/80


ESS[SAS] ess-ebcdic-to-ascii-search-and-replace will now work with the recodeapplication as well which is available on many platorms

ESS[S] (incl. R): Name completion or slots o S4 objects now works!


The documentation now includes an overview o how to use the emacs TAGSacility or S unctions. (The distribution also used to contain a directoryetc/other/Tags where a ~1990 version o etags.c was distributed; this is nolonger relevant and so has been deleted.)

ESS[SAS] When you are working with EBCDIC les on an ASCII platorm, .logNOTEs may display as gibberish since the EBCDIC characters are not convertedto ASCII prior to their display. So, the unction ess-ebcdic-to-ascii-search-and-replace is provided or convenience and is bound to C-F11. This unction requiresthe dd command (only available on unix or unix-like platorms).

ESS: Completion o object names is now always done dynamically rather thanallowing the option o using a pre-computed database (by ess-create-object-name-db) since modern computers seem ast enough or dynamic completion. (Weexpect ew users, i any, have been using the pre-computed database method.)

ESS: object completion in iESS bufers running on Windows was very slow (orGNU Emacs, but not XEmacs) and has now been xed. Further, it was more orless broken or all versions o S-plus 6.x, and has been xed to work everywherebut with the Windows GUI o S-plus. The list o ob jects now shows unique namesalso when an object appears more than once in the search path.

ESS[R]: Completion o object names now also includes those starting with ..


ESS: When new inerior ESS processes are created, by deault they will replacethe current bufer (this restores behavior rom pre 5.2.0). I you wish new ESSprocesses to start in another window o the current rame, set inerior-ess-same-window to nil.

New variables inerior-Splus-args and inerior-R-args provide a way to pass com-mand line arguments to starting S and R processes.


bug-xes or 5.2.1 (require executable), html docs, etc.

ess-lisp-directory/../doc/ino added to Ino-directory-list i ess-ino not ound byino

ESS[R]: I you have other versions o R on your exec-path, such as "R-1.8.1" withUnix or "rw1081" with Windows, ESS will nd them and create appropriate unc-tions, such as M-x R-1.8.1 or M-x rw1081, or calling them. By deault onlyUnix programs beginning "R-1" and "R-2" and Windows programs parallel to theversion o R in your exec-path will be ound, but see ess-r-versions and ess-rterm-versions or ways to nd other versions o R.

ESS[R]: Other versions o R, such as "R-1.8.1" on Unix and "rw1081" on Windows,are added to the "ESS / Start Process / Other" menu.


11/80


ESS[S]: I you have other versions o S-Plus on your Windows computer, such asS-Plus 6.1 or S-Plus 4.5, ESS will nd them and create appropriate unctions,such as M-x splus61, or calling the console version (Sqpe) inside an emacs bufer.By deault only programs installed in the deault location will be ound, but seeess-SHOME-versions or ways to nd other versions o S-Plus.

ESS[S]: Other versions o Sqpe on Windows, such as "splus61", are added to the"ESS / Start Process / Other" menu.

ESS[R]: (bug x) ess-quit (bound to C-c C-q) should now quit the inerior R pro-cess, when issued rom either the inerior bufer, or rom a .R bufer.


ESS[S] (R and S-plus): now have toolbar support with icons to evaluate code inthe inerior process or to switch there. This code is experimental and likely tochange as XEmacs/Emacs issues get resolved. The toolbar should be enabled iyour Emacs displays images, but can be disabled with the variable ess-use-toolbar.

Thanks to David Smith rom Insightul or the S-plus logo. ESS[SAS]: ess-sas-graph-view (F12) enhanced; you can speciy external le viewersor each graphics le type via the alist ess-sas-graph-view-viewer-alist; also .jpg/.giare now handled by image-mode on XEmacs, i available, otherwise by graphicsprimitives as beore


ESS[BUGS]: new ino documentation! now supports interactive processing thanksto Aki Vehtari; new architecture-independent unix support as well as support orBUGS v. 0.5

ESS[SAS]: convert .log to .sas with ess-sas-transcript; ino documentation improved;Local Variable bug xes; SAS/IML statements/unctions now highlighted; les

edited remotely by ange-tp/EFS/tramp are recognized and pressing SUBMITopens a bufer on the remote host via the local variable ess-sas-shell-bufer-remote-init which deaults to "ssh"; changed the denition o the variable ess-sas-edit-keys-toggle to boolean rather than 0/1; added the unction ess-electric-run-semicolonwhich automatically reverse indents lines containing only "run;"; C-F1 creates MSRTF portrait rom the current bufer; C-F2 creates MS RTF landscape rom thecurrent bufer; C-F9 opens a SAS DATASET with PROC INSIGHT rather thanPROC FSVIEW; "inerior" aliases or SAS batch: C-c C-r or submit region, C-cC-b or submit bufer, C-c C-x or goto .log; C-c C-y or goto .lst

ESS[S]: Pressing underscore (" ") once inserts "


12/80


ESS: Support or creating new window rames has been added to ESS. Inerior ESSprocesses can be created in dedicated rames by setting inerior-ess-own-rame tot. ESS help bufers can also open in new rames; see the documentation or ess-help-own-rame or details. (Thanks to Kevin Rodgers or contributing code.)


The version number is now correct even inside ESS/Emacs


Minor more Makele clean up.


Besides ino documentation, PDF and HTML documentation are also provided(instead o built using "make") and available on the web as well; see ESS webpage and StatLib

Now that ino documentation is available, the README.* les are no longer sup-

ported. However, they are still distributed or what its worth. ESS is now an XEmacs package! See XEmacs Installation HOWTO or details

(specically, items 10-15).

ESS[SAS]: more user-riendly enhancements or remote SAS batch jobs with Kermitle transers (LOG and OUTPUT unction key eatures now supported). Multi-ple shells now supported so you can run SAS on diferent computers rom difer-ent bufers by setting the bufer-local variable ess-sas-shell-bufer to unique bufernames.

Major re-vamping o Makele/Makecon.


ESS[SAS]: ino documentation now available!, see ESS->Help or SAS; F12 opensGSASFILE nearest point or viewing either within emacs, when available, or viaan external viewer; more syntax highlighting keywords; more enhancements orremote SAS batch jobs with Kermit; new ramework or remote SAS interactivejobs, see ess-remote

ESS[S]: ino documentation now available!, see ESS->Help or the S amily

Makele: tag now independent o rel; ino les made by doc/Makele and installedin new ino sub-directory


New options()$STERM in the S dialects (S, S-Plus, R). The S program candetermine the environment in which it is currently running. ESS sets the option

to iESS or ddeESS when it starts an S language process. We recommend otherspecic values or S language processes that ESS does not start.

New ess-mouse-me unction, assigned to S-mouse-3 by deault. User may clickon a word or region and then choose rom the menu to display the item, or asummary, or a plot, etc. This eature is still under development.

GNU Emacs 21.1 is now supported (xed or S dialects, SAS & BUGS), (somerom Stephen Eglen).

XEmacs 21.x is now supported (xed w32-using-nt bug)
http://ess.r-project.org/http://ess.r-project.org/http://lib.stat.cmu.edu/general/ESS/dochttp://www.xemacs.org/Install/index.htmlhttp://www.xemacs.org/Install/index.htmlhttp://lib.stat.cmu.edu/general/ESS/dochttp://ess.r-project.org/http://ess.r-project.org/


13/80


XEmacs on Win (NT) is better supported.

Workaround or bug in Sqpe+6 (S-PLUS 6 or Win).

should now work even when imenu is not available (or old XEmacsen).

ESS[SAS]: XEmacs-Imenu x; C-TAB is globalized along with your unction-keydenitions, i specied; you can speciy your SAS library denitions outside oautoexec.sas or ess-sas-data-view with SAS code placed in the variable ess-sas-data-view-libname, also the dataset name is deaulted to the nearest permanentdataset to point; Speedbar support now works or permanent datasets, pleaseignore rst./last.; new ont-locking is now the deault with more improvements oront-locking PROCs, macro statements, * ; and %* ; comments; you can togglesas-log-mode with F10 which will ont-lock your .log (i it isnt too big); submitremote .sas les accessed with ange-tp, EFS or Tramp (Kermit is experimental) bysetting ess-sas-submit-method to sh; ess-sas-submit-command and ess-sas-submit-command-options are bufer-local so you can have local le variable sections at theend o your .sas les to request diferent executables or speciy special options and

the local le variables are re-read at submit instead o only at le open so that iyou make a change it is picked up immediately;

ESS[BUGS]: ont-lock with in xed.

or STATA: ont-lock bug xed.

or Rd mode: C-c C-v and switch-process in menu. urther, C-c C-f prex(Rd-ont) or inserting or surrounding a word by things such as \code{.},\code{\link{.}}, \emph{.} etc.

new unctions (ess-directory-unction) and (ess-narrow-to-deun) ess-directory deault-directory logic (Jef Mincy).

Re-organized Makele and xed a ew bugs.

Changes/New Features in 5.1.19: S+6 now supported (Tony Rossini (Unix) and Rich Heiberger (Windows))

New BUGS support through ESS[BUGS] mode (Rodney Sparapani) Templates as-sist you in writing .bug and .cmd code (.cmd and .log are replaced by .bmd and.bog to avoid emacs extension collisions). Substitution" parameters acilitate "au-tomagic" generation o data...in" and "init...in" lenames, "const N=" rom yourdata le and "monitor()/stats()" commands. Activated by pressing F12.

Fixes or ess-smart-underscore SAS breakage (Rich Heiberger)

You can change between PC and Unix, local and global SAS unction-key deni-tions interactively (Rich Heiberger)

C-Submit a highlighted region to SAS batch (Rodney Sparapani)

New and improved SAS syntax highlighting (Rodney Sparapani) To get the newunctionality, set ess-sas-run-make-regexp to nil. Also available in .log les viaF10.

Open a permanent SAS dataset or viewing via F9 (Rodney Sparapani) You musthave the library dened in autoexec.sas or it to work.

User-riendly deaults or sas-program, ess-sas-batch-pre-command and ess-sas-batch-post-command as well Customize support or these and other ESS[SAS] vari-ables (Rodney Sparapani)


14/80


ess-sas-sux-2 now deaults to .dat via F11 (Rodney Sparapani)

Emacs/XEmacs, Unix/Windows issues collectively handled in ess-emcs.el

deadvice solves problem o missing *ESS* (thanks to Jef Mincy)

Improved manual a bit by including things that were only in README.


New ess-smart-underscore unction, now assigned to " " by deault. Inserts ess-S-assign (customizable "


15/80


Fixes to SAS mode, thanks to Rodney Sparapani


More xes to Stata mode

primitive generic version o ESS-elsewhere

Small xes to SAS/Stata.


Stata mode works

Literate Data Analysis using Noweb works


Bug xes

R documentation mode deaults changed


able to use inerior iESS mode to communicate directly with a running S-Plus 4.xprocess using the Microsot DDE protocol. We use the amiliar (rom Unix ESS) C-c C-n and related key sequences to send lines rom the S-mode le to the inerior Sprocess. We continue to edit S input les in ESS[S] mode and transcripts o previousS sessions in ESS Transcript mode. All three modes know the S language, syntax,and indentation patterns and provide the syntactic highlighting that eases theprogramming tasks.

1.3 Authors o and contributors to ESS

The ESS environment is built on the open-source projects o many contributors, datingback to 1989 where Doug Bates and Ed Kademan wrote S-mode to edit S and Splus les in

GNU Emacs. Frank Ritter and Mike Meyer added eatures, creating version 2. Meyer andDavid Smith made urther contributions, creating version 3. For version 4, David Smithprovided signicant enhancements to allow or powerul process interaction.

John Sall wrote GNU Emacs macros or SAS source code around 1990. Tom Cook addedunctions to submit jobs, review listing and log les, and produce basic views o a dataset,thus creating a SAS-mode which was distributed in 1994.

In 1994, A.J. Rossini extended S-mode to support XEmacs. Together with extensionswritten by Martin Maechler, this became version 4.7 and supported S, Splus, and R. In1995, Rossini extended SAS-mode to work with XEmacs.

In 1997, Rossini merged S-mode and SAS-mode into a single Emacs package or statisticalprogramming; the product o this marriage was called ESS version 5. Richard M. Heiberger

designed the inerior mode or interactive SAS and SAS-mode was urther integrated intoESS. Thomas Lumleys Stata mode, written around 1996, was also olded into ESS. Morechanges were made to support additional statistical languages, particularly XLispStat.

ESS initially worked only with Unix statistics packages that used standard-input andstandard-output or both the command-line interace and batch processing. ESS couldnot communicate with statistical packages that did not use this protocol. This changed in1998 when Brian Ripley demonstrated use o the Windows Dynamic Data Exchange (DDE)protocol with ESS. Heiberger then used DDE to provide interactive interaces or Windows


16/80


versions o Splus. In 1999, Rodney A. Sparapani and Heiberger implemented SAS batch orESS relying on les, rather than standard-input/standard-output, or Unix, Windows andMac. In 2001, Sparapani added BUGS batch le processing to ESS or Unix and Windows.

The multiple process code, and the idea or ess-eval-line-and-next-line are byRod Ball.

Thanks to Doug Bates or many useul suggestions.

Thanks to Martin Maechler or reporting and xing bugs, providing many useul com-ments and suggestions, and or maintaining the ESS mailing lists.

Thanks to Frank Ritter or updates, particularly the menu code, and invaluable com-ments on the manual.

Thanks to Kenichi Shibayama or his excellent indenting code, and many commentsand suggestions.

Thanks to Aki Vehtari or adding interactive BUGS support.

Thanks to Brendan Halpin or bug-xes and updates to Stata-mode. Last, but denitely not least, thanks to the many ESS users and contributors to the

ESS mailing lists.

ESS version 5 is being developed and currently maintained by

A.J. Rossini

Richard M. Heiberger

Kurt Hornik

Martin Maechler

Rodney A. Sparapani

Stephen Eglen Sebastian P. Luque

Henning Redestig

1.4 Getting the latest version o ESS

The latest released version o ESS is always available on the web at: ESS web page orStatLib

The latest development version o ESS is available via https://svn.R-project.org/ESS/,the ESS Subversion repository. I you have a Subversion client (see http://subversion.tigris.org/),you can download the sources using:

% svn checkout https://svn.r-project.org/ESS/trunk path

which will put the ESS les into directory path. Later, within that directory, svn updatewill bring that directory up to date. Windows-based tools such as TortoiseSVN are alsoavailable or downloading the les. Alternatively, you can browse the sources with a webbrowser at: ESS SVN site. However, please use a subversion client instead to minimize theload when retrieving.

I you remove other versions o ESS rom your emacs load-path, you can then use thedevelopment version by adding the ollowing to .emacs:
mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]://ess.r-project.org/http://lib.stat.cmu.edu/general/ESS/https://svn.r-project.org/ESS/http://subversion.tigris.org/https://svn.r-project.org/ESS/trunkhttps://svn.r-project.org/ESS/trunkhttp://subversion.tigris.org/https://svn.r-project.org/ESS/http://lib.stat.cmu.edu/general/ESS/http://ess.r-project.org/mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]


17/80


(load "/path/to/ess-svn/lisp/ess-site.el")

Note that https is required, and that the SSL certicate or the Subversion server o theR project is

Certificate information:

- Hostname: svn.r-project.org

- Valid: from Jul 16 08:10:01 2004 GMT until Jul 14 08:10:01 2014 GMT

- Issuer: Department of Mathematics, ETH Zurich, Zurich, Switzerland, CH

- Fingerprint: c9:5d:eb:f9:f2:56:d1:04:ba:44:61:f8:64:6b:d9:33:3f:93:6e:ad

(currently, there is no trusted certicate). You can accept this certicate permanentlyand will not be asked about it anymore.

1.5 How to read this manual

I you need to install ESS, read Chapter 2 [Installation], page 17 or details on what needsto be done beore proceeding to the next chapter.

In this manual we use the standard notation or describing the keystrokes used to invoke

certain commands. C- means hold the CONTROL key while typing the character. M- means hold the META or EDIT or ALT key down while typing . Ithere is no META, EDIT or ALT key, instead press and release the ESC key and then type.

All ESS commands can be invoked by typing M-x command. Most o the useul commandsare bound to keystrokes or ease o use. Also, the most popular commands are also availablethrough the emacs menubar, and nally, i available, a small subset are provided on thetoolbar. Where possible, keybindings are similar to other modes in emacs to strive ora consistent user interace within emacs, regardless o the details o which programminglanguage is being edited, or process being run.

Some commands, such as M-x Rcan accept an optional prex argument. To speciy the

prex argument, you would type C-u beore giving the command. e.g. I you type C-u M-xR, you will be asked or command line options that you wish to invoke the R process with.

Emacs is oten reerred to as a sel-documenting text editor. This applies to ESS in twoways. First, limited documentation about each ESS command can be obtained by typingC-h f. For example, i you type C-h f ess-eval-region, documentation or that commandwill appear in a separate *Help* bufer. Second, a complete list o keybindings that areavailable in each ESS mode and brie description o that mode is available by typing C-h mwithin an ESS bufer.

Emacs is a versatile editor written in both C and lisp; ESS is written in the Emacslisp dialect (termed elisp) and thus benets rom the exible nature o lisp. In particular,many aspects o ESS behaviour can be changed by suitable customization o lisp variables.

This manual mentions some o the most requent variables. A ull list o them however isavailable by using the Custom acility within emacs. (Type M-x customize-group RET essRETto get started.) Appendix A [Customization], page 71 provides details o common uservariables you can change to customize ESS to your taste, but it is recommended that youdeer this section until you are more amiliar with ESS.


18/80

Chapter 2: Installing ESS on your system 17

2 Installing ESS on your system

The ollowing section details those steps necessary to get ESS running on your system.

2.1 Unix installation

For a Unix or Unix-like installation, please ollow the next steps. Retrieve the latest tgzle (ess-VERSION.tgz) rom ESS downloads area.

GNU Emacs Simple Instructions: or recent versions o Emacs (22.x or higher) and ESS,the installation process is simple.

1. Extract all the les rom ess-VERSION.tgz when you are in the currentworking directory o /usr/local/share/emacs/site-lisp which exists orpackages like ESS (and or Mac OS X create a link to it rom the directory/Applications/Emacs.app/Contents/Resources/site-lisp ):

%prompt gtar zxf ess-VERSION.tgz # for GNU tar

%prompt gunzip < ess-VERSION.tgz | tar xf - # for Unix tar

2. Then, add the line

(require ess-site)

to ~/.emacs and restart Emacs.

3. I you see a bufer named *ESS*, then the simple instructions were most likely suc-cessul. I not, then read urther.

4. It could be that you have an older version o Emacs, some other problem with yourinstallation or you are not a sysadmin. Whatever the case, you may need to editess-site.el manually. I that is the case, then you should create a directory just orESS like ~/ess or /usr/local/ess and unpack ESS there. That way, your changes

to ess-site.el will not be lost i you update Emacs later.5. Replace the line above with

(load "~/ess/ess-VERSION/lisp/ess-site")

in ~/.emacs and restart Emacs.

6. I you see a bufer named *ESS*, then the manual instructions were most likely success-ul. I not, then send a query to [email protected] explicitly describingyour problem and your environment including operating system, Emacs version, ESSversion, etc.

XEmacs Simple Instructions: or recent versions o XEmacs (21.x or higher) and ESS,the installation process is simple.

1. Extract all the les rom ess-VERSION.tgz when you are in the currentworking directory o /usr/local/LOCATION/xemacs/site-packages whichexists or packages like ESS where LOCATION i s lib or legacy installationsand share now (and or Mac OS X create a link to it rom the directory/Applications/XEmacs.app/Contents/Resources/site-lisp ):

%prompt gtar zxf ess-VERSION.tgz # for GNU tar

%prompt gunzip < ess-VERSION.tgz | tar xf - # for Unix tar

2. Then, add the line
http://ess.r-project.org/index.php?Section=downloadmailto:[email protected]:[email protected]://ess.r-project.org/index.php?Section=download


19/80


(require ess-site)

to ~/.xemacs/init.el and restart XEmacs.

3. I you see a bufer named *ESS*, then the simple instructions were most likely suc-

cessul. I not, then read urther.4. It could be that you have an older version o XEmacs, some other problem with your

installation or you are not a sysadmin. Whatever the case, you may need to editess-site.el manually. I that is the case, then you should create a directory just orESS like ~/ess or /usr/local/ess and unpack ESS there. That way, your changesto ess-site.el will not be lost i you update XEmacs later.

5. Replace the line above with

(load "~/ess/ess-VERSION/lisp/ess-site")

in ~/.xemacs/init.el and restart XEmacs.

6. I you see a bufer named *ESS*, then the manual instructions were most likely success-ul. I not, then send a query to [email protected] explicitly describing

your problem and your environment including operating system, XEmacs version, ESSversion, etc.

1. (OPTIONAL) COMPILING E-LISP:

Edit the deault locations o LISPDIR, INFODIR and ETCDIR in Section 1 o Makeconf(i you are using XEmacs, then edit the XEmacs subsection in Section 1).

You can compile those les by:

make all

When that completes successully, install the compiled les:

make install

2.2 Microsot Windows installationFor Microsot Windows installation, please ollow the next steps. Retrieve the latest zip le(ess-VERSION.zip) rom ESS downloads area.

GNU Emacs Simple Instructions: or recent versions o Emacs (22.x or higher) and ESS,the installation process is simple.

1. Extract all the les rom ess-VERSION.zip (by double clicking on it and selectingExtract all les which launches the Folders Extraction Wizard) into the site-lispdirectory that exists or packages like ESS. I GNU Emacs was installed in the de-ault location, then this directory can be ound somewhere like C:\Program Files\GNUEmacs\emacs-22.x\site-lisp.

2. Add the line(require ess-site)

to ~/.emacs and restart Emacs.


4. It could be you have an older version o Emacs or some other problem with your instal-lation. Either way, you may need to edit C:\ess\ess-VERSION\lisp\ess-site.elmanually. I that is the case, then you should create a directory just
mailto:[email protected]://ess.r-project.org/index.php?Section=downloadhttp://ess.r-project.org/index.php?Section=downloadmailto:[email protected]


20/80


or ESS like C:\ess and unpack ESS there. That way, your changes toC:\ess\ess-VERSION\lisp\ess-site.el will not be lost i you update Emacs later.

5. Replace the line above with

(load "C:/ess/ess-VERSION/lisp/ess-site")in ~/.emacs and restart Emacs.

6. I you see a bufer named *ESS*, then the manual instructions were most likely success-ul. I not, then send a query to [email protected] explicitly describingyour problem and your environment including operating system, Emacs version, ESSversion, etc.

XEmacs Simple Instructions: or recent versions o XEmacs (21.x or higher), the instal-lation process is much simpler. Hopeully, these simple instructions will work or you. Inot, then more detailed, manual instructions ollow.

1. Extract all the les rom ess-VERSION.zip (by double clicking on it and selecting Ex-tract all les which launches the Folders Extraction Wizard) into the site-packages

directory that exists or packages like ESS. I XEmacs was installed in the deault loca-tion, then this directory can be ound at C:\Program Files\XEmacs\site-packages.

2. XEmacs requires the HOME environment variable to be dened. You can create it byvisiting the ollowing dialog: My Computer->Control Panel->System->Advanced->Environment Variables In the User variables window, press New. And create avariable named HOME with a value something like (you must use orward slashes /rather than backslashes \) c:/Documents and Settings/%USERNAME%/ApplicationData. Then press OK or that window and press OK or the main window. I you alsohave GNU Emacs installed, GNU Emacs will recognize HOME and expand ~ accordingly.

3. Now launch XEmacs and do a C-x C-f ollowed by a ~. From the Subdir menu, selectCreate Directory, and enter .xemacs

4. Add the line

(require ess-site)

to ~/.xemacs/init.el and restart XEmacs.


6. It could be you have an older version o XEmacs or some other problem with your instal-lation. Either way, you may need to edit C:\ess\ess-VERSION\lisp\ess-site.elmanually. I that is the case, then you should create a directory justor ESS like C:\ess and unpack ESS there. That way, your changes toC:\ess\ess-VERSION\lisp\ess-site.el will not be lost i you update XEmacs

later.7. Replace the line above with

(load "C:/ess/ess-VERSION/lisp/ess-site")

in ~/.xemacs/init.el and restart XEmacs.

8. I you see a bufer named *ESS*, then the manual instructions were most likely success-ul. I not, then send a query to [email protected] explicitly describingyour problem and your environment including operating system, XEmacs version, ESSversion, etc.
mailto:[email protected]:[email protected]:[email protected]:[email protected]


21/80


Now, you should be ready to use ESS. For example, to edit statistical programs, load theles with the requisite extensions (".sas" or SAS, ".S" or "s" or "q" or "Q" or S-PLUS,".r" or ".R" or R, and ".lsp" or XLispStat). One urther step is needed i you wish to runstatistical processes, see below.

To run statistical processes under ESS, Windows users will need to make sure that thedirectories or the sotware they will be using is in the PATH environment variable.

On Windows NT/2000/XP, add the directories to the PATH using the My Computer->Control Panel->System->Advanced->Environment Variables menu. Note that the di-rectory containing the program is added to the PATH, not the program itsel. One suchline is needed or each sotware program. Be sure to use the abbreviation progra~1 andnot the long version with embedded blanks as this may cause problems. Also, make sure touse backslashes \ since Windows requires them.

An alternative, or R users, is that rather than adjusting the PATH variable, you canadd the ollowing to your emacs initialization le (and restart emacs):

(setq inferior-R-program-name "c:/progra~1/R/R-2.2.1/bin/Rterm.exe")This assumes that you have installed R-2.2.1 in the deault location. Change the path

otherwise to point to other locations.

Windows users who place S-PLUS anywhere other than the deault location will alsoneed to add the ollowing three lines (properly adjusted or their location):

(setq-default inferior-S+6-program-name

"c:/progra~1/Insightful/SPLUS70/cmd/Splus")

(setq-default inferior-Sqpe+6-SHOME-name

"c:/progra~1/Insightful/SPLUS70")

(setq-default inferior-Sqpe+6-program-name

"c:/progra~1/Insightful/SPLUS70/cmd/Sqpe.exe")

The above example uses the deault location o S-PLUS in c:\progra~1\Insightful.Please note that ESS considers S-PLUS 6, 7, and 8 to be variants o S+6.

These users may also need to modiy the emacs variable ess-SHOME-versions to matchtheir installation in order to get the ull set o S-PLUS versions on their machine into theESS menu.

To start the S-PLUS [678].x GUI rom ESS under emacs:

1. I you use Cygwin bash as your primary shell, then

M-x S

(or M-x S+6).

2. I you use the MSDOS prompt window as your primary shell, then

M-x S+6-msdos

You will then be asked or a pathname ("S starting data directory?"), rom which tostart the process. The prompt will propose your current directory as the deault. ESS willstart the S-PLUS GUI. There will be slight delay during which emacs is temporarily rozen.ESS will arrange or communication with the S-PLUS GUI using the DDE protocol. Sendlines or regions rom the emacs bufer containing your S program (or example, myfile.s)to the S-PLUS Commands Window with the C-c C-n or C-c C-r keys. (I you are still usingS-PLUS 4.x or 2000,\ then use M-x S+4 or M-x S+4-msdos.)


22/80


To start an S-PLUS [678].x session inside an emacs buferand without the S-PLUSGUI:

M-x Sqpe

(or M-x Sqpe+6).

This works with both the bash and msdos shells. You will then be asked or a pathname("S starting data directory?"), rom which to start the process. The prompt will proposeyour current directory as the deault. You get Unix-like behavior, in particular the entiretranscript is available or emacs-style search commands. Send lines or regions rom theemacs bufer containing your S program (or example, myfile.s) to the *S+6* bufer withthe C-c C-n or C-c C-r keys. Interactive graphics are available with Sqpe by using the javalibrary supplied with S-PLUS 6.1 and newer releases. Enter the commands:

library(winjava)

java.graph()

Graphs can be saved rom the java.graph device in several ormats, but not PostScript.

I you need a PostScript le you will need to open a separate postscript device. (I youare still using S-PLUS 4.x or 2000, then use M-x Sqpe+4.)

To connect to an already running S-PLUS GUI (started, or example, rom the S-PLUSicon):

M-x S+6-existing

or

M-x S+6-msdos-existing

You will then be asked or a pathname ("S starting data directory?"), rom which to startthe process. The prompt will propose your current directory as the deault. ESS will arrangeor communication with the already running S-PLUS GUI using the DDE protocol. Sendlines or regions rom the emacs bufer containing your S program (or example, myfile.s)

to the S-PLUS Commands Window with the C-c C-n or C-c C-r keys. (I you are still usingS-PLUS 4.x or 2000, then use M-x S+4-existing or M-x S+4-msdos-existing.)

I you wish to run R, you can start it with:

M-x R

XLispStat can not currently be run with

M-x XLS

Hopeully, this will change. However, you can still edit with emacs, and cut and pastethe results into the XLispStat *Listener* Window under Microsot Windows.

2.3 Requirements

ESS is most likely to work with current/recent versions o the ollowing statistical packages:R/S-PLUS, SAS, Stata and JAGS. The one exception is BUGS which is quite old, butshould still work.

ESS supports current/recent versions o GNU Emacs and XEmacs. Most notably, theGNU Emacs 22 series and XEmacs 21.4.14 or higher (beta/pre-release versions are NOTSUPPORTED).


23/80

Chapter 3: Interacting with statistical programs 22

3 Interacting with statistical programs

As well as using ESS to edit your source les or statistical programs, you can use ESS torun these statistical programs. In this chapter, we mostly will reer by example to runningS rom within emacs. The emacs convention is to name such processes running under itscontrol as inerior processes. This term can be slightly misleading, in which case theseprocesses can be thought o interactive processes. Either way, we use the term iESS toreer to the Emacs mode used to interact with statistical programs.

3.1 Starting an ESS process

To start an S session on Unix or on Windows when you use the Cygwin bash shell, simplytype M-x S RET.

To start an S session on Windows when you use the MSDOS prompt shell, simply typeM-x S+6-msdos RET.

S will then (by deault) ask the questionS starting data directory?

Enter the name o the directory you wish to start S rom (that is, the directory you wouldhave cdd to beore starting S rom the shell). This directory should have a .Data subdi-rectory.

You will then be popped into a bufer with name *S* which will be used or interactingwith 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 o the process is shown in the mode line in squarebrackets (or example, [S+3:2]); this is useul i the process bufer is renamed. Without aprex argument, M-x S starts a new ESS process, using the rst available process number.With a prex argument (or R), C-u M-x R allows or the specication o command lineoptions.

You can switch to any active ESS process with the command M-xess-request-a-process. Just enter the name o the process you require; com-pletion is provided over the names o all running S processes. This is a good command toconsider binding to a global key.

3.3 ESS processes on Remote ComputersESS works with processes on remote computers as easily as with processes on the localmachine. The recommended way to access a statistical program on remote computer is tostart it rom a telnet or ssh bufer and then connect ESS to that bufer.

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

2. Start the ESS process on the remote machine, or example with one o the commandsSplus, or R, or sas -stdio.
ftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.elftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.el


24/80


3. Enter the ESS command M-x ess-remote. You will be prompted or a program name.Enter sp6 or r or sas or another valid name. Your telnet process is now knownto ESS. All the usual ESS commands (C-c C-n and its relatives) now work with theS language processes. For SAS you need to use a diferent command C-c i (that is aregular i, not a C-i) to send lines rom your myfile.sas to the remote SAS process.C-c i sends lines over invisibly. With ess-remote you get teletype behaviorthe datainput, the log, and the listing all appear in the same bufer. To make this work, youneed 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. I you run X11 (See Section 13.3.2 [X11],page 67, X-windows) on both the local and remote machines then you should be able todisplay the graphs locally by setting the DISPLAY environment variable appropriately.Windows users can download xfree86 rom cygwin.

5. Graphics (static) on the remote machine. I you dont run the X window system on thelocal machine, then you can write graphics to a le on the remote machine, and displaythe le in a graphics viewer on the local machine. Most statistical sotware can writeone or more o postscript, GIF, or JPEG les. Depending on the versions o emacs andthe operating system that you are running, emacs itsel may display .gif and .jpgles. Otherwise, a graphics le viewer will be needed. Ghostscript/ghostview may bedownloaded to display .ps and .eps les. Viewers or GIF and JPEG are usuallyincluded with operating systems. See Section 10.5 [ESS(SAS)Function keys or batchprocessing], page 56, or more inormation on using the F12 key or displaying graphicsles with SAS.

Should you or a colleague inadvertently start a statistical process in an ordinary*shell* bufer, the ess-remote command can be used to convert it to an ESS bufer

and allow you to use the ESS commands with it.We have two older commands, now deprecated, or accessing ESS processes on remote

computers. See Section 3.4 [S+elsewhere and ESS-elsewhere], page 23.

3.4 S+elsewhere and ESS-elsewhere

These commands are now deprecated. We recommend ess-remote. We have two versionso the elsewhere unction. S+elsewhere is specic or the S-Plus program. The moregeneral unction ESS-elsewhere is not as stable.

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

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

2. The *S+3* bufer will appear with a prompt rom the local operating system (theunix prompt on a unix workstation or with cygwin bash on a PC, or the msdos prompton a PC without bash). emacs may reeze because the cursor is at the wrong place.Unreeze it with C-g then move the cursor to the end with M->. With S+elsewherethe bufer name is based on the name o the ESS program.


25/80


3. Enter telnet [email protected] (or ssh [email protected]). You willbe prompted or your password on the remote machine. Use M-x send-invisiblebeore typing the password itsel.

4. Beore starting the ESS process, type stty -echo nl at the unix prompt. The -echoturns of the echo, the nl turns of the newline that you see as ^M.

5. You are now talking to the unix prompt on the other machine in the *S+3* bufer. cdinto the directory or the current project and start the ESS process by entering Splusor R or sas -stdio as appropriate. I you can login remotely to your Windows 2000,then you should be able to run Sqpe on the Windows machine. I havent tested thisand noone has reported their tests to me. You will not be able to run the GUI throughthis text-only connection.

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

7. Graphics on the remote machine works ne. I you run the X window system on theremote unix machine you should be able to display them in xfree86 on your PC. Iyou dont run X11, then you can write graphics to the postscript device and copy it toyour PC with dired and display it with ghostscript.

3.5 Changing the startup actions

I you do not wish ESS to prompt or a starting directory when starting a new process, setthe variable ess-ask-for-ess-directory to nil. In this case, the starting directory willbe set using one o the ollowing methods:

1. I the variable ess-directory-function stores the name o a unction, the value re-

turned by this unction is used. The deault or this variable is nil.2. Otherwise, i the variable ess-directory stores the name o a directory (ending in a

slash), this value is used. The deault or this variable is nil.

3. Otherwise, the working directory o the current bufer is used.

I ess-ask-for-ess-directory has a non-nil value (as it does by deault) then thevalue determined by the above rules provides the deault when prompting or the startingdirectory. Incidentally, ess-directory is an ideal variable to set in ess-pre-run-hook.

I you like to keep a record o your S sessions, set the variable ess-ask-about-transfileto t, and you will be asked or a lename or the transcript beore the ESS process starts.

[User Option]ess-ask-about-transfile

I non-nil, as or a le name in which to save the session transcript.Enter the name o a le in which to save the transcript at the prompt. I the le doesnt

exist it will be created (and you should give it a le name ending in .St); i the le alreadyexists the transcript will be appended to the le. (Note: i you dont set this variable butyou still want to save the transcript, you can still do it later see Section 4.4.4 [Savingtranscripts], page 30.)

Once these questions are answered (i they are asked at all) the S process itsel is startedby calling the program name specied in the variable inferior-ess-program. I you need


26/80


to pass any arguments to this program, they may be specied in the variable inferior-S_program_name -args (e.g. i inferior-ess-program is "S+" then the variable to set isinferior-S+-args. It is not normally necessary to pass arguments to the S program; inparticular do not pass the -e option to Splus, since ESS provides its own command historymechanism.

By deault, the new process will be displayed in the same window in the current rame. Iyou wish your S process to appear in a separate variable, customize the variable inferior-ess-own-frame. Alternatively, change inferior-ess-same-window i you wish the processto appear within another window o the current rame.


27/80

Chapter 4: Interacting with the ESS process 26

4 Interacting with the ESS process

The primary unction o the ESS package is to provide an easy-to-use ront end to theS interpreter. This is achieved by running the S process rom within an Emacs bufer,so that the Emacs editing commands are available to correct mistakes in commands, etc.The eatures o Inerior S mode are similar to those provided by the standard Emacs shellmode (see Section Shell Mode in The Gnu Emacs Reerence Manual). Command-linecompletion o S objects and a number o hot keys or commonly-used S commands arealso provided or ease o typing.

4.1 Entering commands and xing mistakes

Sending a command to the ESS process is as simple as typing it in and pressing the RETURNkey:

RET (inferior-ess-send-input)

Send the command on the current line to the ESS process.I you make a typing error beore pressing RETall the usual Emacs editing commands are

available to correct it (see Section Basic editing commands in The GNU Emacs ReerenceManual). Once the command has been corrected you can press RETURN (even i the cursoris not at the end o the line) to send the corrected command to the ESS process.

ESS provides some other commands which are useul or xing mistakes:

C-c C-w (backward-kill-word)Deletes the previous word (such as an object name) on the command line.

C-c C-u (comint-kill-input)Deletes everything rom the prompt to point. Use this to abandon a command youhave not yet sent to the ESS process.

C-c C-a (comint-bol)Move to the beginning o the line, and then skip orwards past the prompt, i any.

See Section Shell Mode in The Gnu Emacs Reerence Manual, or other commandsrelevant to entering input.

4.2 Completion o object names

In the process bufer, the TAB key is or completion, similar to that provided by Shell Modeor lenames. In Inerior S mode, pressing the TAB key when the cursor is ollowing the rstew characters o an object name completes the object name; i the cursor is ollowing a lename TAB completes the le name.

TAB (comint-dynamic-complete)Complete the S object name or lename beore point.

When the cursor is just ater a partially-completed object name, pressing TAB providescompletion in a similar ashion to tcsh except that completion is perormed over all knownS object names instead o le names. ESS maintains a list o all objects known to S at anygiven time, which basically consists o all objects (unctions and datasets) in every attacheddirectory listed by the search() command along with the component objects o attacheddata rames (i your version o S supports them).
http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/


28/80


For example, consider the three unctions (available in Splus version 3.0) calledbinomplot(), binom.test() and binomial(). Typing bin TAB ater the S prompt willinsert the characters om, completing the longest prex (binom) which distinguishes thesethree commands. Pressing TAB once more provides a list o the three commands whichhave this prex, allowing you to add more characters (say, .) which speciy the unctionyou desire. Ater entering more characters pressing TAB yet again will complete the objectname up to uniqueness, etc. I you just wish to see what completions exist without addingany extra characters, type M-?.

M-? (ess-list-object-completions)List all possible completions o the object name at point.

ESS also provides completion over the components o named lists accessed using the $notation, to any level o nested lists. This eature is particularly useul or checking whatcomponents o a list object exist while partway through entering a command: simply typethe object name and $ and press TABto see the names o existing list components or that

object.

Completion is also provided over le names, which is particularly useul when using Sunctions such as get() or scan() which require ully expanded le names. Whenever thecursor is within an S string, pressing TAB completes the le name beore point, and alsoexpands any ~ or environment variable reerences.

I the cursor is not in a string and does not ollow a (partial) object name, the TAB keyhas a third use: it expands history reerences. See Section 4.6 [History expansion], page 31.

4.3 Completion details

ESS automatically keeps track o any objects added or deleted to the system (such as newobjects created, or directories added to the search list) to make completion as accurate aspossible. Whenever ESS notices that search list has changed 1 when you attach a directoryor data rame, the objects associated with it immediately become available or a completion;when it is detached completion is no longer available on those objects.

To maintain a list o accessible objects or completion, ESS needs to determine whichobjects are contained in each directory or data rame on the search list. This is done at thestart o each S session, by running the objects() command on every element o the searchlist.

Eciency in completion is gained by maintaining a cache o objects currently knownto S; when a new object becomes available or is deleted, only one component o the cachecorresponding to the associated directory needs to be rereshed. I ESS ever becomes con-used about what objects are available or completion (such as when i reuses to completean object you know is there), the command M-x ess-resynch orces the entire cache to berereshed, which should x the problem.

1 The variable ess-change-sp-regexp is a regular expression matching commands which change the searchlist. You will need to modiy this variable i you have dened custom commands (other than attach,detach, collection or library) which modiy the search list.


29/80


4.4 Manipulating the transcript

Most o the time, the cursor spends most o its time at the bottom o the ESS process bufer,entering commands. However all the input and output rom the current (and previous) ESS

sessions is stored in the process bufer (we call this the transcript) and oten we want to moveback up through the bufer, to look at the output rom previous commands or example.

Within the process bufer, a paragraph is dened as the prompt, the command ater theprompt, and the output rom the command. Thus M-{ and M-} move you backwards andorwards, respectively, through commands in the transcript. A particularly useul commandis M-h (mark-paragraph) which will allow you to mark a command and its entire output(or deletion, perhaps). For more inormation about paragraph commands, see SectionParagraphs in The GNU Emacs Reerence Manual.

I an ESS process nishes and you restart it in the same process bufer, the output romthe new ESS process appears ater the output rom the rst ESS process separated by aorm-eed (^L) character. Thus pages in the ESS process bufer correspond to ESS sessions.Thus, or example, you may use C-x [ and C-x ] to move backward and orwards throughESS sessions in a single ESS process bufer. For more inormation about page commands,see Section Pages in The GNU Emacs Reerence Manual.

4.4.1 Manipulating the output rom the last command

Viewing the output o the command you have just entered is a common occurrence andESS provides a number o acilities or doing this. Whenever a command produces a longishoutput, it is possible that the window will scroll, leaving the next prompt near the middleo the window. The rst part o the command output may have scrolled of the top o thewindow, even though the entire output would t in the window i the prompt were near thebottom o the window. I this happens, you can use the command

C-c C-e (comint-show-maximum-output)

Move to the end o the bufer, and place cursor on bottom line o window.

to make more o the last output visible. (To make this happen automatically or all inputs,set the variable comint-scroll-to-bottom-on-input to t.)

I the rst part o the output is still obscured, use

C-c C-r (comint-show-output)Moves cursor to the previous command line and and places it at the top o the window.

to view it. Finally, i you want to discard the last command output altogether, use

C-c C-o (comint-kill-output)Deletes everything rom the last command to the current prompt.

to delete it. Use this command judiciously to keep your transcript to a more manageable

size.

4.4.2 Viewing older commands

I you want to view the output rom more historic commands than the previous command,commands are also provided to move backwards and orwards through previously enteredcommands in the process bufer:

C-c C-p (comint-previous-input)Moves point to the preceding command in the process bufer.
http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/


30/80


C-c C-n (comint-next-input)Moves point to the next command in the process bufer.

Note that these two commands are analogous to C-p and C-n but apply to command lines

rather than text lines. And just like C-p and C-n, passing a prex argument to these com-mands means to move to the ARGth next (or previous) command. (These commands arealso discussed in Section Shell History Copying in The GNU Emacs Reerence Manual.)

There are also two similar commands (not bound to any keys by deault) which moveto preceding or succeeding commands, but which rst prompt or a regular expression (seeSection Syntax o Regular Expression in The GNU Emacs Reerence Manual), and thenmoves to the next (previous) command matching the pattern.

(comint-backward-matching-input regexp arg)

(comint-forward-matching-input regexp arg)

Search backward (orward) through the transcript bufer or the argth previous (next)command matching regexp. arg is the prex argument; regexp is prompted or in the

minibufer.

4.4.3 Re-submitting commands rom the transcript

When moving through the transcript, you may wish to re-execute some o the commandsyou nd there. ESS provides three commands to do this; these commands may be usedwhenever the cursor is within a command line in the transcript (i the cursor is within somecommand output, an error is signalled). Note all three commands involve the RETURN key.

RET (inferior-ess-send-input)Copy the command under the cursor to the current command line, and execute it.

C-c RET (comint-copy-old-input)Copy the command under the cursor to the current command line, but dont execute

it. Leaves the cursor on the command line so that the copied command may be edited. M-RET (ess-transcript-send-command-and-move)

Copy the command under the cursor to the current command line, and execute it.Moves the cursor to the ollowing command.

When the cursor is not ater the current prompt, the RETURN key has a slightly diferentbehavior than usual. Pressing RETon any line containing a command that you entered (i.e.a line beginning with a prompt) sends that command to the ESS process once again. I youwish to edit the command beore executing it, use C-c RET instead; it copies the commandto the current prompt but does not execute it, allowing you to edit it beore submitting it.

These two commands leave the cursor at the new command line, allowing you to continuewith interactive use o S. I you wish to resubmit a series o commands rom the transcript,

consider using M-RET instead, which leaves the cursor at the command line ollowing theone you re-submitted. Thus by using M-RET repeatedly, you can re-submit a whole series ocommands.

These commands work even i i the current line is a continuation line (i.e. the promptis + instead o >) in this case all the lines that orm the multi-line command areconcatenated together and the resulting command is sent to the ESS process (currently thisis the only way to resubmit a multi-line command to the ESS process in one go). I thecurrent line does not begin with a prompt, an error is signalled. This eature, coupled with
http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/


31/80


the command-based motion commands described above, could be used as a primitive historymechanism. ESS provides a more sophisticated mechanism, however, which is described inSection 4.5 [Command History], page 30.

4.4.4 Keeping a record o your S sessionTo keep a record o your S session in a disk le, use the Emacs command C-x C-w (write-file) to attach a le to the ESS process bufer. The name o the process bufer will(probably) change to the name o the le, but this is not a problem. You can still use S asusual; just remember to save the le beore you quit Emacs with C-x C-s. You can makeESS prompt you or a lename in which to save the transcript every time you start S bysetting the variable ess-ask-about-transfile to t; see Section 3.5 [Customizing startup],page 24. We recommend you save your transcripts with lenames that end in .St. Thereis a special mode (ESS transcript mode see Chapter 5 [Transcript Mode], page 35) orediting transcript les which is automatically selected or les with this sux.

S transcripts can get very large, so some judicious editing is appropriate i you are saving

it in a le. Use C-c C-o whenever a command produces excessively long output (printinglarge arrays, or example). Delete erroneous commands (and the resulting error messagesor other output) by moving to the command (or its output) and typing M-h C-w. Also,remember that C-c C-e (and other hot keys) may be used or commands whose output youdo not wish to appear in the transcript. These suggestions are appropriate even i you arenot saving your transcript to disk, since the larger the transcript, the more memory yourEmacs process will use on the host machine.

Finally, i you intend to produce S source code (suitable or using with source() orinclusion in an S unction) rom a transcript, then the command M-x ess-transcript-clean-region may be o use. This command works in any Emacs bufer, and removes allprompts and command output rom an ESS transcript within the current region, leaving

only the commands. Dont orget to remove any erroneous commands rst!

4.5 Command History

ESS provides easy-to-use acilities or re-executing or editing previous commands. An inputhistory o the last ew commands is maintained (by deault the last 50 commands arestored, although this can be changed by setting the variable comint-input-ring-size ininferior-ess-mode-hook.) The simplest history commands simply select the next andprevious commands in the input history:

M-p (comint-previous-input)Select the previous command in the input history.

M-n (comint-next-input)Select the next command in the input history.

For example, pressing M-p once will re-enter the last command into the process bufer aterthe prompt but does not send it to the ESS process, thus allowing editing or correction othe command beore the ESS process sees it. Once corrections have been made, press RETto send the edited command to the ESS process.

I you want to select a particular command rom the history by matching it against aregular expression (see Section Syntax o Regular Expression in The GNU Emacs Reer-
http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/


32/80


ence Manual), to search or a particular variable name or example, these commands arealso available:

M-r (comint-previous-matching-input)Prompt or a regular expression, and search backwards through the input history or acommand matching the expression.

M-s (comint-next-matching-input)Prompt or a regular expression, and search backwards through the input history or acommand matching the expression.

A common type o search is to nd the last command that began with a particular sequenceo characters; the ollowing two commands provide an easy way to do this:

A-M-r (comint-previous-matching-input-from-input)Select the previous command in the history which matches the string typed so ar.

A-M-s (comint-next-matching-input-from-input)Select the next command in the history which matches the string typed so ar.

Instead o prompting or a regular expression to match against, as they instead selectcommands starting with those characters already entered. For instance, i you wanted tore-execute the last attach() command, you may only need to type att and then A-M-rand RET. (Note: you may not have an ALT key on your keyboard, in which case it may bea good idea to bind these commands to some other keys.)

See Section Shell History Ring in The GNU Emacs Reerence Manual, or a moredetailed discussion o the history mechanism.

4.6 Reerences to historical commands

Instead o searching through the command history using the command described in the pre-

vious section, you can alternatively reer to a historical command directly using a notationvery similar to that used in csh. History reerences are introduced by a ! or ^ characterand have meanings as ollows:

!! The immediately previous command

!-N The Nth previous command

!text The last command beginning with the string text

!?text The last command containing the string text

In addition, you may ollow the reerence with a word designator to select particularwords o the input. A word is dened as a sequence o characters separated by whitespace.(You can modiy this denition by setting the value o comint-delimiter-argument-list

to a list o characters that are allowed to separate words and themselves orm words.) Wordsare numbered beginning with zero. The word designator usually begins with a : (colon)character; however it may be omitted i the word reerence begins with a ^, $, * or-. I the word is to be selected rom the previous command, the second ! character canbe omitted rom the event specication. For instance, !!:1 and !:1 both reer to therst word o the previous command, while !!$ and !$ both reer to the last word in theprevious command. The ormat o word designators is as ollows:

0 The zeroth word (i.e. the rst one on the command line)
http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/http://emacs.pdf/


33/80


n The nth word, where n is a number

^ The rst word (i.e. the second one on the command line)

$ The last word

x-y A range o words; -y abbreviates 0-y

* All the words except the zeroth word, or nothing i the command had just oneword (the zeroth)

x* Abbreviates x-$

x- Like x*, but omitting the last word

In addition, you may surround the entire reerence except or the rst ! by braces toallow it to be ollowed by other (non-whitespace) characters (which will be appended to theexpanded reerence).

Finally, ESS also provides quick substitution; a reerence like ^old^new^ means thelast command, but with the rst occurrence o the string old replaced with the stringnew (the last ^ is optional). Similarly, ^old^ means the last command, with the rstoccurrence o the string old deleted (again, the last ^ is optional).

To convert a history reerence as described above to an input suitable or S, you needto expand the history reerence, using the TAB key. For this to work, the cursor must bepreceded by a space (otherwise it would try to complete an object name) and not be withina string (otherwise it would try to complete a lename). So to expand the history reerence,type SPC TAB. This will convert the history reerence into an S command rom the history,which you can then edit or press RET to execute.

For example, to execute the last command that reerenced the variable data, type !?data

SPC TAB RET.

4.7 Hot keys or common commands

ESS provides a number o commands or executing the commonly used unctions. Thesecommands below are basically inormation-gaining commands (such as objects() orsearch()) which tend to clutter up your transcript and or this reason some o the hotkeys display their output in a temporary bufer instead o the process bufer by deault.This behavior is controlled by the variable ess-execute-in-process-buffer which, inon-nil, means that these commands will produce their output in the process buferinstead. In any case, passing a prex argument to the commands (with C-u) will reversethe meaning o ess-execute-in-process-buffer or that command, i.e. the output will

be displayed in the process bufer i it usually goes to a temporary bufer, and vice-versa.These are the hot keys that behave in this way:

C-c C-x (ess-execute-objects)Sends the objects() command to the ESS process. A prex argument species the po-sition on the search list (use a negative argument to toggle ess-execute-in-process-buffer as well). A quick way to see what objects are in your working directory.

C-c C-s (ess-execute-search)Sends the search() command to the ESS process.


34/80


C-c C-e (ess-execute)Prompt or an ESS expression, and evaluate it.

ess-execute may seem pointless when you could just type the command in anyway, but

it proves useul or spot calculations which would otherwise clutter your transcript, or orevaluating an expression while partway through entering a command. You can also use thiscommand to generate new hot keys using the Emacs keyboard macro acilities; see SectionKeyboard Macros in The GNU Emacs Reerence Manual.

The ollowing hot keys do not use ess-execute-in-process-buffer to decide whereto display the output they either always display in the process bufer or in a separatebufer, as indicated:

C-c C-a (ess-execute-attach)Prompts or a directory to attach to the ESS process with the attach() command. Ia numeric prex argument is given it is used as the position on the search list to attachthe directory; otherwise the S deault o 2 is used. The attach() command actually

executed appears in the process bufer. C-c C-l (ess-load-file)

Prompts or a le to load into the ESS process using source(). I there is an errorduring loading, you can jump to the error in the le with C-x (ess-parse-errors).See Section 7.3 [Error Checking], page 43, or more details.

C-c C-v (ess-display-help-on-object)Pops up a help bufer or an S object or unction. See Chapter 9 [Help], page 51 ormore details.

C-c C-q (ess-quit)Sends the q() command to the ESS process (or (exit) to the XLS process), and cleansup any temporary bufers (such as help bufers or edit bufers) you may have created

along the way. Use this command when you have nished your S session instead osimply typing q() yoursel, otherwise you will need to issue the command M-x ess-cleanup comman