ESS – Emacs Speaks Statistics ESS version 15.09-devel The ESS Developers (A.J. Rossini, R.M. Heiberger, K. Hornik, M. Maechler, R.A. Sparapani, S.J. Eglen, S.P. Luque, H. Redestig and V. Spinu) Current Documentation by The ESS Developers Copyright c 2002–2014 The ESS Developers Copyright c 1996–2001 A.J. Rossini Original Documentation by David M. Smith Copyright c 1992–1995 David M.
i Table of Contents 1 Introduction to ESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Why should I use ESS?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1.1 Features Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 New features in ESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3 Authors of and contributors to ESS . . . . . . . . . . . . . . . . . . . . .
ii 7 Editing objects and functions . . . . . . . . . . . . . . . . 37 7.1 7.2 7.3 7.4 Creating or modifying S objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading source files into the ESS process . . . . . . . . . . . . . . . . . . . . . . Detecting errors in source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Indenting and formatting S code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.4.1 Changing indentation styles . . . . . . . . .
iii 12 Overview of ESS features for the S family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 12.1 12.2 12.3 12.4 12.5 12.6 13 68 68 69 69 71 74 75 76 76 ESS[BUGS]–Model files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 ESS[BUGS]–Command files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 ESS[BUGS]–Log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1: Introduction to ESS 1 1 Introduction to ESS The S family (S, Splus and R) and SAS statistical analysis packages provide sophisticated statistical and graphical routines for manipulating data. Emacs Speaks Statistics (ESS) is based on the merger of two pre-cursors, S-mode and SAS-mode, which provided support for the S family and SAS respectively. Later on, Stata-mode was also incorporated. ESS provides a common, generic, and useful interface, through emacs, to many statistical packages.
Chapter 1: Introduction to ESS • • • • • 2 • SAS • OpenBUGS/JAGS • Stata • Julia Editing source code (S family, SAS, OpenBUGS/JAGS, Stata, Julia) • Syntactic indentation and highlighting of source code • Partial evaluation of code • Loading and error-checking of code • Source code revision maintenance • Batch execution (SAS, OpenBUGS/JAGS) • Use of imenu to provide links to appropriate functions Interacting with the process (S family, SAS, Stata, Julia) • Command-line editing • Searchable Command his
Chapter 1: Introduction to ESS 3 • Command-line completion of both object and file names for quick entry. This is similar to tcsh’s facility for filenames; here it also applies to object names and list components. See Chapter 9 [Completion], page 46. • Hot-keys for quick entry of commonly-used commands in ‘S’ such as objects() and search(). See Section 4.5 [Hot keys], page 30. • Transcript recording for a complete record of all the actions in an S session. See Section 4.2 [Transcript], page 25.
Chapter 1: Introduction to ESS • • • • • • • 4 ESS[R]: Detect library and require calls for better completion caching. Buffer display is now customizable (ess-show-buffer-action). Use y-or-n-p instead of yes-or-no-p throughout. More support for ODS in ess-sas-graph-view. Makefiles are now both UNIX and GNU friendly. ESS[R]: Simplify directory lookup in ess-developer (#137). Make closed paren indentation consistent Bug Fixes in 15.03: • Fix open brace indentation bug (#27 in ess/R-ESS-bugs.R).
Chapter 1: Introduction to ESS 5 • ESS[R]: fixed "empty watch window bug" • ESS[R]: don’t ask for help location on ac-quick-help (request of github #81) • ESS[R]: "importClassesFrom" and "importMethodsFrom" were added to the list of two-parameter roxygen commands • ESS[R]: fix vignetes display and hyperlinks (were broken in 13.09-1) • ESS[Julia]: recognize function names ending with ! • ESS[Julia]: fix indentation of "for" comprehension syntax within brackets. Changes / Selected Bug Fixes in 13.
Chapter 1: Introduction to ESS 6 • font-lock in process buffers doesn’t "spill" over prompts. Missing closing string delimiters should not cause wrong fontification of the following command input. • ESS[julia]: full features M-TAB completion and auto-complete support, which now works for modules, structures and data types.
Chapter 1: Introduction to ESS 7 • ESS: process output display is 4-10 times faster due to new caching and only occasional emacs re-display (for the moment this functionality is available only when esstracebug is active). • ESS: C-c ‘ is now bound to ess-show-traceback and C-c ~ is bound to ess-showcall-stack. • ESS[R]: ESS stores function in ’ESSR’ environment to avoid kludging users’ global environment and accidental deletion.
Chapter 1: Introduction to ESS 8 • ESS[tracebug]: A better handling of “Selection” prompts and debug related singlekey commands. • ESS: fix a bug in ess-switch-process that was causing *new* selection to fail. • ESS[R]: Solve missing ess-local-process-name bug in R-dired. • ESS[SWV]: ess-swv-PDF doesn’t ask for a command to run if there is only one command in ess-swv-pdflatex-commands.
Chapter 1: Introduction to ESS 9 • ESS: New “Process” menu entry with process related commands and configuration • iESS: Process buffer is now automatically shown on errors • ESS: New ess-switch-to-inferior-or-script-buffer command bound to C-c C-z in both script and process buffers. If invoked form process buffer it switches to the most recent buffer of the same dialect. It is a single key command.
Chapter 1: Introduction to ESS 10 • ESS[Julia]: Help system works again. Changes/New Features in 12.09: • Due to XEmacs lacking some features that ESS requires, ESS support of XEmacs ends with ESS 12.04-4. This decision will be re-visited in the future as XEmacs continues to sync with GNU Emacs. • ESS[R]: On Windows, there is now a new customizable variable (currently called essdirectory-containing-R) to tell ESS where to look for the ‘Rterm.exe’ executables.
Chapter 1: Introduction to ESS 11 • ESS[R]: R AC sources are no longer auto-starting at 0 characters but at the default ac-auto-start characters. • ESS no longer redefines default ac-sources, but only appends ac-source-filename to it. • ESS: ac-source-R now concatenates “ = “ to function arguments. • ESS: Menus for ESS and iESS have been reorganized and enriched with Tracebug and Developer submenus.
Chapter 1: Introduction to ESS 12 • New make target lisp, to build the lisp-only part, i.e., not building the docs. Changes/New Features in 12.04-1: • iESS[Stata]: New interactive help invocation. • iESS[Stata]: New custom variable inferior-STA-start-file. • iESS[Stata]: inferior-STA-program-name is now “stata” and can be customized. • ESS[Stata] New sections in stata help files Syntax(s-S), Remarks(r), Title(t). Bug Fixes in 12.04-1: • ESS[R]: Better ess-tracebug error handling.
Chapter 1: Introduction to ESS • • • • • • • • • • • • • • 13 a <- some.function(arg1, arg2) This variable should be set as part of indentation style lists, or in ess-mode hook. ESS[R]: C-c . sets (indentation) style. ESS: In ESS buffers yank(C-y) command accepts double argument C-u C-u to paste commands only. It deletes any lines not beginning with a prompt, and then removes the prompt from those lines that remain.
Chapter 1: Introduction to ESS 14 normal fashion. Variable ess-tracebug-inject-source-p controls this behavior - if t, always inject source reference, if ’function, inject only for functions (this is the default), if nil, never inject. During the source injection the value of ess-eval-visibly is ignored. − Org-mode support: Visual debugger is now aware of the temporary org source editing buffer (C-c ’) and jumps through this buffers if still alive, or in original org buffer otherwise.
Chapter 1: Introduction to ESS 15 • ESS[S]: “,“ is bound to ess-smart-comma: If comma is invoked at the process marker of an ESS inferior buffer, request and execute a command from ‘ess-handy-commands’ list. If ess-R-smart-operators is t ‘ess-smart-comma also inserts “ “ after comma. • ESS[S], notably R: Variable ‘ess-handy-commands’ stores an alist of useful commands which are called by ess-smart-comma in the inferior buffer.
Chapter 1: Introduction to ESS 16 • ESS: new functions to manipulate process plists: ess-process-get and ess-processset. • ESS: Internal process waiting mechanism was completely rewritten. ESS no more relies on prompt regular expressions for the prompt detection. The only requirement on the primary process prompt is to end in > . This could be overwritten by setting inferor-ess-primary-prompt. • ESS[S], notably R: Saved command history: ess-history-file now accepts t (default), nil, or a file name.
Chapter 1: Introduction to ESS 17 • Thanks to Martin Maechler for reporting and fixing bugs, providing many useful comments and suggestions, and for maintaining the ESS mailing lists. • Thanks to Frank Ritter for updates, particularly the menu code, and invaluable comments on the manual. • Thanks to Ken’ichi Shibayama for his excellent indenting code, and many comments and suggestions. • Thanks to Aki Vehtari for adding interactive BUGS support.
Chapter 1: Introduction to ESS 18 a consistent user interface within emacs, regardless of the details of which programming language is being edited, or process being run. Some commands, such as M-x R can accept an optional ‘prefix’ argument. To specify the prefix argument, you would type C-u before giving the command. e.g. If you type C-u M-x R, you will be asked for command line options that you wish to invoke the R process with. Emacs is often referred to as a ‘self-documenting’ text editor.
Chapter 2: Installing ESS on your system 19 2 Installing ESS on your system The following section details those steps necessary to get ESS running on your system. 2.1 Step by step instructions 1. Download the latest zip or tgz archive from ESS downloads area and unpack it into a directory where you would like ESS to reside. We will denote this directory as ‘/path/to/ESS/’ hereafter.
Chapter 2: Installing ESS on your system 20 ESS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in the file COPYING in the same directory as this file for more details. 2.3 Stability All recent released versions are meant to be release-quality versions. While some new features are being introduced, we are cleaning up and improving the interface.
Chapter 3: Interacting with statistical programs 21 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 processes running under its control as ‘inferior processes’. This term can be slightly misleading, in which case these processes can be thought of ‘interactive processes’.
Chapter 3: Interacting with statistical programs 22 Alternatively you can start your process normally (M-x R). After you are asked for starting directory, simply type ‘/ssh:user@host: RET’. R process will be started on the remote machine. To simplify the process even further create a "config" file in your .ssh/ folder and add an account. For example if you use amazon EC2, it might look like following: Host amazon Hostname ec2-54-215-203-181.us-west-1.compute.amazonaws.com User ubuntu IdentityFile ~/.
Chapter 3: Interacting with statistical programs 23 We have two older commands, now deprecated, for 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 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’.
Chapter 3: Interacting with statistical programs 24 2. Otherwise, if the variable ess-directory stores the name of a directory (ending in a slash), this value is used. The default for this variable is nil. 3. Otherwise, the working directory of the current buffer is used. If ess-ask-for-ess-directory has a non-nil value (as it does by default) then the value determined by the above rules provides the default when prompting for the starting directory.
Chapter 4: Interacting with the ESS process 25 4 Interacting with the ESS process The primary function of the ESS package is to provide an easy-to-use front end to the S interpreter. This is achieved by running the S process from within an Emacs buffer, called hereafter inferior buffer, which has an active inferior-ess-mode. The features of Inferior S mode are similar to those provided by the standard Emacs shell mode (see Section “Shell Mode” in The Gnu Emacs Reference Manual).
Chapter 4: Interacting with the ESS process 26 Thus, for example, you may use C-x [ and C-x ] to move backward and forwards through ESS sessions in a single ESS process buffer. For more information about page commands, see Section “Pages” in The GNU Emacs Reference Manual. 4.2.1 Manipulating the output from the last command Viewing the output of the command you have just entered is a common occurrence and ESS provides a number of facilities for doing this.
Chapter 4: Interacting with the ESS process 27 whenever the cursor is within a command line in the transcript (if the cursor is within some command output, an error is signalled). Note all three commands involve the RETURN key. RET inferior-ess-send-input See Section 4.1 [Command-line editing], page 25. C-c RET comint-copy-old-input Copy the command under the cursor to the current command line, but don’t execute it. Leaves the cursor on the command line so that the copied command may be edited.
Chapter 4: Interacting with the ESS process 28 4.3 Command History ESS provides easy-to-use facilities for re-executing or editing previous commands. An input history of the last few commands is maintained (by default the last 500 commands are stored, although this can be changed by setting the variable comint-input-ring-size in inferior-ess-mode-hook.
Chapter 4: Interacting with the ESS process 29 (setq comint-scroll-to-bottom-on-output ’others) (setq comint-scroll-show-maximum-output t) ;; somewhat extreme, almost disabling writing in *R*, *shell* buffers above promp (setq comint-scroll-to-bottom-on-input ’this) )) to your ‘.emacs’ file, where the last two settings are typically desirable for the situation where you work with a script (e.g., ‘code.R’) and send code chunks to the process buffer (e.g. *R*).
Chapter 4: Interacting with the ESS process 30 ‘n ’ The nth word, where n is a number ‘^’ The first word (i.e.
Chapter 4: Interacting with the ESS process 31 working directory. A prefix argument of 2 or more means get objects for that position. A negative prefix argument posn gets the objects for that position, as well as toggling ess-execute-in-process-buffer. [Command] C-c C-s Sends the inferior-ess-search-list-command command to the ess-language process; search() in S. Prefix invert toggles ess-execute-inprocess-buffer.
Chapter 4: Interacting with the ESS process 32 4.6 Is the Statistical Process running under ESS? For the S languages (S, S-Plus, R) ESS sets an option in the current process that programs in the language can check to determine the environment in which they are currently running. ESS sets options(STERM="iESS") for S language processes running in an inferior iESS[S] or iESS[R] buffer.
Chapter 4: Interacting with the ESS process 33 Other commands available in Inferior S mode are discussed in Section “Shell Mode” in The Gnu Emacs Reference Manual.
Chapter 5: Sending code to the ESS process 34 5 Sending code to the ESS process Other commands are also available for evaluating portions of code in the S process. These commands cause the selected code to be evaluated directly by the ESS process as if you had typed them in at the command line; the source() function is not used. You may choose whether both the commands and their output appear in the process buffer (as if you had typed in the commands yourself) or if the output alone is echoed.
Chapter 5: Sending code to the ESS process ess-eval-buffer vis 35 [Command] C-c C-b Sends the current buffer to the ESS process. [Command] C-c M-b Like ess-eval-buffer but additionally switches point to the ESS process. ess-eval-buffer-and-go vis All the above ess-eval-* commands are useful for evaluating small amounts of code and observing the results in the process buffer for debugging purposes, or for generating transcripts from source files.
Chapter 6: Manipulating saved transcript files 36 6 Manipulating saved transcript files Inferior S mode records the transcript (the list of all commands executed, and their output) in the process buffer, which can be saved as a transcript file, which should normally have the suffix ‘.St’. The most obvious use for a transcript file is as a static record of the actions you have performed in a particular S session.
Chapter 7: Editing objects and functions 37 7 Editing objects and functions ESS provides facilities for editing S objects within your Emacs session. Most editing is performed on S functions, although in theory you may edit datasets as well. Edit buffers are always associated with files, although you may choose to make these files temporary if you wish. Alternatively, you may make use of a simple yet powerful mechanism for maintaining backups of text representations of S functions.
Chapter 7: Editing objects and functions 38 automatically if the buffer was generated with C-c C-e C-d). The file will then be loaded, and if it loads successfully you will be returned to the ESS process. 7.3 Detecting errors in source files If any errors occur when loading a file with C-c C-l, ESS will inform you of this fact. In this case, you can jump directly to the line in the source file which caused the error by typing C-c ‘ (ess-parse-errors).
Chapter 7: Editing objects and functions 39 [User Option] If non-nil, TAB never tries to complete in ess-mode. The default ’symbol does not try to complete if the next char is a valid symbol constituent. There are more options, see the help (C-h v). ess-first-tab-never-complete [Command] TAB Indents each line in the S (compound) expression which follows point. Very useful for beautifying your S code.
Chapter 7: Editing objects and functions 40 (defun myindent-ess-hook () (setq ess-indent-level 4)) (add-hook ’ess-mode-hook ’myindent-ess-hook) In the rare case that you’d like to add an entire new indentation style of your own, copy the definition of ess-own-style-list to a new variable and ensure that the last line of the :set declaration calls ess-add-style with a unique name for your style (e.g. ’MINE). Finally, add (setq ess-default-style ’MINE) to use your new style. 7.
Chapter 7: Editing objects and functions 41 wanted to look at the definition of one of the standard S functions) the source dump file won’t be left around when you kill the buffer. Note that this variable only applies to files generated with S’s dump function; it doesn’t apply to source files which already exist. The default value is t. [User Option] Variable controlling whether to delete dump files after a successful load. If ‘nil’: always delete. If ‘ask’, confirm to delete.
Chapter 7: Editing objects and functions 42 7.7 Names and locations of dump files Every dump file should be given a unique file name, usually the dumped object name with some additions. [User Option] Template for filenames of dumped objects. %s is replaced by the object name. ess-dump-filename-template By default, dump file names are the user name, followed by ‘.’ and the object and ending with ‘.S’. Thus if user joe dumps the object myfun the dump file will have name ‘joe.myfun.S’.
Chapter 7: Editing objects and functions 43 If the directory generated by the lambda function does not exist but can be created, you will be asked whether you wish to create the directory. If you choose not to, or the directory cannot be created, you will not be able to edit functions.
Chapter 8: Reading help files 44 8 Reading help files ESS provides an easy-to-use facility for reading S help files from within Emacs. From within the ESS process buffer or any ESS edit buffer, typing C-c C-v (ess-display-help-onobject) will prompt you for the name of an object for which you would like documentation. Completion is provided over all objects which have help files. If the requested object has documentation, you will be popped into a buffer (named *help(obj-name )*) containing the help file.
Chapter 8: Reading help files ‘R’ REQUIRED ARGUMENTS: ‘r’ REFERENCES: ‘s’ SEE ALSO: ‘S’ SIDE EFFECTS: ‘u’ USAGE: ‘v’ VALUE: ‘<’ Jumps to beginning of file ‘>’ Jumps to end of file ‘?’ Pops up a help buffer with a list of the defined section motion keys. 45 Evaluation: l ess-eval-line-and-step Evaluates the current line in the ESS process, and moves to the next line. Useful for running examples in help files. r ess-eval-region Send the contents of the current region to the ESS process.
Chapter 9: Completion 46 9 Completion 9.1 Completion of object names The TAB key is for completion. The value of the variable ess-first-tab-never-complete controls when completion is allowed controls when completion is allowed to occur. In essmode TAB first tries to indent, and if there is nothing to indent, complete the object name instead. TAB comint-dynamic-complete Complete the S object name or filename before point.
Chapter 9: Completion 47 9.2 Completion of function arguments When inside a function call (i.e. following ‘(’), TAB completion also provides function arguments. If function is a generic, completion will provide all the arguments of S3 methods known to R. A related functionality is See Section 11.1 [ESS ElDoc], page 56, which displays function arguments in the echo area whenever the point is inside a function call. 9.3 Minibuffer completion From version 12.
Chapter 9: Completion 48 Once installed, Icicles can be activated by evaluating (maybe place in ‘~/.emacs’): (require ’icicles) (icy-mode 1) Icicles can be toggled at any moment by typing M-x icy. When Icicles is on, TAB offers completion, provided the conditions determined by essfirst-tab-never-complete allow it. Typing M-TAB will attempt completion regardless. Typing M-? in ESS or iESS modes brings up the relevant completion candidates from which to choose.
Chapter 10: Developing with ESS 49 10 Developing with ESS ESS provides several tools to help you with the development of your R packages: 10.1 ESS tracebug ESS tracebug offers visual debugging, interactive error navigation, interactive backtrace, breakpoint manipulation, control over R error actions, watch window and interactive flagging/unflagging of functions for debugging. From ESS13.05 ess-tracebug is on by default. You can toggle it on and off with M-x ess-tracebug.
Chapter 10: Developing with ESS w 50 . Watch window . ‘ess-watch’ (C- prefixed equivalents are also defined) * Navigation to errors (general emacs functionality): C-x ‘, M-g n M-g p . ‘next-error’ . ‘previous-error’ * Misc: ? . Show this help . ‘ess-tracebug-show-help’ To configure how electric watch window splits the display see ess-watch-widththreshold and ess-watch-height-threshold variables. A more detailed ess-tracebug documentation with screenshots is available at http://code.google.
Chapter 10: Developing with ESS 51 Describe the features of Rd mode. C-h m LFD RET Reindent the current line, insert a newline and indent the new line (reindentthen-newline-and-indent). An abbrev before point is expanded if abbrevmode is non-nil. TAB Indent current line based on its contents and on previous lines. (indentaccording-to-mode). C-c C-e Insert a “skeleton” with Rd markup for at least all mandatory entries in Rd files (Rd-mode-insert-skeleton).
Chapter 10: Developing with ESS 52 10.2.2 Editing Roxygen documentation The Roxygen R package makes it possible to keep the intended contents for Rd files as structured comments in the R source files. Roxygen can then parse R files and generate appropriate Rd files from these comments, fill the usage fields as well as updating ‘NAMESPACE’ files. See the Roxygen documentation found via http://roxygen.org for more information on its usage.
Chapter 10: Developing with ESS 53 of-open, i.e. C-u C-c C-e C-t, visit the generated HTML file instead. Requires the Roxygen and tools packages to be installed. ess-roxy-previous-entry [Command] C-c C-o p Go to start of the Roxygen entry above point. ess-roxy-next-entry [Command] C-c C-o n Go to end of the Roxygen entry above point. [Command] C-c C-o C-h Use the hideshow mode to fold away the visibility of all Roxygen entries. Hide-show support must be enabled for this binding to get defined.
Chapter 10: Developing with ESS 54 In order to use ess-developer you must add names of the packages that you are developing to ess-developer-packages. You can also do that interactively with C-c C-t C-a. To remove packages from ess-developer-packages use C-c C-t C-r. When developer mode is on, the process mode line indicator displays a small or capital letter "d".
Chapter 10: Developing with ESS 55 Class "boo" is defined (with package slot foo) but no metadata object found to revise subclass information---not exported? You can safely ignore this warnings. − S4 METHODS: Similarly to function definitions modified methods are assigned in the local method table in the namespace:foo. New methods are assigned into .GlobalEnv, but with the environment pointing to namespace:foo. There is a suttle catch with method caching in R though. See the code in etc/ESSR/developer.
Chapter 11: Other ESS features and tools 56 11 Other ESS features and tools ESS has a few extra features, which didn’t fit anywhere else. 11.1 ElDoc In ElDoc mode, the echo area displays function’s arguments at point. From ESS version 12.03, ElDoc is active by default in ess-mode and inferior-ess-mode buffers. To activate it only in ess-mode buffers, place the following into your init file: (setq ess-use-eldoc ’script-only) [User Option] If ‘t’, activate eldoc in ess-mode and inferior-ess-mode buffers.
Chapter 11: Other ESS features and tools search ess-execute-search set-width ess-execute-screen-options 57 install.packages ess-install.packages library ess-library setRepos ess-setRepositories sos ess-sos Handy commands: ess-library, ess-install.packages, etc - ask for item with completion and execute the correspond command. ess-sos is a interface to findFn function in package sos. If package sos is not found, ask user for interactive install. 11.
Chapter 11: Other ESS features and tools 58 11.5 Using graphics with ESS One of the main features of the S package is its ability to generate high-resolution graphics plots, and ESS provides a number of features for dealing with such plots. 11.5.1 Using ESS with the printer() driver This is the simplest (and least desirable) method of using graphics within ESS. S’s printer() device driver produces crude character based plots which can be contained within the ESS process buffer itself.
Chapter 11: Other ESS features and tools 59 11.8 TAGS The Emacs tags facility can be used to navigate around your files containing definitions of S functions. This facility is independent of ESS usage, but is written here since ESS users may wish to take advantage of TAGS facility. Read more about emacs tags in an emacs manual. Etags, the program that generates the TAGS file, does not yet know the syntax to recognise function definitions in S files.
Chapter 11: Other ESS features and tools 60 11.10 Rutils Ess-rutils builds up on ess-rdired, providing key bindings for performing basic R functions in the inferior-ESS process buffer, such as loading and managing packages, object manipulation (listing, viewing, and deleting), and alternatives to help.start() and RSiteSearch() that use the browse-url Emacs function. The library can be loaded using M-x load-file, but the easiest is to include: (require ’ess-rutils) in your .emacs.
Chapter 11: Other ESS features and tools 61 11.11 Interaction with Org mode Org-mode (http://orgmode.org) now supports reproducible research and literate programming in many languages (including R) – see chapter 14 of the Org manual (http://orgmode.org/org.html#Working-With-Source-Code). For ESS users, this offers a document-based work environment within which to embed ESS usage.
Chapter 12: Overview of ESS features for the S family 62 12 Overview of ESS features for the S family 12.1 ESS[S]–Editing files ESS[S] is the mode for editing S language files. This mode handles: − proper indenting, generated by both [Tab] and [Return]. − color and font choices based on syntax. − ability to send the contents of an entire buffer, a highlighted region, an S function, or a single line to an inferior S process, if one is currently running.
Chapter 12: Overview of ESS features for the S family 63 In the (rare) case that you wish to pass command line arguments to the starting S+6 process, set the variable inferior-Splus-args. Note that R has some extremely useful command line arguments. For example, -vanilla will ensure R starts up without loading in any init files.
Chapter 12: Overview of ESS features for the S family 64 ’( ("Splus64" "/usr/local/bin/Splus64") ("Splus64-j" "/usr/local/bin/Splus64" "-j"))) which will then allow you to do M-x Splus64-j to start Splus64 with the corresponding command line arguments. If you change the value of either ess-s-versions or ess-s-versions-list, you should put them in your .emacs before ess-site is loaded, since the new emacs functions are created when ESS is loaded.
Chapter 12: Overview of ESS features for the S family ## Edit as appropriate, and then start up S-PLUS 3.x M-x S+3 ## A new buffer *S+3:1* will appear. Splus will have been started ## in this buffer. The buffer is in iESS [S+3:1] mode. ## Split the screen and go back to the file editing buffer. C-x 2 C-x b myfile.s ## Send regions, lines, or the entire file contents to S-PLUS. For regions, ## highlight a region with keystrokes or mouse and then send with: C-c C-r ## Re-edit myfile.
Chapter 12: Overview of ESS features for the S family 66 3: ## Program revision example (S object is real) ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) M-x S+3 ## Dump an existing S object my.function into a buffer to work with C-c C-d my.function ## a new buffer named yourloginname.my.function.S will be created with ## an editable copy of the object. The buffer is associated with the ## pathname /tmp/yourloginname.my.function.
Chapter 12: Overview of ESS features for the S family 67 C-c C-d my.cool.function ## Edit the function as appropriate, and dump back in to the ## process buffer C-c C-b ## Return to the S-PLUS process buffer C-c C-y ## Continue working. ## When you need help, use C-c C-v rchisq ## instead of entering: help("rchisq") 12.6 Customization Examples and Solutions to Problems 1. Suppose that you are primarily an SPLUS 3.
Chapter 13: ESS for SAS 68 13 ESS for SAS ESS[SAS] was designed for use with SAS. It is descended from emacs macros developed by John Sall for editing SAS programs and SAS-mode by Tom Cook. Those editing features and new advanced features are part of ESS[SAS]. The user interface of ESS[SAS] has similarities with ESS[S] and the SAS Display Manager. 13.1 ESS[SAS]–Design philosophy ESS[SAS] was designed to aid the user in writing and maintaining SAS programs, such as ‘foo.sas’.
Chapter 13: ESS for SAS 69 13.3 ESS[SAS]–TAB key Two options. The TAB key is bound by default to sas-indent-line. This function is used to syntactically indent SAS code so PROC and RUN are in the left margin, other statements are indented sas-indent-width spaces from the margin, continuation lines are indented sasindent-width spaces in from the beginning column of that statement. This is the type of functionality that emacs provides in most programming language modes.
Chapter 13: ESS for SAS 70 ess-sas-submit-command: "sas8" End: The command line is also made of ess-sas-submit-pre-command, ess-sas-submitpost-command and ess-sas-submit-command-options (the last of which is also bufferlocal). Here are some examples for your ‘~/.emacs’ or ‘~/.xemacs/init.
Chapter 13: ESS for SAS 71 F5 (F6) Now, ‘refresh’ the ‘.lst’ and go to it’s buffer. F6 (F7) If you wish to make changes, go to the ‘.sas’ file with. F4 (F5) Make your editing changes and submit again. F3 (F8) 13.5 ESS[SAS]–Function keys for batch processing The setup of function keys for SAS batch processing is unavoidably complex, but the usage of function keys is simple. There are five distinct options: Option 1 (default). Function keys in ESS[SAS] are not bound to elisp commands.
Chapter 13: ESS for SAS 72 Finally, we get to what the function keys actually do. You may recognize some of the nicknames as SAS Display Manager commands (they are in all capitals). UNIX PC F2 F2 F3 F8 F4 F5 F5 F6 F6 F7 F7 F4 F8 F3 F9 F9 F10 F10 F11 F11 F12 F12 C-F1 C-F1 C-F2 C-F2 C-F3 C-F8 C-F5 C-F6 C-F6 C-F7 C-F9 C-F9 Nickname ‘refresh’ revert the current buffer with the file of the same name if the file is newer than the buffer SUBMIT save the current ‘.
Chapter 13: ESS for SAS 73 open an interactive PROC INSIGHT session on the SAS dataset near point C-F10 C-F10 toggle-listing toggle ESS[SAS] for ‘.lst’ files; useful for toggling read-only SUBMIT, PROGRAM, LOG and OUTPUT need no further explanation since they mimic the SAS Display Manager commands and related function key definitions. However, six other keys have been provided for convenience and are described below.
Chapter 13: ESS for SAS 74 (setq ess-sas-graph-view-suffix-regexp (concat "[.]\\([eE]?[pP][sS]\\|" "[pP][dD][fF]\\|[gG][iI][fF]\\|[jJ][pP][eE]?[gG]\\|" "[tT][iI][fF][fF]?\\)")) ;; default (setq ess-sas-graph-view-viewer-default "kodakimg") ;; Windows default (setq ess-sas-graph-view-viewer-default "sdtimage") ;; Solaris default (setq ess-sas-graph-view-viewer-alist ’(("[eE]?[pP][sS]" . "gv") ("[pP][dD][fF]" .
Chapter 13: ESS for SAS 75 M-x SAS Four buffers will appear on screen: Buffer ‘foo.sas’ ‘*SAS:1*’ ‘*SAS:1.log*’ ‘*SAS:1.lst*’ Mode ESS[SAS] iESS[SAS:1] Shell ESStr [] Shell ESSlst [] Description your source file iESS communication buffer SAS log information SAS listing information If you would prefer each of the four buffers to appear in its own individual frame, you can arrange for that. Place the cursor in the buffer displaying ‘foo.sas’. Enter the sequence C-c C-w.
Chapter 13: ESS for SAS 76 find / -name sas -print Now place a soft link to the real sas executable in your ~/bin directory, with for example cd ~/bin ln -s /usr/local/sas9/sas sas Check your PATH environment variable to confirm that ~/bin appears before the directory in which the sas shell script appears. 13.8 ESS[SAS]–Graphics Output from a SAS/GRAPH PROC can be displayed in a SAS/GRAPH window for SAS batch on Windows or for both SAS batch and interactive with XWindows on UNIX.
Chapter 14: ESS for BUGS 77 14 ESS for BUGS ESS[BUGS] was originally designed for use with BUGS software. Later, it evolved to support JAGS as a dialect of the BUGS language via ESS[JAGS], however, ESS[JAGS] is documented in the section Help for JAGS. ESS[BUGS] provides 5 features. First, BUGS syntax is de- scribed to allow for proper fontification of statements, distributions, functions, commands and comments in BUGS model files, command files and log files.
Chapter 15: ESS for JAGS 78 15 ESS for JAGS ESS[BUGS] was originally designed for use with BUGS software. Later, it evolved to support JAGS as a dialect of the BUGS language via ESS[JAGS]. Since BUGS and JAGS are quite similar, ESS[BUGS] and ESS[JAGS] are necessarily similar. ESS[JAGS] provides 4 features. First, JAGS syntax is described to allow for proper fontification of statements, distributions, functions, commands and comments in JAGS model files, command files and log files.
Chapter 15: ESS for JAGS 79 C-c C-c, a command file is created if one does not already exist. When you are finished editing your command file, pressing C-c C-c again will submit your command file as a batch job. The ess-jags-command variable allows you to specify a different JAGS program to use to run your model; defaults to “jags”. 15.3 ESS[JAGS]–Log files The ‘.jog’ extension is used for JAGS log files. You may find F2 useful to refresh the ‘.jog’ if the batch process over-writes or appends it.
Chapter 16: Bugs and Bug Reporting, Mailing Lists 80 16 Bugs and Bug Reporting, Mailing Lists 16.1 Bugs • Commands like ess-display-help-on-object and list completion cannot be used while the user is entering a multi-line command. The only real fix in this situation is to use another ESS process. • The ess-eval- commands can leave point in the ESS process buffer in the wrong place when point is at the same position as the last process output.
Chapter 16: Bugs and Bug Reporting, Mailing Lists • • • • • 81 helping users of ESS to get along with it. discussing aspects of using ESS on Emacs and XEmacs. suggestions for improvements. announcements of new releases of ESS. posting small patches to ESS. 16.4 Help with emacs Emacs is a complex editor with many abilities that we do not have space to describe here. If you have problems with other features of emacs (e.g.
Appendix A: Customizing ESS 82 Appendix A Customizing ESS ESS can be easily customized to your taste simply by including the appropriate lines in your ‘.emacs’ file. There are numerous variables which affect the behavior of ESS in certain situations which can be modified to your liking. Keybindings may be set or changed to your preferences, and for per-buffer customizations hooks are also available. Most of these variables can be viewed and set using the Custom facility within Emacs.
Indices 83 Indices Key index , , . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 { { . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 } } . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 C C-c C-c C-c C-c C-c C-c C-c C-c C-c C-c C-c C-c C-C C-c C-C C-c C-C C-C C-c C-c C-c C-c C-c C-c C-c C-c C-c C-C C-c C-c .. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Indices comint-bol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . comint-copy-old-input . . . . . . . . . . . . . . . . . . . . . . . comint-dynamic-complete . . . . . . . . . . . . . . . . . . . . . comint-forward-matching-input . . . . . . . . . . . . . . comint-history-isearch-backward-regexp . . . comint-interrupt-subjob . . . . . . . . . . . . . . . . . . . . . comint-kill-input. . . . . . . . . . . . . . . . . . . . . . . . . . . . comint-kill-output . . . . . . . . . . . . .
Indices 85 O Q objects() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 q() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 S P printer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 S.............................................. search() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31, source(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Indices completion on file names . . . . . . . . . . . . . . . . . . . . . . . completion on lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . completion, when prompted for object names . . creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . credits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 46 46 37 37 16 82 K D data frames . . . . . . . . . . . .
Indices 87 S S+elsewhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . search list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31, sending input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . starting directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . starting ESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STERM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
