9 R tutorial

Getting Files and Starting R

Go to your DOS shell (eshell works better than shell on Windows):
```
M-x eshell
```
The emacs shortcut on your DVD is set to start up in your network drive, which is drive H:. If your emacs shell starts on the DVD drive, you should change to a drive that you can write on/save files to.
```
C:
cd %userprofile%
```
or
```
H:
```
Userprofile is your home directory on windows, and probably a reasonable place to start on your home computer. H is a shared drive on UT campus PCs. Anything saved on this drive will be available to you on any UT PC. Keep in mind, however, that you have only 50M (250M?) of space here. That is ample for all the R work you will do, but you might prefer to carry a flash drive, which will be F: in the Newton lab.

In your shell

wget http://potis.org/~poti/tutorial/fisher.r

Open the file:
```
C-x C-f fisher.r
```
Start R by pressing:
```
M-x R
```

R will probably say it cannot read .Rhistory. That is fine and correct, since this is probably your first session on this computer. .Rhistory is the history of all the R commands you typed in your session. If this is your first session, clearly there are none. However, you might find this useful if you plan to stop an re-start your work. In than case, on campus you may want to select a directory on your H: drive when R prompts you for a starting directory.

You will probably also see the message 'timed out waiting for prompt.' Just wait. Reading from DVD is slower than ESS expects.

The above steps demonstrate emacs as an integrated environment for getting a file, opening a file, and the existence of emacs 'modes' which are triggered by the type of file being viewed. In particular, you can see that R mode, triggered by opening a file ending in .r (or .R), has syntax highlighting, indentation, and special menus and functions.

While you can get files in various ways from within R, using the shell has some advantages at this point:

You know where your file is.
You can see the relationship between what your operating system sees and what is available to R.
You can get accustomed to using a broader range of your computer's capabilities.
You have the file to work with in Emacs so you can not only see the code and see what it does, but you can edit it and see the effects of your changes.

The final point is related to why we stress stepping through the code one line at a time (C-c C-n), or later through a debugger, rather than just sending the whole buffer (C-c C-b) and seeing the final answers. This can also be done by typing commands by hand (but do get into the habit of using tab completion) in the R command buffer. Done through Emacs, you still have all the editor functions so you can edit and save what you have written in the command buffer.

Using R With ESS

The packages that provides the editing abilities for the R emacs mode is ESS. Take some time to explore some of the features of ESS, trying things out in the two buffers you created by opening fisher.r and launching R.

Put your cursor in the fisher.r buffer and go to the help menu.
It may be helpful to divide the screen one more time at this point:
```
C-x 2
```
Practice switching between screens
```
C-x o
```
and between buffers
```
C-x b
```
Click on the ESS menu and select
```
Read ESS Info
```
Your screen will split into three screens. Keep in mind
```
C-x o
```
so you can switch between them to try out the things you read in the Info.
Most useful to you might be *Entering commands*. Look through the section on completion, and try out some examples in your *R* buffer. These features refer to the *R* buffer.
Go to the ESS menu again and select About editing. Most useful will probably be *Sending code to the ESS process*
Try the editing commands on the fisher.r buffer. Editing commands refer to that buffer.
At this point, stepping through code will probably be your most useful command. Use
```
C-c C-n 
```
to step through the code.
Look at the introduction again and lets try some of the ess process commands (in particular, completion)
```
TAB
```
Try completion in the editing window
```
M-TAB
```

Help on specific R objects.

Help on specific R objects and commands:
```
C-c C-v
```
Try getting help on the rmultinom function in the fisher.r code by placing your cursor on the function name and pressing
```
C-c C-v
```
Note the structure of the help:
It contains:
```
the name, the package
a short description
a longer description
the usage
an explanation of the argument that can be passed to the function
a detailed discussion of how the function and arguments are used
values returned
notes
references
and a set of examples.
```
Copying and pasting the examples into a buffer and stepping through them can be a very valuable way to understand the function:
```
C-SPACE move cursor
C-w 
C-x o
C-y
```
Try an example from glm.

General Help

Have a look at the help from your *R* buffer:
```
help.start()
```
Notice the structure of the help files for the specific packages. These are the same help texts that comes up in Emacs when you type
```
C-c C-v
```
Of the categories on the help.start() page that will probably be of most use to you at this stage are the description of all packages, Data Import/Export, and Search and Keywords. The Search and Keyword link gives the same output as help.search(). However, it is much faster than help.search() since we are running from DVD.
We showed you where you can find Various Tutorials.
Of these, the most useful to you for daily use will probably be the English or Chinese version of the Ref card by Tom Short.

Coding Style.

To make your code easier for you and others to read and maintain: RCC :R Coding Conventions.

Writing R packages

Refactoring your code into an R package helps get the most out of your writing: Packages

Last modified: Wed Jan 24 13:44:09 EST 2007