TutorialESS < Main < Vanderbilt Biostatistics Wiki

You are here: Vanderbilt Biostatistics Wiki>Main Web>StatComp>UseR-2012>TutorialESS (14 Jun 2012, RichHeiberger) (raw view)EditAttach
---+ ESS tutorial -- _UseR!_ 2012
---++ Richard M Heiberger
---++ Martin Mächler
---++ June 12, 2012
---+++ *List of useful Web resources ("Links")*
   * [[http://emacswiki.org/][Emacs Wiki]]
   * [[http://ess.r-project.org/][ESS Homepage]] ([[http://ess.r-project.org/][the ESS manual there]])
   * [[http://emacswiki.org/emacs/EmacsSpeaksStatistics][ESS section in Emacs Wiki]]
   * [[ftp://stat.ethz.ch/U/maechler/ESS/][Martin Maechler's 2012 Resources, notably a *zip* file with all slide material]]
   * [[http://www.damtp.cam.ac.uk/user/sje30/ess11][Stephen Eglen's 2011 Resources]]
   * [[http://code.google.com/p/ess-tracebug/][Vitalie's ess-tracebug]] (part of ESS, since 12.03)
   * [[https://www.ohloh.net/p/10818?p=ESS][Ohloh's Software metrics about ESS]] ("automated software analysis")

---+++ *Files, R scripts, etc - directly for the tutorial (partly uploaded "real time")*

<div style="position: absolute; left: -10000px; top: 0px; width: 1px; height: 1px; overflow: hidden;" id="_mcePaste">% Created 2012-06-09 Sat 18:22<br />\documentclass{beamer}<br />\usepackage[utf8]{inputenc}<br />\usepackage[T1]{fontenc}<br />\usepackage{fixltx2e}<br />\usepackage{graphicx}<br />\usepackage{longtable}<br />\usepackage{float}<br />\usepackage{wrapfig}<br />\usepackage{soul}<br />\usepackage{textcomp}<br />\usepackage{marvosym}<br />\usepackage{wasysym}<br />\usepackage{latexsym}<br />\usepackage{amssymb}<br />\usepackage{hyperref}<br />\tolerance=1000<br />\AtBeginSection{\begin{frame} \frametitle{Outline} \tableofcontents[currentsection] \end{frame}}<br />\setbeamersize{text margin left=0.25cm}<br />\setbeamersize{text margin right=0.25cm}<br />\setbeamertemplate{navigation symbols}{}<br />\providecommand{\alert}[1]{\textbf{#1}}<br /><br />\title{ESS tutorial, UseR! 2012 meeting}<br />\author{Stephen Eglen (UseR! 2011) -- \emph{small changes by Martin Mächler}}<br />\date{June 12, 2012 --- Handouts: 2012-06-09}<br />\hypersetup{<br /> pdfkeywords={},<br /> pdfsubject={},<br /> pdfcreator={Emacs Org-mode version 7.8.11}}<br /><br />\begin{document}<br /><br />\maketitle<br /><br />\section{Overview}<br />\label{sec-1}<br />\begin{frame}<br />\frametitle{Aims of the tutorial}<br />\label{sec-1-1}<br /><br /><br />\begin{itemize}<br />\item Introduce Emacs and ESS<br />\item Reproducible research: Sweave and Org-babel<br />\item Q \& A / Discuss future development<br />\item I'd like this to be very interactive. Feel free to ask<br /> questions/comment.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Course material}<br />\label{sec-1-2}<br /><br /><br />\begin{itemize}<br />\item All available via \href{http://www.damtp.cam.ac.uk/user/sje30/ess11}{http://www.damtp.cam.ac.uk/user/sje30/ess11}<br />\item ess11.zip has the relevant material for today.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Disclaimers}<br />\label{sec-1-3}<br /><br /><br />\begin{itemize}<br />\item Learning Emacs takes a long time.<br />\item I'm a core-developer on Emacs and ESS.<br />\item I do not speak for emacs-devel or ess-core.<br />\item ESS has several statistical interfaces; only R will be discussed today.<br />\item Emacs (not XEmacs and SXEmacs) preferred.<br />\item I have limited knowledge of Windows.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{These slides}<br />\label{sec-1-4}<br /><br /><br />\begin{itemize}<br />\item Although there are pdf slides, probably most of the time I'll be<br /> showing you emacs.<br />\item Of course, we could just view these slides in Emacs!<br /> (View \texttt{ess-slides.pdf} in Emacs\ldots{})<br />\item These slides are written in Org mode/Beamer. To compile them<br /> yourself (e.g., via \texttt{make}), you will need (e.g. in \href{file://.//~/.emacs}{file://\~/.emacs})<br />\end{itemize}<br /><br />\begin{verbatim}<br />(setq org-beamer-frame-level 2)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Acknowledgements}<br />\label{sec-1-5}<br /><br /><br />\begin{itemize}<br />\item ESS-core, in particular Tony Rossini, who gave an 2006 tutorial,<br /> from which these notes are based<br />\item ESS-help contributors<br />\item Org mode team, esp. Carsten Dominik, Eric Schulte and Dan Davison<br />\end{itemize}<br />\end{frame}<br />\section{Part I: Emacs}<br />\label{sec-2}<br />\begin{frame}<br />\frametitle{Why Emacs?}<br />\label{sec-2-1}<br /><br /><br />\begin{itemize}<br />\item Being productive with Emacs (Phil Sung).<br /> \href{http://web.psung.name/emacs/}{http://web.psung.name/emacs/}<br /><br /> \href{http://www.gnu.org/software/emacs/tour}{http://www.gnu.org/software/emacs/tour}<br />\item Explore the guided tour file:<br /> \includegraphics[width=.9\linewidth]{./resources/Emacs-guided-tour-1.pdf}<br />\item Older PDF from<br /> \href{http://commons.wikimedia.org/wiki/File:Emacs-guided-tour-1.pdf}{http://commons.wikimedia.org/wiki/File:Emacs-guided-tour-1.pdf}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{History of Emacs}<br />\label{sec-2-2}<br /><br /><br />\begin{itemize}<br />\item Key architect: Richard Stallman.<br />\item Evolution from terminal only to rich graphical interface with remote<br /> editing support.<br />\item Emacs release cycle is slow<br />\item XEmacs: 1990s gained prominence as alternative, more<br /> graphical-friendly. (Less supported by ESS)<br />\item Emacs 23 very stable.<br />\item Emacs 24 due out next year? (&lt;&lt; written in 2011)<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Keystrokes, keybindings and functions}<br />\label{sec-2-3}<br /><br /><br />\begin{itemize}<br />\item Each keystroke is bound to a lisp function, even simple characters<br /> like ``a''.<br />\item \texttt{C-h k a}<br />\item \texttt{C-h k C-a}<br />\end{itemize}<br /><br />These create new \emph{buffers} which are shown in new windows.<br /><br />\begin{itemize}<br />\item \texttt{M-x} is bound to execute-extended-command, which allows you to run a<br /> command by name (there are many commands that are not bound to<br /> keys).<br />\item Mapping between keybindings and commands is flexible; can change on<br /> fly e.g.<br />\end{itemize}<br /><br />\begin{verbatim}<br /> (global-set-key "\C-ca" 'org-agenda)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Understanding keystrokes}<br />\label{sec-2-4}<br /><br /><br />\begin{itemize}<br />\item \texttt{TAB} is the TAB (indent) key.<br />\item \texttt{RET} is the Return (carriage return, enter) key.<br />\item \texttt{C-h} means press control key AND ``h'' together<br />\item \texttt{ESC-h} means press ESC key THEN ``h''<br />\item \texttt{M-h} means press ALT or Meta key AND ``h'' together.<br />\item \texttt{M-C-h} means press Meta or Alt while pressing h and control key. OR<br /> (if no meta/alt): ESC THEN (control and h keys together).<br />\item Older keyboards (and sometimes older Macs) without ALT or Meta<br /> lead to confusion between ESC and Meta, but ideally they should<br /> be different.<br />\end{itemize}<br /><br />\begin{verbatim}<br />;; change CMD modifier to meta key (usually super).<br />(setq mac-command-modifier 'meta)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Example keybinding that makes a key `smart'}<br />\label{sec-2-5}<br /><br /><br /><br />\begin{verbatim}<br /> ;; From Peter.Weiss@Informatik.Uni-Oldenburg.DE (Peter Weiss)<br /> ;; Sun Nov 12 1995<br /> (defun match-paren (arg)<br /> "Go to the matching parenthesis if on parenthesis<br />otherwise insert %."<br /> (interactive "p")<br /> (cond ((looking-at "\\s\(")<br /> (forward-list 1) (backward-char 1))<br /> ((looking-at "\\s\)")<br /> (forward-char 1) (backward-list 1))<br /> (t<br /> (self-insert-command (or arg 1)))))<br /><br /> (global-set-key "%" 'match-paren)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Moving Around}<br />\label{sec-2-6}<br /><br /><br /><br />\begin{verbatim}<br />C-v Move forward one screenful<br />M-v Move backward one screenful<br />C-l Clear and redraw screen<br />M- -&gt; Meta-&lt;right&gt; - moves forward a word<br />M- &lt;- Meta-&lt;left&gt; - moves back a word<br />M- |^ Meta-&lt;up&gt; - move up a paragraph<br />M- V Meta-&lt;down&gt; - move down a paragraph<br />M- &lt; Meta-&lt;less than&gt; - move to file start<br />M- &gt; Meta-&lt;greater than&gt; - move to file end<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Cut and Paste}<br />\label{sec-2-7}<br /><br /><br />\begin{verbatim}<br />C-d _D_elete<br />C-k _K_ill from the cursor position to<br /> end of line<br />C-y Recover/Paste (_Y_ank) killed text<br /> (repeat to copy)<br />M-y recover former killed text (after C-y).<br /> Repeat to go back through stack).<br />C-x u _U_ndo (multiple undo/redo)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Loading / Saving Files}<br />\label{sec-2-8}<br /><br /><br />\begin{verbatim}<br />C-x C-f _F_ind a file<br />C-x C-s _S_ave the file<br /><br />If you find a second file with C-x C-f,<br />the first file remains inside Emacs.<br />You can switch back to it by finding it<br />again with C-x C-b. This way you can get<br />quite a number of files inside Emacs.<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Managing Buffers and Windows}<br />\label{sec-2-9}<br /><br /><br /><br />\begin{verbatim}<br />C-x 0 Move between windows<br /> (Oh, not Zero!)<br />C-x 1 One window<br /> (i.e., kill all other windows).<br />C-x b Switch to new _b_uffer<br />C-x C-b List _b_uffers<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Search and Replace}<br />\label{sec-2-10}<br /><br /><br />\begin{verbatim}<br />M-x (then) replace-string<br /> Replace string<br />M-x (then) query-replace-string<br /> Will ask you, for each match,<br /> if you really want to replace<br /> the old string with the new one.<br />C-s _S_earch forward (repeat to<br /> reuse past search strings)<br />C-r Search _R_everse (repeat to<br /> reuse past search strings)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Misc Emacs Actions}<br />\label{sec-2-11}<br /><br /><br />\begin{verbatim}<br />C-h or C-h ? _H_elp<br />C-h c (command) _H_elp on this _c_ommand<br /><br />C-u 8 (character or command)<br /> Repeat character/command 8 times<br /><br />C-g Stop, unhang.<br />C-x C-c Stop and exit (_c_lose) Emacs<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Evaluating lisp}<br />\label{sec-2-12}<br /><br /><br />Sometimes you will see me evaluate lisp code within emacs, rather than<br />typing a command. These are equivalent:<br /><br />\begin{verbatim}<br /> M-x next-line<br /> (next-line)<br /> above line eval'd using C-x C-e<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Repeating yourself}<br />\label{sec-2-13}<br /><br /><br /> Repeat C-n ten times:<br /><br /> C-u 10 C-n<br /><br /> C-u 70 \#<br /><br /> Can anyone guess what the following will do?<br /><br /> C-u C-n<br /><br /> C-u C-u C-n<br /><br /> Keyboard macros allow for arbritary key sequences to be repeated\ldots{}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Keyboard macros}<br />\label{sec-2-14}<br /><br /><br /> \texttt{C-x (} lots of stuff \texttt{C-x )}<br /><br /><br /> Can include counters. e.g.<br />\begin{verbatim}<br /> C-x ( TAB step C-x C-k C-i RET C-x )<br />\end{verbatim}<br /><br /> will make:<br /><br />\begin{verbatim}<br /> step 0<br /> step 1<br /> step 2<br />\end{verbatim}<br />\ldots{}<br /><br /><br /> (info ``(emacs)Keyboard Macros'')<br />\end{frame}<br />\begin{frame}<br />\frametitle{Point, mark and region}<br />\label{sec-2-15}<br /><br /><br />\begin{itemize}<br />\item \emph{point} is current location of cursor<br />\item \emph{mark} \texttt{C-SPC} to define another point<br />\item \emph{region} is text between mark and point<br />\item \texttt{C-x C-x} will swap point and mark.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Buffers}<br />\label{sec-2-16}<br /><br /><br />\begin{itemize}<br />\item Can contain:<br />\begin{enumerate}<br />\item contents of files, e.g. ess-slides.org<br />\item output from commands, e.g. \texttt{M-x man RET pwd RET}<br />\item \emph{inferior processes} e.g. \texttt{M-x shell} (these will be useful later<br /> for running R wihin Emacs.)<br />\item Any text you care for \ldots{} \texttt{M-x animate-birthday-present}<br />\end{enumerate}<br />\item Switching between buffers from \texttt{Buffers} menu or \texttt{C-x b}<br />\item Think of buffers as bits of text that can be edited/moved around.<br />\item You can easily get 100+ buffers on a good day\ldots{}!<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Windows and frames}<br />\label{sec-2-17}<br /><br /><br />\begin{itemize}<br />\item A \emph{frame} can have one or more windows.<br />\item An emacs process can create many frames (e.g. \texttt{M-x speedbar}, \texttt{C-x 5 2})<br />\item Each window has a \emph{modeline} (describe).<br />\item Each frame usually has an echo area, and a minibuffer. These<br /> normally overlap.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Major and minor modes}<br />\label{sec-2-18}<br /><br /><br /> Modes contain specialisations (commands/variables) for different<br /> languages.<br /><br />\begin{itemize}<br />\item Major modes are defined for different languages (C, latex, R,<br /> python, \ldots{}).<br />\item Consistency across modes where possible (e.g. commands for<br /> commenting, indentation). Keybindings consistent. \emph{Font lock}<br /> also consistent, e.g. comments in red.<br />\item Only one \emph{major} mode active at a time (?Sweave?)<br />\item Major mode decided typically on regexps on buffer name.<br />\end{itemize}<br /><br /> See \texttt{C-h v auto-mode-alist}<br /><br />\begin{itemize}<br />\item Can have several \emph{minor} modes, e.g. auto-fill-mode,<br /> flyspell-mode, font-lock-mode. Try \texttt{M-x tool-bar-mode}<br />\item \texttt{C-h m} describes features available in current buffer.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Completion, defaults, history}<br />\label{sec-2-19}<br /><br /><br />\begin{itemize}<br />\item TAB completion where possible, e.g \texttt{M-x describe- TAB}<br />\item sensible defaults, depending on text at point. e.g. \texttt{M-x man} with<br /> point on word \emph{perl}<br />\item context-dependent history, e.g. \texttt{M-x &lt;up&gt;} to see prev commands, or<br /> \texttt{M-x man RET &lt;up&gt;} to see previous man pages.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Getting help with Emacs}<br />\label{sec-2-20}<br /><br /><br /><br />\begin{center}<br />\begin{tabular}{ll}<br />\hline<br /> Keybinding & Function \\<br />\hline<br /> C-h m & describe mode \\<br /> C-h k & describe key \\<br /> C-h i & info \\<br /> C-h t & tutorial \\<br />\hline<br />\end{tabular}<br />\end{center}<br /><br /><br /><br /><br />Check out \href{http://emacswiki.org}{http://emacswiki.org}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Some of my favourite Emacs things}<br />\label{sec-2-21}<br /><br /><br />\begin{itemize}<br />\item (show-paren-mode)<br />\item find file at point: ffap<br />\item iswitchb / ido<br />\item VC: version control \texttt{C-x v l}<br />\item ediff, e.g. \texttt{M-x ediff-revision}<br />\item \texttt{M-x occur RET eval}<br />\item \texttt{M-x grep}, \texttt{M-x compile} work similarly.<br />\item AUCTeX + reftex<br />\item org mode<br />\item GNUS / MH-E / VM / RMAIL<br />\item ESS !!!<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Changing how emacs works}<br />\label{sec-2-22}<br /><br /><br /> ``Emacs is the extensible, customizable, self-documenting real-time<br /> display editor.'' (info ``emacs'')<br /><br />\begin{itemize}<br />\item \emph{Extensible} means that you can extend by writing elisp. Most of<br /> emacs is written in elisp, with C for core.<br />\item \emph{Customizable} means that you can change behaviour by changing<br /> values of variables.<br />\item The .emacs file<br />\item Reload by restarting emacs, \texttt{M-x eval-buffer} or \texttt{M-x eval-region}<br />\item Or, after a closing bracket, just \texttt{C-x C-e}. Try twice e.g.:<br />\begin{verbatim}<br /> (+ 5 (* 3 2) 4)<br />\end{verbatim}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{How does Emacs find its libraries?}<br />\label{sec-2-23}<br /><br /><br />\begin{itemize}<br />\item Emacs' \texttt{load-path} controls which directories are searched.<br />\end{itemize}<br /><br />\begin{verbatim}<br /> (locate-library "ess")<br /> (add-to-list 'load-path "~/langs/emacs/org-mode/lisp")<br />\end{verbatim}<br /><br /> Or to look up the definition of a function, try \texttt{M-x find-function ess-dirs}.<br />\end{frame}<br />\begin{frame}<br />\frametitle{How do you find other packages?}<br />\label{sec-2-24}<br /><br /><br />\begin{itemize}<br />\item \href{http://emacswiki.org}{http://emacswiki.org} mentions many, and has repository.<br />\item Upcoming Emacs Lisp Package Archive (ELPA).<br />\item \href{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html}{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Exercise: install Org mode 7.8.11}<br />\label{sec-2-25}<br /><br /><br />Although Emacs comes with org-mode, you probably should get a newer<br />version. 7.8.11 has been released, 2012-05-25<br /><br />Download, unpack, make and install.<br />\begin{verbatim}<br /> wget http://orgmode.org/org-7.8.11.tar.gz<br /> tar xfz org-7.8.11.tar.gz<br /> cd org-7.8.11<br /> make ## not make install<br /><br /> Add to .emacs and eval.<br />\end{verbatim}<br /><br />\begin{verbatim}<br /> (add-to-list 'load-path "~/org-7.8.11/lisp")<br /> (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))<br /> (require 'org-install)<br /><br /> C-h v org-version<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Exercise: make sure you have ESS 12.04-4 (or 12.04-2) if you can.}<br />\label{sec-2-26}<br /><br /><br /> Installing ESS is slightly simpler, especially if you want just the<br /> source.<br /><br /> Download, unpack, and then:<br />\begin{verbatim}<br /> (load "~/langs/emacs/elisp-ds/ess/lisp/ess-site")<br />\end{verbatim}<br /><br /> Aug 2011: Vincent Goulet's pre-made binaries for MAC and WIN are up<br /> to date.<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Variables}<br />\label{sec-2-27}<br /><br /><br /> Emacs variables influence the way functions behave.<br /><br /><br /><br />\begin{verbatim}<br />(setq visibile-bell t)<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item nil is FALSE, everything else, including t, is TRUE.<br />\item \texttt{M-x customize}<br />\item \texttt{M-x customize-group RET ess RET}<br />\item \texttt{M-x customize-variable RET visible-bell RET}<br />\item Finding new variables and functions: \texttt{M-x apropos RET occur RET}<br />\item Hook variables \ldots{}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Hook variables}<br />\label{sec-2-28}<br /><br /><br /><br />\begin{itemize}<br />\item Hooks are run e.g. after major-mode has been created.<br />\end{itemize}<br /><br />\begin{verbatim}<br />(add-hook 'emacs-lisp-mode-hook 'turn-on-eldoc-mode)<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Compare the following two versions:<br />\end{itemize}<br /><br />\begin{verbatim}<br />## version 1<br />(defun my-ess-hook ()<br /> "Add my keybindings to ESS mode."<br /> (local-set-key (kbd "C-j") 'ess-eval-line-and-step))<br /><br />(add-hook 'R-mode-hook 'my-ess-hook)<br /><br />## version 2<br />(add-hook 'R-mode-hook<br /> '(lambda () (local-set-key (kbd "M-RET")<br /> 'ess-R-use-this-dir)))<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Read (and edit) the source}<br />\label{sec-2-29}<br /><br /><br />\begin{itemize}<br />\item \texttt{M-x find-function RET shell RET}<br />\end{itemize}<br /><br />Emacs is extensible: write your own functions. e.g.<br /><br /><br />\begin{verbatim}<br />(defun date-stamp ()<br /> "Insert current date and time at point."<br /> (interactive)<br /> (insert (current-time-string)))<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Notes: 1. \texttt{interactive} makes it available to \texttt{M-x}. 2. Doc string<br /> accessible.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Byte compiler}<br />\label{sec-2-30}<br /><br /><br />\begin{itemize}<br />\item You will see .elc files; these are byte-compiled files.<br />\item \texttt{M-x byte-compile-file}<br />\item Should be faster than \texttt{.el} files, but can be confusing when<br /> developing code to have both .el .elc around.<br />\item Note: \texttt{M-x find-function RET shell RET} will visit the<br /> \emph{compressed} source file. Can edit .gz files as if they were<br /> uncompressed.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Philosophy}<br />\label{sec-2-31}<br /><br /><br />\begin{itemize}<br />\item Keeping files in plain text. Unicode: (view-hello-file)<br />\item Keybindings should be consistent across modes.<br />\item Keep one Emacs running (e.g. for many days).<br />\item Where to draw the line about running everything in Emacs? mail?<br /> web browsing? \texttt{M-x artist-mode}<br />\end{itemize}<br />\end{frame}<br />\section{part II: ESS}<br />\label{sec-3}<br />\begin{frame}<br />\frametitle{Why ESS?}<br />\label{sec-3-1}<br /><br /><br /> Taken from the manual \texttt{(info "(ess)Features")}<br /><br />\begin{itemize}<br />\item Command history, searchable + modifiable.<br />\item Command-line completion of both object and file names.<br />\item Hot-keys for quick entry of commonly-used commands in `S'.<br />\item Transcript recording for a complete record of session.<br />\item Interface to the help system.<br />\item Object editing.<br />\item Editing mode for code, providing syntactic indentation and highlighting.<br />\item evaluating lines/regions/chunks of R code.<br />\item loading and error-checking source files.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{History of ESS (Tony)}<br />\label{sec-3-2}<br /><br /><br />\begin{itemize}<br />\item 3 branches: S-mode, SAS-mode, Stata-mode<br />\item S-mode: 1989, 2 groups managing the project before (Bates/F<br /> Ritter/E Kademan, M Meyer, DM Smith).<br /> R added in 1995 (Rossini/Maechler)<br />\item SAS: `94, Tom Cook (`92, John Sall, SAS). Integrated `95-6, Rossini<br />\item Stata-mode: 1997, Thomas Lumley. Added 1997 (Rossini).<br />\item 1997: last major restructuring (``grand unification'')<br />\item 2004: switch leaders: Maechler takes over<br />\end{itemize}<br /><br /><br />\begin{itemize}<br />\item We are still suffering from the 1997 grand unification.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{ESS Installation}<br />\label{sec-3-3}<br /><br /><br />\begin{itemize}<br />\item \href{http://ess.r-project.org/index.php?Section=download}{http://ess.r-project.org/index.php?Section=download}<br />\item New users: grab pre-packaged bundle.<br />\item For those who prefer a mac-like app: \href{http://aquamacs.org/}{http://aquamacs.org/}<br />\item Debian package \emph{ess}<br />\item Available from Emacs Lisp Package Archive (ELPA) in near future<br />\item Line in .emacs:<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />(load "~/langs/emacs/elisp-ds/ess/lisp/ess-site")<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Editing and viewing R code}<br />\label{sec-3-4}<br /><br /><br /> Indentation should be automatic; if in doubt \texttt{M-x indent-region}<br /><br />\begin{itemize}<br />\item Imenu for browsing function definitons. (or use Speedbar)<br />\item Demo: view example code in \href{file://.files/ms_funs.R}{file:files/ms\_funs.R}<br />\item The magic underscore. like it? If not, Try M-q \_{} (this works in<br /> general, e.g. M-q TAB). Or customize:<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />(ess-toggle-underscore nil)<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item \texttt{C-c TAB} does object completion within .R buffers<br />\item Moving around your functions:<br />\end{itemize}<br /><br /><br />\begin{center}<br />\begin{tabular}{ll}<br />\hline<br /> Keybinding & Function \\<br />\hline<br /> C-M-a & ess-beginning-of-function \\<br /> C-M-e & ess-end-of-function \\<br /> C-M-h & ess-mark-function \\<br />\hline<br />\end{tabular}<br />\end{center}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Making comments}<br />\label{sec-3-5}<br /><br /><br />\begin{itemize}<br />\item ESS follows the three-level comment model of elisp:<br />\begin{enumerate}<br />\item One hash (\#) for col 32 aligned end-of-line comments.<br />\item Two hashes (\#\#) to match current indentation.<br />\item Three hashes (\#\#\#) for column 0, major comments.<br />\end{enumerate}<br />See examples in \texttt{files/ms\_funs.R}<br />\item \texttt{comment-dwim} is bound to \texttt{M-;}.<br />\item This `do what I mean' should work well for cases 1 and 2.<br />\item Or use \texttt{comment-region} (with or without prefix).<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Indenting your code.}<br />\label{sec-3-6}<br /><br /><br />\begin{itemize}<br />\item By default, ESS uses a set of variables to set spacing.<br />\item Following from \texttt{(info "(ess)Styles")}<br />\end{itemize}<br /><br />\begin{quote}<br />The combined value of nine variables that control indentation are<br />collectively termed a style. ESS provides several styles covering the<br />common styles of indentation: `DEFAULT', `OWN', `GNU', `BSD', `K\&R',<br />`C++', `RRR', `CLB'. The variable `ess-style-alist' lists the value of<br />each indentation variable per style.<br />\end{quote}<br /><br />\begin{itemize}<br />\item To reindent code: \texttt{M-x indent-region}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Viewing help files}<br />\label{sec-3-7}<br /><br /><br /> e.g. \texttt{C-c C-v RET pbinom RET} (or ?pbinorm within \verb~*R*~).<br /> Key features<br /><br />\begin{itemize}<br />\item move easily between sections (n/p)<br />\item browse help for new pages<br />\item running examples (l)<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Making help files (.Rd)}<br />\label{sec-3-8}<br /><br /><br />\begin{itemize}<br />\item Edit an exiting .Rd file: \href{file:///u/maechler/R/Meetings-Kurse-etc/2012-Nashville/ESS-tutorial/ess2012/files/sjedrp.Rd}{file:files/sjedrp.Rd}<br />\item Create a new file. \href{file://.files/empty.Rd}{file:files/empty.Rd} then \texttt{C-c C-e}<br />\item Preview your Rd files \texttt{C-c C-p}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Inferior ESS Processes (\verb~*R*~)}<br />\label{sec-3-9}<br /><br /><br />\begin{itemize}<br />\item \texttt{M-x R} will start an R process within a new buffer.<br />\item We can have multuple R processes, running either locally or remotely.<br />\item Passing command-line switches to the R session.<br />\end{itemize}<br /><br />\begin{verbatim}<br /> C-u M-x R RET --no-save RET<br />\end{verbatim}<br /><br /><br />\begin{verbatim}<br />(setq inferior-R-args "--no-save ")<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item These buffers are called \emph{inferior} as they run a process under<br /> Emacs. Our ESS manual calls them \emph{iESS} buffers.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Which version of R will it find?}<br />\label{sec-3-10}<br /><br /><br />\begin{itemize}<br />\item Should find all versions of R on your path, see the list found by<br />\begin{verbatim}<br /> M-x R- TAB<br />\end{verbatim}<br />\item If you have a version of R on your path, try putting in a symlink<br /> somewhere on your path.<br /><br />\begin{verbatim}<br /> ln -s /my/version/of/R ~/bin/R-2.15.0-special<br />\end{verbatim}<br />\item Which versions of R are found?<br />\end{itemize}<br />\begin{verbatim}<br /> ess-r-versions is a variable defined in `ess-r-d.el'.<br /> Its value is ("R-1" "R-2" "R-devel" "R-patched")<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item \texttt{M-x R-newest} will be bound to newest version of R on your<br /> system, by checking \texttt{R -{}-version} for each R binary.<br />\item (Windows might differ slightly)<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{What can I do in \texttt{*R*}?}<br />\label{sec-3-11}<br /><br /><br />\begin{itemize}<br />\item Run commands as normal.<br />\item TAB Completion of functions, objects, filenames.<br />\item At the prompt, recall history:<br />\end{itemize}<br /><br /><br />\begin{center}<br />\begin{tabular}{ll}<br />\hline<br /> keybinding & function \\<br />\hline<br /> M-p & comint-previous-input \\<br /> M-n & comint-next-input \\<br /> M-r & comint-previous-matching-input \\<br />\hline<br />\end{tabular}<br />\end{center}<br /><br /><br /><br />\begin{itemize}<br />\item Can move through \texttt{*R*} and resissue commands from previous prompts<br />\end{itemize}<br /><br /><br />\begin{center}<br />\begin{tabular}{ll}<br />\hline<br /> keybinding & function \\<br />\hline<br /> RET & inferior-ess-send-input \\<br /> C-c RET & comint-copy-old-input \\<br /> M-RET & ess-transcript-send-command-and-move \\<br />\hline<br />\end{tabular}<br />\end{center}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{What is emacsclient?}<br />\label{sec-3-12}<br /><br /><br />Why does \texttt{*R*} start with:<br /><br />\begin{verbatim}<br /> options(STERM='iESS', editor='emacsclient')<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item emacsclient allows you to work with a running emacs, rather than<br /> start a new one.<br />\end{itemize}<br /><br />\begin{verbatim}<br /> M-x server-start<br /> % emacsclient file.R<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Now in R, you can do things like<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />x &lt;- rbinom(100, 10, 0.5)<br />edit(x)<br />fix(x)<br />page(x)<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item \texttt{C-x \#} should kill any client buffer.<br />\item As an aside, \texttt{emacsclient -t} will bring up a new window.<br />\item Warning: make sure you are using the right emacsclient if you have<br /> several versions on your system.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{emacsclient / 2}<br />\label{sec-3-13}<br /><br /><br />\begin{itemize}<br />\item emacsclient allows you to run elisp<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />ess-slides.pdf: ess-slides.org<br /> emacsclient --eval "(org-to-pdf \"ess-slides.org\")"<br />\end{verbatim}<br /><br /><br />\begin{verbatim}<br />(defun org-to-pdf (org)<br /> "Convert org buffer ORG to a pdf."<br /> (interactive)<br /> (save-current-buffer<br /> (set-buffer org)<br /> (org-export-as-pdf t)))<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Transcripts}<br />\label{sec-3-14}<br /><br /><br />\begin{itemize}<br />\item If you save an \texttt{*R*} buffer, you create a transcript.<br />\item You can keep using it.<br />\item Clean up transcripts: \texttt{M-x ess-transcript-clean-buffer}<br />\item Example \texttt{files/short\_session.Rt}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{How many versions of R can I run?}<br />\label{sec-3-15}<br /><br /><br />\begin{itemize}<br />\item \texttt{M-x R} multiple times will generate multiple processes,<br /> e.g. \texttt{*R*}, \texttt{*R:2*}, \ldots{}<br />\item You can tell your .R buffer to use a particular session by \texttt{C-c C-s} and be prompted (with completion!) for R process.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Remote R sessions}<br />\label{sec-3-16}<br /><br /><br />\begin{itemize}<br />\item login to remote computer via, e.g. by a ssh command in \texttt{M-x shell}<br />\item Call \texttt{M-x ess-remote}, and select R.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Sending code from an R buffer to \texttt{*R*}}<br />\label{sec-3-17}<br /><br /><br />\begin{itemize}<br />\item An R source buffer must be associated with an iESS process. You<br /> can do this with, \texttt{C-c C-s} or accept default association.<br />\item Loading source files with \texttt{C-c C-l}; errors can be parsed with<br /> \texttt{C-c `}<br />\end{itemize}<br /><br /><br />\begin{center}<br />\begin{tabular}{ll}<br />\hline<br /> Keybinding & Function \\<br />\hline<br /> \texttt{C-c C-j} & \texttt{ess-eval-line} \\<br /> \texttt{C-c M-j} & \texttt{ess-eval-line-and-go} \\<br /> \texttt{C-c C-f} & \texttt{ess-eval-function} \\<br /> \texttt{C-c M-f} & \texttt{ess-eval-function-and-go} \\<br /> \texttt{C-c C-r} & \texttt{ess-eval-region} \\<br /> \texttt{C-c M-r} & \texttt{ess-eval-region-and-go} \\<br /> \texttt{C-c C-b} & \texttt{ess-eval-buffer} \\<br /> \texttt{C-c M-b} & \texttt{ess-eval-buffer-and-go} \\<br /> \texttt{C-c C-n} & \texttt{ess-eval-line-and-step} \\<br />\hline<br />\end{tabular}<br />\end{center}<br /><br /><br /><br /><br />\begin{itemize}<br />\item \texttt{C-c C-y} will switch to end of iESS buffer.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sending code to \texttt{*R*} --- is it slow?}<br />\label{sec-3-18}<br /><br /><br />If so, this is a long-standing bug. Add:<br /><br /><br />\begin{verbatim}<br />(setq ess-eval-visibly-p nil)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Narrowing}<br />\label{sec-3-19}<br /><br /><br />\begin{itemize}<br />\item You can temporarily narrow a buffer down to a particular region,<br /> and then \texttt{C-c C-b} works on that narrowed region:<br />\item \texttt{M-x narrow-to-region C-x n n}<br />\item \texttt{M-x narrow-to-defun C-x n d} works for R source buffers.<br />\item \texttt{M-x widen C-x n w}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Customizing ESS}<br />\label{sec-3-20}<br /><br /><br />Recommended way is to do:<br /><br />\begin{verbatim}<br /> (customize-group 'ess)<br />\end{verbatim}<br /><br />or try editing your .emacs. e.g.<br /><br />\begin{verbatim}<br /> (setq ess-ask-for-ess-directory nil)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{When things go wrong with ESS}<br />\label{sec-3-21}<br /><br /><br />\begin{itemize}<br />\item Read the info guides for sending bug reports<br />\end{itemize}<br /><br />\begin{verbatim}<br /> (info "(ess)Reporting Bugs")<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item ess-help mailing list<br />\item \href{http://www.emacswiki.org/emacs/EmacsSpeaksStatistics}{http://www.emacswiki.org/emacs/EmacsSpeaksStatistics}<br />\end{itemize}<br />\end{frame}<br />\section{Part III: Sweave}<br />\label{sec-4}<br />\begin{frame}<br />\frametitle{Literate Programming}<br />\label{sec-4-1}<br /><br /><br />From the web page describing his book \emph{Literate Programming}, Donald E<br />Knuth writes:<br /><br />``Literate programming is a methodology that combines a programming<br />language with a documentation language, thereby making programs more<br />robust, more portable, more easily maintained, and arguably more fun<br />to write than programs that are written only in a high-level<br />language. The main idea is to treat a program as a piece of<br />literature, addressed to human beings rather than to a computer. The<br />program is also viewed as a hypertext document, rather like the World<br />Wide Web. (Indeed, I used the word WEB for this purpose long before<br />CERN grabbed it!) \ldots{}''<br /><br />\url{http://www-cs-faculty.stanford.edu/~uno/lp.html}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Tangling and Weaving:}<br />\label{sec-4-2}<br /><br /><br />\begin{itemize}<br />\item CWEB: system for documenting C, C++, Java:<br />\end{itemize}<br /><br />\begin{verbatim}<br /> CTANGLE<br /> converts a source file foo.w to a compilable program file foo.c;<br /> CWEAVE<br /> converts a source file foo.w to a prettily-printable and<br /> cross-indexed document file foo.tex.<br />\end{verbatim}<br />\url{http://sunburn.stanford.edu/~knuth/cweb.html}<br />\end{frame}<br />\begin{frame}<br />\frametitle{What is Reproducible Research (RR)?}<br />\label{sec-4-3}<br /><br /><br />\begin{itemize}<br />\item Gentleman et al (2004) advocate RR:<br />\end{itemize}<br /><br />\begin{quote}<br />Buckheit and Donoho (35) , referring to the work and philosophy of<br />Claerbout, state the following principle: ``An article about<br />computational science in a scientific publication is not the<br />scholarship itself, it is merely advertising of the<br />scholarship. The actual scholarship is the complete software<br />development environment and that complete set of instructions that<br />generated the figures.''<br />\end{quote}<br /><br /> \url{http://genomebiology.com/2004/5/10/R80}<br /><br />\begin{itemize}<br />\item Bioconductor packages are good examples of reproducible research.<br />\item This article is also good background reader for open software<br /> development.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Sweave: literate programming for R}<br />\label{sec-4-4}<br /><br /><br />\begin{itemize}<br />\item Sweave is the system for mixing latex and R code in the same<br /> document.<br />\item Used within R often to create ``vignettes'' which can be<br /> dynamically run.<br />\item Allows you to write reports where results (tables,graphs) are<br /> automatically generated by your R code.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave: including code chunks}<br />\label{sec-4-5}<br /><br /><br />\begin{itemize}<br />\item An example code chunk: by default we are in `LaTeX mode'.<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />We can then test the procedure a few<br />times, using the default number<br />of darts, 1000:<br /><br />&lt;&lt;&gt;&gt;=<br />replicate(9, estimate.pi())<br />@<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave: including graphs}<br />\label{sec-4-6}<br /><br /><br />\begin{itemize}<br />\item Automatically creates filenames, e.g. \verb~estimate-001.pdf~<br />\item By default will generate .ps and .pdf; so change options:<br />\end{itemize}<br />\begin{verbatim}<br /> \SweaveOpts{echo=T,pdf=T,eps=F,eval=T,keep.source=T}<br />\end{verbatim}<br /><br /><br />\begin{verbatim}<br />\setkeys{Gin}{width=0.6\textwidth}<br />\begin{center}<br />&lt;&lt;fig=TRUE&gt;&gt;=<br />r &lt;- 1; n &lt;- 50; par(las=1)<br />plot(NA, xlim=c(-r,r), ylim=c(-r,r), asp=1, bty='n',<br /> xaxt='n', yaxt='n', xlab='', ylab='')<br />axis(1, at=c(-r,0,r)); axis(2, at=c(-r,0,r))<br />symbols(x=0, y=0, circles=r, inch=F, add=T)<br />...<br />rect(-r, -r, r, r, border='blue', lwd=2)<br />@<br />\end{center}<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave: including tables}<br />\label{sec-4-7}<br /><br /><br />\begin{itemize}<br />\item Use the \emph{xtable} package from CRAN.<br />\item Example from that package:<br />\end{itemize}<br /><br /><br /><br />\begin{verbatim}<br />&lt;&lt;echo=FALSE&gt;&gt;=<br />library(xtable)<br />data(tli)<br />@<br /><br />&lt;&lt;label=tab1,echo=FALSE,results=tex&gt;&gt;=<br /> ## Demonstrate data.frame<br /> tli.table &lt;- xtable(tli[1:20,])<br /> digits(tli.table)[c(2,6)] &lt;- 0<br /> print(tli.table)<br />@<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave: including inline computation}<br />\label{sec-4-8}<br /><br /><br /><br />\begin{verbatim}<br />In this case the number of darts within<br />the circle is \Sexpr{d}, and so the estimated<br />value is $\pi \approx \Sexpr{4*d/n}$.<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave: a full example}<br />\label{sec-4-9}<br /><br />\begin{itemize}<br />\item Example application: estimate the value of $\pi$ using the<br />\end{itemize}<br /> dartboard method.<br />\begin{itemize}<br />\item \href{file://.~/papers/2009_R/estimate.Rnw}{estimate.Rnw}<br />\item For nice ways to customize Sweave output (as in estimate.Rnw:<br />\end{itemize}<br />\url{http://www.stat.auckland.ac.nz/~stat782/downloads/Sweave-customisation.pdf}<br /><br />\begin{itemize}<br />\item Compiling the document with make:<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />estimate.pdf: estimate.Rnw<br /> R CMD Sweave estimate.Rnw<br /> pdflatex estimate.tex<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Note: \texttt{R CMD Sweave -{}-pdf} (since R 2.14.0)<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Emacs and Sweave: how to get n&gt;1 major-mode?}<br />\label{sec-4-10}<br /><br /><br />\begin{itemize}<br />\item How can we switch between major modes within the same buffer?<br />\item Approach: R-mode for code chunks, AUCTeX for latex sections.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Why AUCTeX?}<br />\label{sec-4-11}<br /><br /><br />\begin{itemize}<br />\item \href{http://www.gnu.org/software/auctex/}{http://www.gnu.org/software/auctex/}<br />\item Excellent environment for (1) editing, (2) compiling and (3) viewing output.<br />\item Shortcuts for inserting environments, blocks, and for completion.<br />\item Interacts well with bibtex too.<br />\item Reftex allows for easy editing/viewing of citations,<br /> table-of-contents. (Carsten Dominik).<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Exercise: compile/edit a document in AUCTeX}<br />\label{sec-4-12}<br /><br /><br />\begin{itemize}<br />\item Warning: may need to install AUCTeX<br />\end{itemize}<br /><br /> See example \href{file:///u/maechler/R/Meetings-Kurse-etc/2012-Nashville/ESS-tutorial/ess2012/coin/coin.tex}{file:coin/coin.tex} and try the following<br /><br />\begin{itemize}<br />\item edit it, compile it, fix errors.<br />\item What do these commands do? \texttt{C-c [} \texttt{C-c \&}<br />\item Browse the TOC: \texttt{C-c =}<br />\item I prefer to generate PDF (rather than postcript): \texttt{C-c C-t C-p}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Makefiles / compile modes.}<br />\label{sec-4-13}<br /><br /><br />\begin{itemize}<br />\item One approach to compiling your document is to use Makefiles.<br />\item Emacs can run these with \texttt{M-x compile}<br />\item Output shown in own buffer, which can be parsed.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave editing help}<br />\label{sec-4-14}<br /><br /><br />\begin{itemize}<br />\item Typing \texttt{&lt;} at start of line is \emph{electric} and will expand to:<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />&lt;&lt;&gt;&gt;=<br />@<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Has many functions for navigating around and moving chunks. See the<br /> Noweb menu.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Sweave compilation}<br />\label{sec-4-15}<br /><br /><br />\begin{itemize}<br />\item `M-n s' (`ess-swv-weave')<br /> Run Sweave on the current .Rnw file.<br />\item `M-n l' (`ess-swv-latex')<br /> Run \LaTeX{} after Sweave'ing.<br />\item `M-n p' (`ess-swv-PS')<br /> Generate and display a postscript file after LaTeX'ing.<br />\item `M-n P' (`ess-swv-PDF')<br /> Generate and display a PDF file after<br /> LaTeX'ing. The command used to generate the PDF file is the<br /> first element of `ess-swv-pdflatex-commands'.<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Sweave + AUCTeX}<br />\label{sec-4-16}<br /><br /><br /> This needs to be added in .emacs before place you load ESS, then<br /> restart Emacs. (\textbf{New since ESS 5.14.})<br /><br /><br />\begin{verbatim}<br />(setq ess-swv-plug-into-AUCTeX-p t)<br />\end{verbatim}<br /><br />\begin{itemize}<br />\item Within an R buffer, \texttt{C-c C-c Sweave} runs Sweave in a separate<br /> process, not \texttt{*R*}.<br />\item Compile latex file with \texttt{C-c C-c LaTeXSweave}.<br />\item View resulting file with \texttt{C-c C-c View}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{How it works in Emacs (advanced)}<br />\label{sec-4-17}<br /><br /><br />\begin{itemize}<br />\item multiple-major modes is quite fragile; more principled approaches<br /> welcome, e.g. based on Dave Love's work (indirect buffers).<br />\item Current approach assumes that every time you switch in/out of a<br /> chunk, the major mode is reset; any local variable modifications<br /> must be set in hooks.<br />\end{itemize}<br />\end{frame}<br />\section{Part IV: Org mode}<br />\label{sec-5}<br />\begin{frame}[fragile]<br />\frametitle{Prelim: make sure you have Org installed, see earlier section.}<br />\label{sec-5-1}<br /><br /><br /><br />\begin{verbatim}<br />(require 'org-install)<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{My org mode setup}<br />\label{sec-5-2}<br /><br /><br />\begin{verbatim}<br />(add-to-list 'load-path "~/langs/emacs/elisp-ds/org-mode/lisp")<br />(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))<br />(global-set-key "\C-cl" 'org-store-link)<br />(global-set-key "\C-ca" 'org-agenda)<br />(setq org-completion-use-iswitchb t)<br />(global-set-key "\C-cb" 'org-iswitchb)<br /><br />;; stop C-c C-c within code blocks from querying<br />(setq org-confirm-babel-evaluate nil)<br /><br />;; which languages do I want??<br />(org-babel-do-load-languages<br /> 'org-babel-load-languages<br /> '((R . t)<br /> (sh . t)<br /> (emacs-lisp . t)<br /> ))<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Live demo !}<br />\label{sec-5-3}<br /><br /><br />\begin{itemize}<br />\item Follow demo in \href{file:///u/maechler/R/Meetings-Kurse-etc/2012-Nashville/ESS-tutorial/ess2012/org/intro.org}{file:org/intro.org}<br />\item simple outlining: folding/ moving/ promoting+demoting<br />\item simple markup, e.g. \textbf{bold} \emph{italics} \underline{underscore} and \verb~verbatim~<br />\item editing lists<br />\item look how math is formatted\ldots{} $\alpha$ + $\beta$ without the need for<br /> math mode?<br />\item tables; spreadsheets.<br />\item export<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Other key features of org mode (not covered here)}<br />\label{sec-5-4}<br /><br /><br />\begin{itemize}<br />\item agendas, dates.<br />\item scheduler<br />\item clocking tasks<br />\item todo lists<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Including code snippets}<br />\label{sec-5-5}<br /><br /><br /><br />\begin{verbatim}<br />#+begin_src R :exports both :results graphics :file hist.png<br /> hist( rnorm(1e4))<br />#+end_src<br />\end{verbatim}<br /><br />These enviroments can be added using ``Easy Templates'', e.g. \texttt{&lt; s TAB}<br />to get a source block.<br /><br />These code snippets can be run using \texttt{C-c C-c} to generate results<br />after the code snippet. see ob-R-examples.org<br />\end{frame}<br />\begin{frame}<br />\frametitle{Exercise: Org examples to explore}<br />\label{sec-5-6}<br /><br /><br />\begin{enumerate}<br />\item \href{file:///u/maechler/R/Meetings-Kurse-etc/2012-Nashville/ESS-tutorial/ess2012/org/nice/nice.org}{file:org/nice/nice.org} and export it to either latex --&gt;<br /> pdf or html (\texttt{C-c C-e} for export menu)<br /><br /> \href{http://emacs-fu.blogspot.com/2011/04/nice-looking-pdfs-with-org-mode-and.html}{http://emacs-fu.blogspot.com/2011/04/nice-looking-pdfs-with-org-mode-and.html}<br />\item \href{file:///u/maechler/R/Meetings-Kurse-etc/2012-Nashville/ESS-tutorial/ess2012/org/drift/drift.org}{file:org/drift/drift.org} -- Genetic drift. For browsing and<br /> exporting.<br /><br /> \href{http://orgmode.org/worg/org-contrib/babel/uses.html}{http://orgmode.org/worg/org-contrib/babel/uses.html}<br />\end{enumerate}<br /><br /><br />\begin{enumerate}<br />\item ob-R-examples.org -- Some simple examples in R, to run and export.<br />\item CISE -- convert this to use R rather than gnuplot. Or try to<br /> get the baseball stats for year other than 2010.<br /><br /> Eric Schulte, Dan Davison. Active Documents with Org-Mode<br /> Computing in Science \& Engineering 2011.<br /><br /> \href{http://www.cs.unm.edu/~eschulte/data/CISE-13-3-SciProg.pdf}{http://www.cs.unm.edu/\~eschulte/data/CISE-13-3-SciProg.pdf}<br />\end{enumerate}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Problems with org-mode for RR}<br />\label{sec-5-7}<br /><br /><br />\begin{enumerate}<br />\item Is it prime for RR yet?<br />\item Emacs 24 as stable base for documents\ldots{}<br />\item Tom Dye has a nice reproducible solution for Org config.<br /> \href{https://github.com/tsdye/hawaii-colonization}{https://github.com/tsdye/hawaii-colonization}<br />\item How do \textbf{you} think it compares with sweave?<br />\end{enumerate}<br />\end{frame}<br />\section{Advanced topics}<br />\label{sec-6}<br />\begin{frame}<br />\frametitle{Speedbar support for R code / imenu}<br />\label{sec-6-1}<br /><br /><br />\begin{itemize}<br />\item \texttt{M-x speedbar}<br />\item Driven by the imenu support, which in turn depends on<br /> \texttt{ess-imenu-S-generic-expression} which you see has \texttt{&lt;-}<br /> hard-coded.<br />\item Show examples in \texttt{files/ms\_funs.R}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Support for editing Roxygen documentation.}<br />\label{sec-6-2}<br /><br /><br />\begin{itemize}<br />\item See info node for full details: \texttt{(info "(ess)Roxygen")}<br />\end{itemize}<br /><br /><br />\begin{verbatim}<br />##' Description of the function<br />##'<br />##' Further details about this function<br />##' @title A title<br />##' @param me all parameters must be listed and documented<br />##' @return Description of the return value<br />##' @author The author<br />myfun &lt;- function(me)<br /> cat("Hello", me, "\n")<br />@end verbatim<br />\end{verbatim}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{TAGS support}<br />\label{sec-6-3}<br /><br /><br />\begin{itemize}<br />\item TAGS files are supported for many different editing modes.<br />\item They contain a list of where functions are defined in your source<br /> file.<br />\item Normally found by regexps, but R now can generate tags directly:<br /><br />\begin{verbatim}<br /> R CMD rtags --help<br />\end{verbatim}<br />\item You can then ask Emacs to find definition of function name under<br /> point.<br />\item \texttt{(info "(ess)TAGS")}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{ESS-rdired}<br />\label{sec-6-4}<br /><br /><br />\begin{itemize}<br />\item Mode inspired by Dired for files.<br />\item For viewing objects, deleting, plotting.<br />\item \texttt{(info "(ess)Rdired")}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Rutils}<br />\label{sec-6-5}<br /><br />\begin{itemize}<br />\item Recent addition to ESS, building upon ess-rdired. Adds many convenience functions.<br />\item Browsing, adding, updating packages<br />\item Editing objects<br />\item Managing workspaces<br />\item \texttt{(info "(ess)Rutils")}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}[fragile]<br />\frametitle{Dynamically showing arguments of a function}<br />\label{sec-6-6}<br /><br /><br />Both of these methods work by calling the R function \texttt{args()} with<br />function name under point. What differs is the feedback mechanism.<br />\begin{itemize}<br /><br />\item ess-eldoc, works like other eldoc modes, e.g. elisp.\\<br />\label{sec-6-6-1}%<br />\href{file://.example.R}{Eldoc example}<br /><br /><br />\begin{verbatim}<br />(require 'ess-eldoc)<br />(add-hook 'inferior-ess-mode-hook 'ess-use-eldoc)<br />\end{verbatim}<br /><br /><br />\item ess-r-args-show\\<br />\label{sec-6-6-2}%<br />\begin{verbatim}<br />;; bind ess-r-args-show to F2<br />(define-key ess-mode-map [f2] 'ess-r-args-show)<br />\end{verbatim}<br /><br />\end{itemize} % ends low level<br />\end{frame}<br />\begin{frame}<br />\frametitle{r-autoyas}<br />\label{sec-6-7}<br /><br /><br />\begin{itemize}<br />\item \href{http://www.svenhartenstein.de/Software/R-autoyas}{http://www.svenhartenstein.de/Software/R-autoyas}<br />\item Dynamically creates \emph{snippets} for editing R functions. Watch the<br /> movie online at:<br /><br /> \href{http://www.youtube.com/watch?v=jLJPorf2LBE}{http://www.youtube.com/watch?v=jLJPorf2LBE}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Debuggers}<br />\label{sec-6-8}<br /><br /><br />\begin{enumerate}<br />\item Since ESS 12.03, \emph{Ess-tracebug} is part of ESS:<br /> ``A package for interactive visual debugging of R<br /> code from ESS. It provides visual debugging, browser, recover and<br /> conditional breakpoints; watch window and loggers; interactive<br /> debug/undebug of R functions and methods at point; highlighting<br /> and easy error navigation and interactive traceback.''<br /> Docu \href{http://code.google.com/p/ess-tracebug/}{http://code.google.com/p/ess-tracebug/}<br />\item There are \textbf{R} packages for enhanced debugging, notably \emph{edtdbg}<br /> ``integrates R's debugging facilities with your<br /> text editor, featuring code tracking, variable display, quick<br /> breakpoint setting, and easy toggling of function debug status.''<br /> It provides support for both Emacs and VIM. Package available<br /> from CRAN mirrors.<br />\end{enumerate}<br />\end{frame}<br />\begin{frame}<br />\frametitle{R Object Tooltips in ESS}<br />\label{sec-6-9}<br /><br /><br />\begin{itemize}<br />\item Watch the movie to see the tooltips for object at point:<br /> \href{http://www.sigmafield.org/2009/10/01/r-object-tooltips-in-ess}{http://www.sigmafield.org/2009/10/01/r-object-tooltips-in-ess}<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Rewrite of interface to inferior processes (SLIME)}<br />\label{sec-6-10}<br /><br /><br />\begin{itemize}<br />\item ESS uses comint to interface with R processes.<br />\item Better solution, based on sockets, rather than text-based<br /> channels, is to use SLIME framework.<br />\item Work in progress (Christophe Rhodes):<br /><br /> \href{http://common-lisp.net/~crhodes/swankr/}{http://common-lisp.net/\~crhodes/swankr/}<br />\end{itemize}<br />\end{frame}<br />\section{Part V Future steps / Q \& A session / open discussion}<br />\label{sec-7}<br />\begin{frame}<br />\frametitle{Final discussion}<br />\label{sec-7-1}<br /><br /><br />\begin{itemize}<br />\item What would you like to ask?<br />\item e.g. Can I do X with Emacs / ESS?<br />\item What is the focus for future development of ESS?<br />\end{itemize}<br />\end{frame}<br />\begin{frame}<br />\frametitle{Further reading}<br />\label{sec-7-2}<br /><br /><br />\begin{enumerate}<br />\item \emph{Intro to emacs lisp} is a great introduction to learning elisp.<br />\item \emph{Org mode} manual. Warning: it is big! You might prefer the<br /> `compact' guide: \href{http://orgmode.org/guide/index.html}{http://orgmode.org/guide/index.html}<br />\end{enumerate}<br />\end{frame}<br />\section{End}<br />\label{sec-8}<br />\begin{frame}<br />\frametitle{My contact details}<br />\label{sec-8-1}<br /><br /><br />\begin{itemize}<br />\item Stephen Eglen<br />\item sje30@cam.ac.uk<br />\item Tel: 01223 765761<br />\item Web: \href{http://www.damtp.cam.ac.uk/user/sje30/}{http://www.damtp.cam.ac.uk/user/sje30/}<br />\end{itemize}<br />\end{frame}<br /><br />\end{document}<br /><br /></div>

   * [[%ATTACHURL%/ess-slides.org][ess-slides.org]]: Org-mode "Source" of the slides
Hint: I prefer to edit the wiki using the "Raw edit" button below; this provides a simple text box, and forces the use of wiki syntax. Use the "Attach" button below to upload files. There are some wiki text formatting rule here: System.TextFormattingRules

   * [[%ATTACHURL%/ess-slides.pdf][ess-slides.pdf]]: PDF / Presentation "version" of slides

   * [[%ATTACHURL%/Sweave-Example-collection.org][Sweave-Example-collection.org]]: Collection of Martin's Sweave examples

   * [[%ATTACHURL%/Sweave-Example-collection_files.zip][Sweave-Example-collection_files.zip]]: the Rnw source files of the collection

   * [[%ATTACHURL%/new.r][new.r]]: graphics R script file from tutorial

   * [[%ATTACHURL%/new.Rout][new.Rout]]: transcript file from graohcs example
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
org	Sweave-Example-collection.org	manage	1.3 K	12 Jun 2012 - 11:47	RichHeiberger	Collection of Martin's Sweave examples
zip	Sweave-Example-collection_files.zip	manage	48.4 K	12 Jun 2012 - 11:48	RichHeiberger	the Rnw source files of the collection
r	demo.r	manage	0.1 K	12 Jun 2012 - 08:26	RichHeiberger
org	ess-slides.org	manage	37.2 K	11 Jun 2012 - 22:07	RichHeiberger	Org-mode "Source" of the slides
pdf	ess-slides.pdf	manage	713.1 K	12 Jun 2012 - 06:25	RichHeiberger	PDF / Presentation "version" of slides
r	fake.plot.data.frame-setup.r	manage	0.9 K	12 Jun 2012 - 08:25	RichHeiberger
r	fake.plot.data.frame.r	manage	0.1 K	12 Jun 2012 - 08:25	RichHeiberger
pdf	ggraph.pdf	manage	1109.4 K	12 Jun 2012 - 11:49	RichHeiberger	the paper produced from the ggraph.Rnw Sweave example
Rout	new.Rout	manage	2.6 K	14 Jun 2012 - 12:12	RichHeiberger	transcript file from graohcs example
r	new.r	manage	0.5 K	14 Jun 2012 - 12:11	RichHeiberger	graphics R script file from tutorial
pdf	rmhslides.pdf	manage	29.5 K	12 Jun 2012 - 08:26	RichHeiberger
r	tmp.r	manage	0.1 K	12 Jun 2012 - 08:25	RichHeiberger
Topic revision: r10 - 14 Jun 2012, RichHeiberger
Main
Department Home Page
Biostatistics Graduate Program
Vanderbilt University Medical Center
Biostatistics Webs
- Archive
- Main
- Sandbox
- System
Copyright © 2013-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback