Tinn-R is probably the best text file editor to use in conjunction with the R program. It is specifically designed for working with R script files. In addition to syntax highlighting of R code, Tinn-R can interact with R using specific menus and tool bars. This means that sections of commands can be highlighted and sent to the R console (sourced) with a single button click. Line numbers can be shown and open and closed brackets can be matched. These features are important because they are commonly used in the R command language. Tinn-R can be downloaded from the Internet at: www.sciviews.org/Tinn-R. The software can be installed in the conventional fashion as all other software, i.e. by executing the "setup.exe" file and following the instructions.
R command file
At this stage the R commands have been pasted into the console and interpreted as if they had been typed in manually. If there are no errors, the output should appear as in the screen capture on the previous page. Note that R commands are displayed in red and the output in blue. To save the commands to a text file point our mouse to the menu bar at the top left of the R console window and click 'File...Save History...' Then choose an appropriate filename for the work you have been doing, and save it in your current R working directory.
The file can then be opened using your favourite text editor. In this course we recommend using Tinn-R, but there are many others to choose from, such as Crimson Editor, Winedt, Open Office, vi, emacs, Xemacs, MS Wordpad, or even Notepad. All these editors have their followers and some have nice features, such as colour highlighting of recognized functions, however Tinn-R is the only one that interacts with R.
To be a professional data analyst, one would rather create and edit command files and run either a part of the file or the whole file and read the output from the R console. When an error is detected, the offending command in the command file should be immediately corrected and the commands or file run again. This iterative process continues until the end of the analysis session where the command file is either saved for future use or ignored (if the analysis is meant to be only temporary).
There are four alternative methods in this iterative process.
1. Copying parts or the entire command file from Tinn-R and pasting them into the R console.
2. "Sourcing" the whole command file from the R console.
3. Sending parts or the entire command file from Tinn-R to the R console by clicking one of the 'send' buttons.
4. Defining 'hotkeys' in Tinn-R and pressing the appropriate key on the keyboard.
The first method is straight-forward. This can be used with any text editor. The second method is discussed next. The third and fourth methods are specific for Tinn-R.
Start Tinn-R. Open the file that you saved in the previous step above. It should look something like the screen shot shown here. Notice the line numbers in the gutter area to the left of the commands. If you do not see them then press <Ctrl> + L to make them visible or click 'Options…
The familiar copy & paste method still works, however the most conventional method is to use the source command. Switch to R console and type the following commands:
> getwd() # get the current working directory
> dir() # list all files in the current working directory
Whenever you learn a new command it is advisable to look at the help page to familiarize yourself with the usage. The help page for the source function tells us that the first argument is the name of the file (with an optional pathname) or a URL (which means you can read in commands from a file located on the Internet). This argument is mandatory (cannot be omitted), however the others are optional, and if omitted, R will assume the values as stated in the usage. For example, 'local' will be assumed "FALSE" and 'echo' assumed to be the value of the 'verbose' argument, which is (by default) "TRUE". Most optional arguments to functions can be ignored, and to be honest, are difficult to understand anyway.
If nothing happens after typing the third command above, then don't worry – you have done nothing wrong. R has quietly run the commands in the background since the 'echo' argument was omitted. Now type the following command:
> source("myfile.r", echo=TRUE)
You should see output very similar to that shown on the previous page. However, note that the R commands are shown in blue colour, and not red as before.
More conveniently, selected commands from a command file can be sent to the R console by clicking a button or pressing a key on the keyboard in much the same way that commands are sent to Stata from the Do-file editor or in SPSS using the Syntax Editor. Switch back to Tinn-R, either by using your mouse to find it in the taskbar, or by toggling on the keyboard (<Alt> + <Tab>). Click the first button highlighted in the screen capture above. If you hover the mouse over the button the caption 'Send file (source)' will appear briefly. Alternatively, from the menu bar at the top, you can click 'R…Send to R…File (source)'. You should see the source command appear in the R console, with the full pathname of the file as the first argument.
Return to Tinn-R and click the second button highlighted, or click 'R…Send to R…All' from the menu bar. The output should be similar to that shown on the previous page, with R commands in red.
Using the mouse, click on line numbers
For those who prefer not to use the mouse too often, you may set up the hotkeys to perform the above tasks. Switch focus to Tinn-R and using your mouse click R from the menu bar and select 'Hotkeys of R (operational system)'. Define the hotkeys for each function one by one using the form as shown on the next page. The hotkeys defined here are given as a guide only and users are fully free to define their own.
Click OK to return back to the command file. Now test each hotkey one by one. These hotkeys are active throughout Windows, so that pressing a hotkey will activate it even if the Tinn-R application does not have the focus. This means that you can retrieve commands from your opened Tinn-R command file from within the R console itself. For example, position the cursor on the first line of the file. Press hotkey F2 (as defined above for 'Send: line'). R console should now have the focus, with the zap() command shown in red. Now press hotkey F2 again and notice what happens. Press it again, and again, until the final command is retrieved. When all commands have been retrieved the focus should return back to Tinn-R. You can also control the behaviour of Tinn-R regarding keeping focus after sending (or retrieving) commands by clicking Options from the menu bar and selecting 'Return focus after sending to R'. This is a toggle button, being either OFF or ON. Selecting it again will turn it OFF. If turned ON, pressing the hotkeys will send the command(s) to R and then return focus back to Tinn-R.
There are many other features of Tinn-R that are not mentioned in this handout. Users are advised to learn and discover more features for themselves by reading the online help files, which are available in four languages: English, French, Portuguese and Spanish.
Please note that the 'send' method in Tinn-R uses Windows advanced features which may be affected by hotkey functions running concurrently from other software applications. If you encounter these problems, either quit R and Tinn-R and restart both or close the other interfering applications and try again. In the worst case, you may need to reboot your computer.
Using the source function in the R console is more reliable but requires tidiness of the command file, that is, it must be free of errors. If there are any syntax errors, for example, unmatched brackets, the file will not be accepted. R will terminate execution and report the line number of the first offending command. If this occurs simply return to the source command file and edit the erroneous command, save the file and source it again from R.
If there are no syntax errors in the command file, but R still reports an error when the file is sourced, the reason may be due to another type of error. For example, you may have specified an object that R cannot find, or a function that R does not recognize. The error will be reported as if it was typed at the R console, and no line number is given. To fix this particular type of error you must manually search the command file for the offending object using the search facility (<Ctrl> + F or F3 function key). Make the appropriate correction, save the command file and source the file again from R.
Tinn-R version 184.108.40.206 (June, 2010)
From version 220.127.116.11 and up the setting of the hotkeys has been changed from earlier versions. Four extra R packages are required for communication between R and Tinn-R to be successful. These packages are "TinnR", "Hmisc", "R2HTML" and "svSocket", all of which can be downloaded from the CRAN website. After successful installation (note that Windows Vista users must Run R as Administrators to install new packages), you will then need to open Tinn-R program and modify the "RProfile.site" file (again,
Tinn-R will then automatically update the file with the necessary commands. If R is running, you will be asked to close the R program and restart. Answer "Yes" to close the R program and restart. Answer "No" to return to Tinn-R. In either case, you should close the "RProfile.site" file that was just modified and then proceed to define your hotkeys.
To define the hotkeys, select "R" from the menu bar and choose "Hotkeys (operational system)" form the shortcut list. A small window will appear as shown below.
You may create your own hotkeys using any key sequence by selecting the function from the list (Send file, Send selection, Send line, etc.) using the mouse to click once and then clicking in the Set (hotkey) text area. To define the function keys (F1, F2, F5, F6 etc.) as your hotkeys, depress the desired function key and click the "Add" button at the bottom of the window.