~ubuntu-branches/ubuntu/natty/ess/natty

%% $Id: ESS_intro.tex,v 1.2 1999/11/16 20:58:36 ess Exp $
%%
%% $Log: ESS_intro.tex,v $
%% Revision 1.2  1999/11/16 20:58:36  ess
%% Martin suggested a small fix.
%%
%% Revision 1.1  1999/11/16 20:54:33  ess
%% Another bit of documentation
%%
%% Revision 1.11  1998/10/12 21:09:20  rossini
%% added andy's notes.
%%
%% Revision 1.10  1998/10/12 15:53:25  rossini
%% emacs clarification made (thanks Martin!).
%%
%% Revision 1.9  1998/10/12 15:48:16  rossini
%% Released in semi-final form.
%%
%%

\documentclass{article}

\addtolength{\textheight}{2in}
\addtolength{\textwidth}{1in}
\addtolength{\topmargin}{-1in}
\addtolength{\oddsidemargin}{-1.0in}

\usepackage{palatino}
\usepackage{html}

\title{A Quick Introduction to ESS}
\author{A.J. Rossini}

\begin{document}

\maketitle

This document can be found at
\begin{center}
  \htmladdnormallink
  {http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/}
  {http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/}
\end{center}
The example file for this session is
\htmladdnormallink{rossini.example.R}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/rossini.example.R},
which can be retrieved (from the Biostat machines) by 
\begin{verbatim}
        cp ~rossini/public_html/talk/ESS_intro/rossini.example.R .
\end{verbatim}
to your current working directory.  (note that the final ``.'' is very
important!).

For convenience, the \htmladdnormallink{latex}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/ESS\_intro.tex}
and \htmladdnormallink{postscript}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/ESS\_intro.ps}
versions are also available.

\section{Common Emacs Information}
\label{sec:emacs}

This is not a tutorial for Emacs.  That is a subject for another session.

Basic notation for key sequences:
\begin{itemize}
\item \verb+[tab]+ is the TAB (indent) key.
\item \verb+C-k+ refers to holding down the control (ctrl) key \textbf{WHILE}
  pressing ``k''.
\item \verb+M-k+ refers to pressing the Escape key (ESC),
  \textbf{THEN} pressing ``k''.
\end{itemize}
\textbf{Only run one Emacs session}.  This is a cardinal rule, that
you should try not to violate.  To load in (visit) new files, do:
\begin{itemize}
\item \verb+C-x C-f+    (replaces current file in window with new)
\item \verb+C-x 4 C-f+  (load new file in different window)
\item \verb+C-x 5 C-f+  (load new file in different frame)
\end{itemize}
and to switch to another file, do
\begin{itemize}
\item \verb+C-x b+    (switch to new buffer in window)
\item \verb+C-x 4 b+  (replaces current file in different window)
\item \verb+C-x 5 b+  (replaces current file in different frame)
\end{itemize}

Buffers are the representations of the files you are editing.  You can
treat them as the files themselves.


\subsection{Useful (X)Emacs Commands for UW Biostat}
\label{sec:emacs:uwbiostat}

In the following, \emph{``Emacs''} can be used instead of
\emph{``XEmacs''}.

This section is thanks to \htmladdnormallink{Andy
  Dunning}{mailto:adunning@biostat.washington.edu} and
\htmladdnormallink{Greg Warnes}{mailto:warnes@biostat.washington.edu}.

It's also available as a \htmladdnormallink{crib sheet text document}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/emacs.txt}.

\begin{verbatim}
                        USEFUL XEMACS COMMANDS
                        ======================

STARTING XEMACS  (Currently on GIBSON, GORN, SOL, ATLAS, ABACUS)
---------------
        rsh <machine>           login to machine <machine>

        xemacs <filename>       start xemacs, edit <filename>
        xemacs -f S             start xemacs, run S-plus
        xemacs -nw              start xemacs in _text_ mode (nw="No Window")
                                (useful over telnet session from home)

ANY EMACS BUFFER
----------------

        MOVING AROUND
        -------------
        C-v             Move forward one screenful
        M-v             Move backward one screenful
        C-l             Clear screen and redisplay everything
        M- ->           Meta-<right> - moves forward a word 
        M- <-           Meta-<left> - moves back a word
        M- |^           Meta-<up> - move up a paragraph
        M- V            Meta-<down> - move down a paragraph
        M- <            Meta-<less than> - move to end of file
        
        CUT AND PASTE
        -------------
        C-d             _D_elete
        C-k             _K_ill from the cursor position to end of line
        C-y             Recover/Paste (_Y_ank) killed text (repeat to copy) 
        M-y             recover former killed text (after C-y.  Repeat to go 
                        back through stack).
        C-x u           _U_ndo

        LOADING/SAVING FILES
        --------------------
        C-x C-f         _F_ind a file
        C-x C-s         _S_ave the file

        If you find a second file with C-x C-f, the first file remains
        inside Emacs.  You can switch back to it by finding it again with
        C-x C-b.  This way you can get quite a number of files inside Emacs.

        MANAGING BUFFERS / WINDOWS
        --------------------------
        C-x 0           Move between windows 
        C-x 1           One window (i.e., kill all other windows).

        C-x b           Switch to new _b_uffer
        C-x C-b         List _b_uffers

        SEARCH and REPLACE
        ------------------
        M-x (then) replace-string
                        Replace string
        C-s             _S_earch forward - repeat to move to next occurence
        C-r             Search _r_everse - repeat to move to previous occurence
                        
        MISC
        ----
        C-h or C-h ?    _H_elp
        C-h c (command) _H_elp on this _c_ommand

        C-u 8 (character or command)   
                        Repeat character or command 8 times

        C-g             Stop, undo, unhang.
        C-x C-c         stop editing and exit (_c_lose) Emacs  

        STARTING SPLUS / ESS
        --------------------
        M-x S           Start _S_-plus process buffer
        M-x S-mode      Change mode of current buffer to S-plus code editing

S EXECUTION BUFFER (Usually named "*S*" or similar, mode line says "iESS")
------------------

        C-c C-d         _D_ump S-plus object or function into new editing 
                           buffer.

        C-c C-v xxx     get S-plus help on "xxx"


S CODE EDITING BUFFER (Usually named for the file being edited, mode line 
---------------------           says "ESS[S]")

        C-c C-j         Send line to S
        C-c C-n         Send line to S and move down to _n_ext line
        C-c C-r         Send highlighted _r_egion to S
        C-c C-b         Send whole _b_uffer to S
        C-c C-f         Send _f_unction where cursor is to S

        C-c C-v xxx     get S-plus help on "xxx"
\end{verbatim}

\section{Replacing Command-line Usage}
\label{sec:commandline}

\subsection{Start-up}
\label{sec:commandline:startup}

\begin{enumerate}
\item To run from the command-line in a non-windowing environment:
\begin{verbatim}
  xemacs -f S
\end{verbatim}
\item To run from the command-line in a windowing environment:
\begin{verbatim}
  xemacs -f S &
\end{verbatim}
\end{enumerate}
(note that depending on the system, you might be using \verb+emacs+,
not \verb+xemacs+).

\textbf{Optional: } The first time that one runs this, you should
construct the object list.  This is done by:
\begin{verbatim}
      M-x ess-create-object-name-db
\end{verbatim}
or
\begin{verbatim}
      M-x ess-create-obj[tab]
\end{verbatim}
where \verb+[tab]+ is the TAB key.

One can replace \verb+S+ with \verb+R+ or \verb+XLS+, to run a
different version.  The object database feature currently only works
with Splus and R.

\subsection{Replacing Command-line Usage}
\label{sec:commandline:usage}

To enter commands, you generally need to be at a command prompt (i.e.
``\verb+> +'').  But there are some nice exceptions.

The follow applies primarily to \verb+Splus+ and \verb+R+.

\begin{enumerate}
\item To get help on a function (help(``lm'')) without spoiling your
  input line: \verb+C-c C-v+
\item Completion of objects (functions and data): 
  \begin{enumerate}
  \item \verb+C-c [tab]+ 
  \item \verb+[tab]+ (sometimes).
\end{enumerate}
\item Search command-line history ``manually'', matching on current input
  \begin{enumerate}
  \item backwards: \verb+M-p+
  \item forwards:  \verb+M-n+
  \end{enumerate}
\item Complete current line based on command-line history:
  \begin{enumerate}
  \item backwards: \verb+\C-[uparrow]-p+
  \item forwards:  \verb+M-n+
  \end{enumerate}
\item If you are reviewing old commands, to re-enter it one (with the
  cursor on the line): \verb+[return]+.  
\end{enumerate}

Many other commands, as well...

\section{Replacing Cut-and-Paste}
\label{sec:cutpaste}

The next stage of statistics package usage is usually to cut-and-paste
from an editor.  Since we are within an editor, this is moot.

\textbf{Use the following suffices for your files:}
\begin{itemize}
\item \verb+.S+, such as \verb+critical_simulation.S+
\item \verb+.R+, such as \verb+speedy_simulation.R+
\end{itemize}

\subsection{Cut and Paste}
\label{sec:cutpaste:usual}

You \textbf{can} cut and paste.  It's pretty identical, and a bit ugly.

\subsection{Efficient Methods 1}
\label{sec:cutpaste:eff1}

\textbf{This works from the process (inferior ESS, or iESS) buffer}

One improvement is to use a \verb+source()+-like facility.

\begin{enumerate}
\item To source a file into Splus (within ESS): \verb+C-c C-l+  (load file)
\item To find what the errors are (if any): \verb+C-c `+ (backquote).
\end{enumerate}

The latter will tell you what the error is.  You'll have to go back to
the file and edit it.

\subsection{Efficient Methods 2}
\label{sec:cutpaste:eff2}

\textbf{This works from the editing (ESS) buffer}

Better yet, use a file, and send material from the file straight to
the process.  This works if the file ends in the proper suffix (and
hence, the mode at the bottom should say ``ESS'').

The following is possible:
\begin{itemize}
\item Send current line to S: \verb+C-c C-j+
\item Send current function to S (assumes the cursor is in the
  function body): \verb+C-c C-f+.
\item Send current region (highlighted) to S  \verb+C-c C-r+
\item Send whole buffer/file to S  \verb+C-c C-b+
\end{itemize}


\section{Editing}
\label{sec:edit}

\textbf{This works from the editing (ESS) buffer}

See Section~\ref{sec:cutpaste:eff2} for communication between the code
buffer and the process buffer.

The help commands and object completion commands (only \verb+C-c [TAB]+
version) work.

Syntax-highlighting and formatting are present.  For comment indentation:
\begin{enumerate}
\item \verb+#+ gets moved to the right-side of the line
\item \verb+##+ is placed at the current indentation level
\item \verb+###+ is placed flush-left.
\end{enumerate}

To dump an object into a buffer (for editing, saving, possible reloading):
\begin{enumerate}
\item \verb+C-c C-d+ dumps the named object into an editing buffer (in
  ESS mode).
\end{enumerate}


\section{Advanced Usage}
\label{sec:advanced}

\begin{itemize}
\item preliminary integration with noweb, for literate programming and
  data analysis (another talk)
\item Has a transcript mode for recreating work and providing
  demonstrations.
\item Except for object-completion, everything mentioned here works
  \textbf{identically} for Stata, XLispStat, and SAS.
\item Makes versioning (version control, document revision history)
  simple.
\end{itemize}
\end{document}