doc/user-manual/ess-user.xml

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2
   3 <!DOCTYPE book PUBLIC "-//Arbortext//DTD DocBk XML V2.0//EN"
   4  "file:///home/rossini/sandbox/local/Src/Emacs/xae/doctypes/docbook/docbookx.dtd" [
   5 <!ENTITY ess "ESS">
   6 <!ENTITY intro SYSTEM "ess-cha-intro.xml">
   7 <!ENTITY basic SYSTEM "ess-cha-basic.xml">
   8 <!ENTITY advanced SYSTEM "ess-cha-advanced.xml">
   9 <!ENTITY esslS SYSTEM "ess-cha-S.xml">
  10 <!ENTITY esslSAS SYSTEM "ess-cha-SAS.xml">
  11 <!ENTITY esslStata SYSTEM "ess-cha-Stata.xml">
  12 <!ENTITY esslXLispStat SYSTEM "ess-cha-xlispstat.xml">
  13 <!ENTITY essExS SYSTEM "ess-app-example-S.xml">
  14
  15 ]>
  16
  17 <?xml-stylesheet
  18   href="file:///home/rossini/sandbox/local/Src/Emacs/xae/doctypes/docbook/styles/docbook/html/docbook.xsl"
  19   type="text/xsl"?>
  20
  21 <book>
  22   <title>Emacs Speaks Statistics User Manual</title>
  23   <titleabbrev>ESS User Manual</titleabbrev>
  24   <bookinfo>
  25     <legalnotice>
  26       <para>
  27         This work is copyright A.J. Rossini,
  28         <email>rossini@u.washington.edu</email>
  29       </para>
  30     </legalnotice>
  31     <author>
  32       <firstname>Anthony</firstname>
  33       <surname>Rossini</surname>
  34       <affiliation>
  35         <orgname>
  36           Department of Biostatistics, University of Washington
  37         </orgname>
  38         <address format="linespecific">
  39           Box 292731
  40           Seattle, WA 98195
  41         </address>
  42       </affiliation>
  43     </author>
  44   </bookinfo>
  45   <dedication>
  46     <para>
  47       This is dedicated to free time.
  48     </para>
  49   </dedication>
  50
  51   &intro;
  52
  53   <!--  &basic; -->
  54
  55   <appendix>
  56   <title>Examples for using S</title>
  57
  58   <para>
  59     We present some basic suggestions for using ESS to interact with
  60     S.  These are just a subset of approaches, many better approaches
  61     are possible.  Contributions of examples of how you work with ESS
  62     are appreciated (especially since it helps us determine priorities
  63     on future enhancements)! (comments as to what should be happening
  64     are prefixed by "##").
  65   </para>
  66
  67     <para>
  68       <literallayout format="linespecific" class="normal">
  69 1:  ##    Data Analysis Example (source code is real)
  70     ## Load the file you want to work with
  71     C-x C-f myfile.s
  72
  73     ## Edit as appropriate, and then start up S-PLUS 3.x
  74     M-x S+3
  75
  76     ## A new buffer *S+3:1* will appear.  Splus will have been started
  77     ## in this buffer.  The buffer is in iESS [S+3:1] mode.
  78
  79     ## Split the screen and go back to the file editing buffer.
  80     C-x 2 C-x b myfile.s
  81
  82     ## Send regions, lines, or the entire file contents to S-PLUS. For regions,
  83     ## highlight a region with keystrokes or mouse and then send with:
  84     C-c C-r
  85
  86     ## Re-edit myfile.s as necessary to correct any difficulties.  Add
  87     ## new commands here.  Send them to S by region with C-c C-r, or
  88     ## one line at a time with C-c C-n.
  89
  90     ## Save the revised myfile.s with C-x C-s.
  91
  92     ## Save the entire *S+3:1* interaction buffer with C-c C-s.  You
  93     ## will be prompted for a file name.  The recommended name is
  94     ## myfile.St.  With the *.St suffix, the file will come up in ESS
  95     ## Transcript mode the next time it is accessed from Emacs.
  96       </literallayout>
  97     </para>
  98
  99     <para>
 100       <literallayout>
 101 2:  ## Program revision example (source code is real)
 102
 103     ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
 104     M-x S+3
 105
 106     ## Load the file you want to work with
 107     C-x C-f myfile.s
 108
 109     ## edit program, functions, and code in myfile.s, and send revised
 110     ## functions to S when ready with
 111     C-c C-f
 112     ## or highlighted regions with
 113     C-c C-r
 114     ## or individual lines with
 115     C-c C-n
 116     ## or load the entire buffer with
 117     C-c C-l
 118
 119     ## save the revised myfile.s when you have finished
 120     C-c C-s
 121 </literallayout></para>
 122
 123     <para>
 124       <literallayout>
 125 3:  ## Program revision example (S object is real)
 126
 127     ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
 128     M-x S+3
 129
 130     ## Dump an existing S object my.function into a buffer to work with
 131     C-c C-d my.function
 132     ## a new buffer named yourloginname.my.function.S will be created with
 133     ## an editable copy of the object.  The buffer is associated with the
 134     ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not
 135     ## exist after you log off.
 136
 137     ## enter program, functions, and code into work buffer, and send
 138     ## entire contents to S-PLUS when ready
 139     C-c C-b
 140
 141     ## Go to *S+3:1* buffer, which is the process buffer, and examine
 142     ## the results.
 143     C-c C-y
 144     ## The sequence C-c C-y is a shortcut for:  C-x b *S+3:1*
 145
 146     ## Return to the work buffer (may/may not be prefixed)
 147     C-x C-b yourloginname.my.function.S
 148     ## Fix the function that didn't work, and resubmit by placing the
 149     ## cursor somewhere in the function and
 150     C-c C-f
 151     ## Or you could've selected a region (using the mouse, or keyboard
 152     ## via setting point/mark) and
 153     C-c C-r
 154     ## Or you could step through, line by line, using
 155     C-c C-n
 156     ## Or just send a single line (without moving to the next) using
 157     C-c C-j
 158     ## To fix that error in syntax for the "rchisq" command, get help
 159     ## by
 160     C-c C-v rchisq
 161       </literallayout>
 162     </para>
 163
 164     <para>
 165       <literallayout format="linespecific" class="normal">
 166 4:  Data Analysis (S object is real)
 167     ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*)
 168     M-x S+3
 169
 170     ## Work in the process buffer.  When you find an object that needs
 171     ## to be changed (this could be a data frame, or a variable, or a
 172     ## function), dump it to a buffer:
 173     C-c C-d my.cool.function
 174
 175     ## Edit the function as appropriate, and dump back in to the
 176     ## process buffer
 177     C-c C-b
 178
 179     ## Return to the S-PLUS process buffer
 180     C-c C-y
 181     ## Continue working.
 182
 183     ## When you need help, use
 184     C-c C-v rchisq
 185     ## instead of entering:   help("rchisq")
 186       </literallayout>
 187     </para>
 188   </appendix>
 189
 190     <appendix>
 191       <title>Customization Examples and Solutions to Problems</title>
 192       <para>
 193         <literallayout format="linespecific" class="normal">
 194 1. Suppose that you are primarily an SPLUS 3.4 user, occasionally
 195    using S version 4, and sick and tired of the buffer-name *S+3*
 196    we've stuck you with.  Simply edit the "ess-dialect" alist entry in
 197    the essd-s+3.el and essd-s4.el files to be "S" instead of "S4" and
 198    "S+3".  This will insure that all the inferior process buffer names
 199    are "*S*".
 200 </literallayout>
 201
 202         <literallayout format="linespecific" class="normal">
 203 2. Suppose that you WANT to have the first buffer name indexed by
 204    ":1", in the same manner as your S-PLUS processes 2,3,4, and 5 (for
 205    you heavy simulation people).  Then uncomment the line in ess-site
 206    (or add after your (require 'ess-site) or (load "ess-site") command
 207     in your .emacs file, the line:
 208
 209        (setq ess-plain-first-buffername nil)
 210    )
 211 </literallayout>
 212
 213         <literallayout>3. Fontlocking sometimes fails to behave nicely upon errors.  When
 214    Splus dumps, a mis-matched "  (double-quote) can result in the
 215    wrong font-lock face being used for the remainder of the buffer.
 216
 217    Solution: add a " at the end of the "Dumped..." statement, to
 218    revert the font-lock face back to normal.
 219         </literallayout>
 220       </para>
 221     </appendix>
 222 </book>
 223
 224 <!--
 225 Local Variables:
 226 mode: xae
 227 sgml-indent-step:2
 228 sgml-indent-data:t
 229 sgml-set-face: t
 230 sgml-insert-missing-element-comment: nil
 231 sgml-omittag:nil
 232 sgml-shorttag:nil
 233 sgml-namecase-general:nil
 234 sgml-general-insert-case:lower
 235 sgml-minimize-attributes:nil
 236 sgml-always-quote-attributes:t
 237 sgml-parent-document:nil
 238 sgml-exposed-tags:nil
 239 sgml-local-catalogs:nil
 240 sgml-local-ecat-files:nil
 241 End:
 242 -->
 243