~ubuntu-branches/ubuntu/oneiric/ess/oneiric

\input texinfo   @c -*-texinfo-*-

@comment %**start of header

@setfilename ess.info

@settitle ESS --- Emacs Speaks Statistics

@comment %**end of header

@synindex pg vr

@include ess-defs.texi

@titlepage

@title ESS --- Emacs Speaks Statistics

ESS @w{version @ESSVER}

@author The ESS Developers (A.J. Rossini, R.M. Heiberger, K. Hornik,

@author M. Maechler, R.A. Sparapani, S.J. Eglen,

@author S.P. Luque and H. Redestig)

@c @author (Formerly by: Doug Bates, Ed Kademan, Frank Ritter

@c @author                and David Smith)

@c @ifhtml

@c <P><HR></P>

@c @end ifhtml

@c

@author Current Documentation by The ESS Developers

@author Copyright @copyright{} 2002--2010 The ESS Developers

@author Copyright @copyright{} 1996--2001 A.J. Rossini

@c (@email{rossini@@biostat.washington.edu})

@c @author Department of Biostatistics

@c @author University of Washington, USA.

@author Original Documentation by David M. Smith

@author Copyright @copyright{} 1992--1995 David M. Smith

@c (@email{D.M.Smith@@lancaster.ac.uk})

@c @author Department of Mathematics and Statistics

@c @author Lancaster University, UK

@c @page

@c @vskip 0pt plus 1filll

@c @sp 2

@author Permission is granted to make and distribute verbatim copies of this

@author manual provided the copyright notice and this permission notice are

@author preserved on all copies.

@author Permission is granted to copy and distribute modified versions of this

@author manual under the conditions for verbatim copying, provided that the

@author entire resulting derived work is distributed under the terms of a

@author permission notice identical to this one.

@end titlepage

@ifnottex

@majorheading ESS --- Emacs Speaks Statistics

@dircategory Emacs

@direntry

* ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS/JAGS, Stata, XLisp-Stat).

@end direntry

@c node-name,  next,  previous,  up

@node Top, Introduction, (dir), (dir)

@top ESS: Emacs Speaks Statistics

ESS version

@include ../VERSION

@display

by  A.J. Rossini,

    R.M. Heiberger,

    K. Hornik,

    M. Maechler,

    R.A. Sparapani,

    S.J. Eglen,

    S.P. Luque

and H. Redestig.

@end display

@c (Formerly: Doug

@c Bates, Ed Kademan, Frank Ritter and David Smith).

@quotation

Emacs Speaks Statistics (ESS) provides an intelligent, consistent

interface between the user and the software.  ESS interfaces with SAS,

S-PLUS, R, BUGS/JAGS and other statistical analysis packages on Unix,

Linux and Microsoft Windows.  ESS is itself a package within the emacs

text editor and uses emacs features to streamline the creation and use

of statistical software.  ESS knows the syntax and grammar of

statistical analysis packages and provides consistent display and

editing features based on that knowledge.  ESS assists in interactive

and batch execution of statements written in these statistical

analysis languages.

@end quotation

@end ifnottex

@menu

* Introduction::                Overview of features provided by this package

* Installation::                Installing ESS on your system

* Interactive ESS::             Interacting with statistical programs

* Entering commands::           Interacting with the ESS process

* Transcript Mode::             Manipulating saved transcript files

* ESS for the S family::

* Editing::                     How to create/edit objects and functions

* Editing R documentation::

* Help::                        Reading help files

* ESS for SAS::

* ESS for BUGS::

* ESS for JAGS::

* Miscellaneous::               Other features of ESS

* Mailing lists/bug reports::   How to get assistance with ESS

* Customization::               Customizing ESS

* Key Index::

* Concept Index::

* Variable and command index::

@c

@c @detailmenu

@c  --- The Detailed Node Listing ---

@c

@c Introduction to ESS

@c

@c * Features::                    Why should I use ESS?

@c * New features::

@c * Credits::                     Authors of and contributors to ESS

@c * Latest version::              Getting the latest version of ESS

@c * Manual::                      How to read this manual

@c

@c Installing ESS on your system

@c * Unix installation::              Installing ESS on your Unix system

@c * Microsoft Windows installation:: Installing ESS on your MS Windows system

@c * Requirements::         emacs, Operating Systems and Statistical Packages

@c * System dependent::               Other variables you may need to change

@c

@c Starting the ESS process

@c

@c * Multiple ESS processes::

@c * ESS processes on Remote Computers::

@c * Customizing startup::         Changing the startup actions

@c

@c Help for the S family

@c

@c * ESS(S)--Editing files::

@c * iESS(S)--Inferior ESS processes::

@c * Handling and Reusing Transcripts::

@c * ESS-help--assistance with viewing help::

@c * Philosophies for using ESS(S)::

@c * Scenarios for use (possibilities--based on actual usage)::

@c * Customization Examples and Solutions to Problems::

@c

@c Help for SAS

@c

@c * ESS(SAS)--Design philosophy::

@c * ESS(SAS)--Editing files::

@c * iESS(SAS)--Interactive SAS processes::

@c * ESS(SAS)--Batch SAS processes::

@c * ESS(SAS)--Function keys for batch processing::

@c * ESS(SAS)--TAB key::

@c * ESS(SAS)--Usage scenarios::

@c * iESS(SAS)--Common problems::

@c * ESS(SAS)--MS Windows::

@c

@c Interacting with the ESS process

@c

@c * Command-line editing::        Entering commands and fixing mistakes

@c * Completion::                  Completion of object names

@c * Completion details::          Advanced completion concepts

@c * Transcript::                  Manipulating the transcript

@c * Command History::             Command History

@c * History expansion::           References to historical commands

@c * Hot keys::                    Hot keys for common commands

@c * Statistical Process running in ESS?::

@c * Other::                       Other commands provided by inferior-ESS

@c

@c Manipulating the transcript

@c

@c * Last command::                Manipulating the output from the last command

@c * Process buffer motion::       Viewing older commands

@c * Transcript resubmit::         Re-submitting commands from the transcript

@c * Saving transcripts::          Keeping a record of your S session

@c

@c Editing S functions

@c

@c * Edit buffer::                 Edit objects in a specialized buffer

@c * Loading::                     Loading source files into the ESS process

@c * Error Checking::              Detecting errors in source files

@c * Evaluating code::             Sending code to the ESS process

@c * Indenting::                   Indenting and formatting @Sl{} code

@c * Other edit buffer commands::  Commands for motion, completion and more

@c * Source Files::                Maintaining @Sl{} source files

@c * Source Directories::          Names and locations of dump files

@c

@c Manipulating saved transcript files

@c

@c * Resubmit::                    Resubmitting commands from the transcript file

@c * Clean::                       Cleaning transcript files

@c

@c Other features of ESS

@c

@c * Highlighting::                Syntactic highlighting of buffers

@c * Graphics::                    Using graphics with ESS

@c * Object Completion::

@c

@c Using graphics with ESS

@c

@c * printer::                     The printer() graphics driver

@c * X11::                         The X11() (and other X-windows based) driver

@c

@c Bugs and Bug Reporting, Mailing Lists

@c

@c * Bugs::

@c * Reporting Bugs::

@c * Mailing Lists::

@c

@c Customizing ESS

@c

@c * Variables::                   Variables for customization

@c * Hooks::                       Customizing ESS with hooks

@c * Keybindings::                 Changing the default ESS keybindings

@c

@c Variables for customization

@c

@c * Variables for starting ESS::  Variables for starting ESS

@c * Dump file variables::         Variables for dump files

@c * Indentation variables::       Variables controlling indentation

@c * Variables controlling interaction::  Variables controlling interaction

@c 					with the ESS process

@c @end detailmenu

@end menu

@comment node-name,  next,  previous,  up

@node Introduction, Installation, Top, Top

@chapter Introduction to ESS

@cindex introduction

The S family (@Sl{}, Splus and R) and SAS statistical analysis packages

provide sophisticated statistical and graphical routines for manipulating

data.   @b{E}macs @b{S}peaks @b{S}tatistics (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.  It currently supports the S family, SAS, BUGS/JAGS,

Stata and XLisp-Stat with the level of support roughly in that order.

A bit of notation before we begin.  @emph{emacs} refers to both

@emph{GNU Emacs} by the Free Software Foundation, as well as

@emph{XEmacs} by the XEmacs Project.  The emacs major

mode @code{ESS[language]}, where @code{language} can take values such as

@code{S}, @code{SAS}, or @code{XLS}.  The inferior process interface

(the connection between emacs and the running process) referred to as inferior ESS

(@code{iESS}), is denoted in the modeline by @code{ESS[dialect]}, where

@code{dialect} can take values such as @code{S3}, @code{S4}, @code{S+3},

@code{S+4}, @code{S+5}, @code{S+6}, @code{S+7}, @code{R}, @code{XLS}, @code{VST}, @code{SAS}.

Currently, the documentation contains many references to @cite{`S'}

where actually any supported (statistics) language is meant, i.e., `S'

could also mean `XLisp-Stat' or `SAS'.

@cindex interactive use of S

@cindex using S interactively

For exclusively interactive users of S, ESS provides a number of

features to make life easier.  There is an easy to use command history

mechanism, including a quick prefix-search history.  To reduce typing,

command-line completion is provided for all @Sl{} objects and ``hot

keys'' are provided for common @Sl{} function calls.  Help files are

easily accessible, and a paging mechanism is provided to view them.

Finally, an incidental (but very useful) side-effect of ESS is that a

transcript of your session is kept for later saving or editing.

@cindex transcripts of S sessions

No special knowledge of Emacs is necessary when using @Sl{}

interactively under ESS.

@cindex programming in S

For those that use @Sl{} in the typical edit--test--revise cycle when

programming @Sl{} functions, ESS provides for editing of @Sl{} functions

in Emacs edit buffers.  Unlike the typical use of @Sl{} where the editor

is restarted every time an object is edited, ESS uses the current Emacs

session for editing.  In practical terms, this means that you can edit

more than one function at once, and that the ESS process is still

available for use while editing.  Error checking is performed on

functions loaded back into S, and a mechanism to jump directly to the

error is provided.  ESS also provides for maintaining text versions of

your @Sl{} functions in specified source directories.

@menu

* Features::                    Why should I use ESS?

* New features::

* Credits::                     Authors of and contributors to ESS

* Latest version::              Getting the latest version of ESS

* Manual::                      How to read this manual

@end menu

@comment  node-name,  next,  previous,  up

@node Features, New features, Introduction, Introduction

@section Why should I use ESS?

Statistical packages are powerful software systems for manipulating and

analyzing data, but their user interfaces often leave something something

to be desired:  they offer weak editor functionality and they differ

among themselves so markedly that you have to re-learn how to do those

things for each package.  ESS is a package which is designed to make

editing and interacting with statistical packages more uniform,

user-friendly and give you the power of emacs as well.

ESS provides several features which make it easier to interact with the

ESS process (a connection between your buffer and the statistical

package which is waiting for you to input commands).  These include:

@itemize @bullet

@item

@b{Command-line editing} for fixing mistakes in commands before they are

entered.  The @samp{-e} flag for S-plus provides something similar to

this, but here you have the full range of Emacs commands rather than a

limited subset.  However, other packages such as XLisp-Stat and S3 do not

necessarily have features like this built-in.

@xref{Command-line editing}.

@item

@b{Searchable command history} for recalling previously-submitted

commands.  This provides all the features of the @samp{Splus -e} history

mechanism, plus added features such as history searching.

@xref{Command History}.

@item

@b{Command-line completion} of both object and file names for quick

entry.  This is similar to @code{tcsh}'s facility for filenames; here it

also applies to object names and list components.

@xref{Completion}.

@item

@b{Hot-keys} for quick entry of commonly-used commands in `S' such as

@code{objects()} and @code{search()}.

@xref{Hot keys}.

@item

@b{Transcript recording} for a complete record of all the actions in an

S session.

@xref{Transcript}.

@item

@b{Interface to the help system}, with a specialized mode for viewing S

help files.

@xref{Help}.

@end itemize

If you commonly create or modify @Sl{} functions, you will have found

the standard facilities for this (the @samp{fix()} function, for

example) severely limiting.  Using S's standard features, one can only

edit one function at a time, and you can't continue to use @Sl{} while

editing.  ESS corrects these problems by introducing the following

features:

@itemize @bullet

@item

@b{Object editing}.  ESS allows you to edit more than one function

simultaneously in dedicated Emacs buffers.  The ESS process may

continue to be used while functions are being edited.

@xref{Edit buffer}.

@item

@b{A specialized editing mode} for @Sl{} code, which provides syntactic

indentation and highlighting.

@xref{Indenting}.

@item

@b{Facilities for loading and error-checking source files}, including a

keystroke to jump straight to the position of an error in a source file.

@xref{Error Checking}.

@item

@b{Source code revision maintenance}, which allows you to keep historic

versions of @Sl{} source files.

@xref{Source Files}.

@item

@b{Facilities for evaluating @Sl{} code} such as portions of source

files, or line-by-line evaluation of files (useful for debugging).

@xref{Evaluating code}.

@end itemize

Finally, ESS provides features for re-submitting commands from saved

transcript files, including:

@itemize @bullet

@item

@b{Evaluation of previously entered commands}, stripping away

unnecessary prompts.

@xref{Transcript resubmit}.

@end itemize

@comment  node-name,  next,  previous,  up

@node New features, Credits, Features, Introduction

@section New features in ESS

@include newfeat.texi

@include onewfeat.texi

@comment  node-name,  next,  previous,  up

@node Credits, Latest version, New features, Introduction

@section Authors of and contributors to ESS

@include credits.texi

@comment  node-name,  next,  previous,  up

@node Latest version, Manual, Credits, Introduction

@section Getting the latest version of ESS

@include getting.texi

@comment  node-name,  next,  previous,  up

@node Manual,  , Latest version, Introduction

@section How to read this manual

If you need to install ESS, read @ref{Installation} for details on what

needs to be done before proceeding to the next chapter.

In this manual we use the standard notation for describing the

keystrokes used to invoke certain commands.  @kbd{C-<chr>} means hold

the CONTROL key while typing the character <chr>. @kbd{M-<chr>} means

hold the META or EDIT or ALT key down while typing <chr>. If there is no

META, EDIT or ALT key, instead press and release the ESC key and then

type <chr>.

All ESS commands can be invoked by typing @kbd{M-x command}.  Most of

the useful commands are bound to keystrokes for ease of use.  Also, the

most popular commands are also available through the emacs menubar, and

finally, if available, a small subset are provided on the toolbar.

Where possible, keybindings are similar to other modes in emacs to

strive for 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 @kbd{M-x R} can accept an optional `prefix'

argument.  To specify the prefix argument, you would type @kbd{C-u}

before giving the command.  e.g. If you type @kbd{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.  This

applies to ESS in two ways.  First, limited documentation about each ESS

command can be obtained by typing @kbd{C-h f}.  For example, if you type

@kbd{C-h f ess-eval-region}, documentation for that command will appear

in a separate *Help* buffer.  Second, a complete list of keybindings

that are available in each ESS mode and brief description of that mode

is available by typing @kbd{C-h m} within an ESS buffer.

Emacs is a versatile editor written in both C and lisp; ESS is written

in the Emacs lisp dialect (termed `elisp') and thus benefits from the

flexible nature of lisp.  In particular, many aspects of ESS behaviour

can be changed by suitable customization of lisp variables.  This manual

mentions some of the most frequent variables.  A full list of them

however is available by using the Custom facility within emacs.  (Type

@kbd{M-x customize-group RET ess RET} to get started.)

@ref{Customization} provides details of common user variables you can

change to customize ESS to your taste, but it is recommended that you

defer this section until you are more familiar with ESS.

@comment  node-name,  next,  previous,  up

@node Installation, Interactive ESS, Introduction, Top

@chapter Installing ESS on your system

@cindex installation

The following section details those steps necessary to get ESS running

on your system.

@menu

* Unix installation::              Installing ESS on your Unix system

* Microsoft Windows installation:: Installing ESS on your MS Windows system

* Requirements::         emacs, Operating Systems and Statistical Packages

@end menu

@c FIXME: the following contains @node s  *and* is also included by readme.texi

@c -----  which does *not* include 'requires.texi'

@c         ==> *must* give node pointer problems!

@c @include inst_tar.texi

@include unixlike.texi

@include windows.texi

@node Requirements, , Microsoft Windows installation, Installation

@comment node-name,  next,  previous,  up

@section Requirements

@include requires.texi

@comment  node-name,  next,  previous,  up

@node Interactive ESS, Entering commands, Installation, Top

@chapter 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'.  Either

way, we use the term `iESS' to refer to the Emacs mode used to interact

with statistical programs.