R for Macintosh FAQ/DOC

Version for `R 1.4.0`

S. M. Iacus

Changes and bug fixing specific to this version:

Added the Preferences pane. The settings in .Renviron are now superseeded by the prefences settings .Renviron can be still used to simulate the Environment for the Sys.getenv() call.
Added the item "Link Packages Help" to the "Help" menu.
Fixed a bug that set the help menu items ghosted after having used them.
Some MRC Apple's Compiler specific fixing.
Fixed problems with current working directory in different points (.Rprofile, .Renviron, etc).
Solved the problem of line endings that are different from MacOS and OS X. Now text files generated under both systems are fine to R.
Makefiles and perl scripts have been fixed so that now R builds via MPW shell scripts and help files are generated as well.
A bug in the internal file viewer that suppressed the "_" symbols from the text has been fixed.
This version of R is slower at startup but faster than then previous release (by a factor of 10%) in calculations.
The initial window at startup has been suppressed in this release in the hope to provide am applescript analogous to pass initial arguments to R. Anyway this option was mostly disturbing R users then used by them.
The about box now reports informations on the current release of R
Added the zlib capability so now R can manage gzipped files and connections
Fixed some wrong links in html help files
Finally fixed copy and paste of graphic windows contents and saving of them onto files. For some reason the previous algorithm did not copy text characters under MacOS X.
Fixed a bug that appear when trying to reading files or directories on a different volume w.r.t. the current working directory of R.
Added two functions file.edit() and new.file(). The file.edit() function is similar to file.show() but let the user edit the opened file. It it the equivalent to the menu command "OPen File for Editing..." while new.file() is the equivalent to the "New Window" menu command with the difference that you can specify the name of the new file to edit. For more details see man pages.
Added three functions to manipulate a User menu in the R Console menubar. With add.menu.cmd(label,command) the user can add menu item "label" to which is associated an R command. Respectively with del.menu.cmd(label) and get.menu.cmd(label) the user can remove or get the command associated to the menu "label". See the help pages for details and examples.
Added three functions to manipulate a User menu in the R Console menubar. With del.usr.cmd() the whole user menu is removed. Respectively with del.num.cmd(menunum) and get.num.cmd(menunum) the user can remove or get the command associated to the menu numbered "menunum". See the help pages for details and examples.
Fixed some problems with windows naming (duplicates and so forth)
Windows (both text and graphic) now appears only after repositioning
lwd parameter in graphic functions re-implemented even if not yet perfectly working.
lty & lwd paramter now works for all the graphic call apart for Circle.
Fixed a bug in the function edit(). Now it behaves correctly. If you call it without parameters, the last temporary edited file will be shown. See man pages of edit(). Consequently it is now fixed the problem with the function fix().
Refresh of graphic windows fixed. One time only and the bottom part of the window is correctly redrawn.

rmac-FAQ.html

This is the ReadMe file of R for Macintosh Application.

We discuss here the following topics:

* NEWS
* THE GUI
* APPLE SCRIPT SUPPORT
* EXTERNAL EDITOR INTERACTION
* MEMORY
* SPECIFYING OPTIONS: the Preferences pane
* SPECIFYING ENVIRONMENT VARIABLES: the .Renviron file
* THE USER MENU
* R HELPERS
* SYSTEM REQUIREMENTS
* KNOWN BUGS
* SHORT FAQ (in the MAC-FAQ)
* REMERCIEMENTES

NEWS
There are several enanchements in this release. Most of them concern the user interface of R application but one of the most important novelty is that now
R runs both on MacOS and MacOS X using Carbon technology. This means that when you run R from MacOS X it run natively under the new System without calling the Classic Compatibility Module. The use of R under MacOS X takes lots of advantages starting from the new Aqua look.

As this version is based on the new Carbon technology some new bugs can appear that we were'nt able to found before releasing R officially.

Any feedback is then welcome at stefano.iacus@unimi.it

THE NEW GUI
Several menus are now present from this release. The structure of the menus is as follows with a brief description.

Menu Item Shortcut Brief description

Apple (or Application Menu under MacOS X)

About R Opens the R information dialog. Reports release informations.

Preferences (under OS X only, see the Config menu for pre X Systems) Opens the R Preferences pane

File

New Edit Window N Opens an empty editable window. You can usethis as an internal editor for R. If the current active window isa graphic device window than a new macintosh() device will be opened.

Edit Object E Is the equivalent of "edit(object)"

Source File O Opens a file and sources it. This is equivalent to "source(file)"

Open File For Editing Opens a file in an editable window.Useful when you want to modify an existing script and test it.

File Show F Open a file in a non editable window. This isthe equivalent of R command "show.file(file)"

Load Workspace File L If you want to load a wspace image otherthan ".RData"

Save Workspace As If you want to save an image file other the ".RData"

Page Setup Calls the printer driver page setup

Print P Print the text window (R Console etc) or the imagein the graphic device window. The image is rescaled to the page dimension of your printer.

Save S Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphic device window.

Save As... Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphicdevice window. This menu acts as a standard "Save As" menu so you have to specify each time the filename.

Close W Closes the current window. If it is the R Console window than it is interpreted as quitting R.

Quit Q This menu item is on the Application Menu under MacOS X

Edit

Undo Z

Cut X

Copy C If you use it on a graphic device window theimage is copied to the clipboard (see also knownbugs)

Paste V

Copy & Paste You copy some text and the resultis pasted into the R Console window. You use thiswhen you select a piece of R code of text windowand then you want to R to execute it. This is quite useful when you want to test part of your script of the examples of an help window

Clear

Select All A

Goto line Active only for editable windows. It moves thecursor to a certain line

Tools

Show Workspace It is equivalent to "ls()"

Clear Workspace It is equivalent to "rm(list=ls())"

Load Workspace Loads the ".RData" file; equivalent to load(".RData")

Save Workspace Save the workspace to ".RData"; equivalent to "save.image()"

Load History It is equivalent to "loadhistory()"

Save History It is equivalent to "savehistory()"

Show History It is equivalent to "history()"

Change Working Directory D Allows the user to change the workingdirectory by using a standard dialog

Show Working Directory It is equivalent to "getwd()"

Reset Working Directory It is equivalent to "setwd(R.home())"

Show Libraries It is equivalent to "library()"

Show DataSets It is equivalent to "data()"

Windows

R Console This menu contains by default only the "R Console" item and it is dynamically changed by appending/removing the names of any new/closed window

Config

Allow Interrupt It is equivalent to set the option "Interrupt=TRUE" in the .Renvironment config file but this can be changed at runtime. This menu is syncronized with the option you select in the Preference pane.

On Open Source It is equivalent to set the option "OnOpenSource=TRUE" in the .Renvironment config file but this can be changed at runtime. Useful to work with external editor such as Alpha. This menu is syncronized with the option you select in the Preference pane.

Preferences (under Mac OS only) Opens the R Preferences pane

Help

R Help ? It is equivalent to "help.start()"

Help On Topic Opens a dialog where the user can specify an item he or she wants to see. equivalent to "help(topic)" or "?topic"

Search Help On Opens a dialog where the user can specify an argument to have help on. It is equivalent to"help.search("topic")"

Run An Example Opens a dialog where the user can specify an item of which he or she wants to run anexample of. It is equivalent to "example(topic)".

Link Packages Help After installing a new package you need to link help files database.

About R windows.
Normally R opens windows to let 80 character/columns to be displayed. The size of the windows is calculated on the basis of the size of the font used.
For non fixed fonts the algorithm can fail so the window can result a bit larger or smaller then needed.
R windows are opened in cascade for each class (edit windows, file show windows and graphic windows). This functionality does not work on MacOS X yet.

APPLE SCRIPT SUPPORT
From release 1.3.1 R has partial support for AppleScripts. This means two things: you can run applescripts from inside R using the command applescript() (see the corresponing help) or you can ask R to run commands from and applescript. The directory "scripts" in the main R folder contains two examples of applescripts. What follows is an example of applescript that interacts with R.

set CommandLine to "R.Version()"
try
tell application "R"
activate
   with timeout of 90000 seconds
    cmd CommandLine
    cmd "Sys.getenv()"
   end timeout
end tell
end try

Where cmd is the applescript command in the R dictionary that is used to tell R to execute an R command in the R Console. The syntax is cmd <command string>, where command string have to be in quotes. Actually, the output of the command is not sent back to the application that is calling R but to the R Console.

EXTERNAL EDITOR INTERACTION
From release 7.4.1 of the famous Alpha editor, there is a (tcl) mode called S+/R.
When you open a file in Alpha with the extension ".s" or ".r" this new mode will be installed and you will in the Alpha menu bar the "S+/R" menu. Of this menu you can use "Process File" or "Process Selection" to interact with R. By default Alpha sends an “open” command to R and by default R opens a file in a non editable window (equivalent to the “File Show” menu). If you want R to source a file you should modify activate the option "OnOpenSource" that is set by default to "FALSE". You can change this at runtime running via the Config/OnOpenSource menu or accessing the Preferences pane. The latest version of Alpha can be found at http://alpha.olm.net

MEMORY
Under MacOS you should reserve a fixed amount of memory to each application. As R is just an application, you need to set this to a bigger amount of memory if for some reason R went out of memory. To do this, go to the Finder and select the R aplication icon. Then with CMD+I key obtain the Information for R. Select "Memory" and the fix the amount of memory you need. Under MacOS X, there is no need to reserve memory to R. R will use as much memory as it needs.

SPECIFYING OPTIONS: the Preferences pane
The Preferences pane allow you to configure a bit R GUI and behaviour. You can set the tab size in your edit windows, the font type and size of text windows and R Console as well as the colors of the text in R Console. You can also specify a particular font for the graphic device and the resolution of the graphic device. Finally you can specify if R should accept User breaks (CMD+. or Esc). If this option is enabled R is a bit slower. You can instruct R on what to do when a file is opened: source it or simply show in the internal viewer.

Take care that under MacOS R creates a file in the Preferences folder of you System Folder. If you switch to MacOS X than, this folder is no longer the default Preferences folder so you have either to move th "R preferences" file to "~user/Library/Preferences/" directory or reset the preferences. If you have different logins under OS X, remember that each user should set its own preferences.

SPECIFYING ENVIRONMENT VARIABLES: the .Renviron file
In this file you can specify some of options or environment variables. This is not standard for general MacOS/X applications but has been implemented for compatibility reasons. If you don't need to set environment variables you can ignore what is in this file.
The environment file is used by R application both to simulate the enviroment on a standard Unix or Windows system.
You can always use "Sys.getenv()" to see which variables are set to some values.
The .Renviron file looks like this: an option is a "Rkey" with its "keyvalue" that you can specify in new separate line as follows RKey=keyvalue. Consider that RKey=keyvalue and RKey = keyvalue are different, that means that blanks/spaces are significant. "RKey" and "keyvalue" are case sensitive. A symbol "#" at the beginning of a line means that this is a commented out line.
You can find more details on that in the .Renviron file itself.

THE NEW USER MENU
The user has now the ability to create a menu with several menuitems, up to 99, where to keep preferred R commands.
With the commands add.menu.cmd("label","R_command") the user adds a menuitem named "label" to the User menu. When the command is selected from the menu, R executes the command "Rcommand" associated to it. The User menu is created dynamically, so that user will never see it if he does not add any item to it.
Several functions to manipulate the user menu are previewed:

get.menu.cmd("label") returns the R Command associated to menu item "label" and the corresponding menu number

get.num.cmd(menunum) returns the R Command associated to menu item number "menunum" and the corresponding menu label

del.menu.cmd("label") removes the menu item "label" from the User menu

del.num.cmd(menunum) removes the menu item numbered "menunum" from the User menu

del.usr.cmd("label") removes the whole User's menu

add.menu.cmd("label","RCommand") adds a menu item to the User's menu, if any, with associated the R command "RCommand"

R HELPERS
* If you want to use an external editor we suggest you to use Alpha version 7.4.1 or newer that contains a S+/R mode. Alpha home page is
http://alpha.olm.net
* You also need MacZip to use the unzip feature of R. MacZip home page is
http://www.sitec.net/maczip

SYSTEM REQUIREMENTS

To run the R application you need at least 42MB of free memory for the application itself you work under MacOS but there is no limitations under MacOS X as virtual memory is always on.
You need the latest version of the CarbonLib library from Apple. At the time of this release, version 1.4 is the current non developer release. Normally it is included in System 9.2 and X.
Now R needs the f2cLib shared library to run. This library is distributed with R but in case you miss it you can found it here.
The minimum System version release is 8.6 (+ CarbonLib library).
You need the WasteLib library. This library is distributed with R binaries.
You need the zlibLib library. This library is distributed with R binaries.

KNOWN BUGS

In some situations R stops execution giving an error like this:

Error in plot.xy(xy.coords(x, y), type = type, pch = pch, col = col, bg = bg, :
negative length vectors are not allowed
To solve this problem you just need to resize the device window to a bigger size with your mouse and resubmit the graphic command in R.

For some reason MacZip does not intercat too much with R under MacOS X. Moreover MacZip has not yet been “carbonized” so when R calls it to uncompress items it also starts up Classic Environment. We suggest to uncompress the help and examples files directly by using Stuffit Expander that is part of the utilities provided with System X.
This version of R and Adobe ATM are incompatible. We are looking at the problem. The solution is that you should switch ATM off before running R. (Thanks to R. Gill for feedback on this bug)
Internet functionality is not available yet. We are working on this.
Mathematical expressions are not yet well spaced moreover, mathemathic symbols are not rotated.

SHORT FAQ (in the MAC-FAQ)

Q	How can I manage invisible files under MacOS X ?
A	Under Unix it is typical that invisible files are files starting with a "." (dot) in the filename. MacOS X conforms to this convention. So it could happen that your preferred editor doesn't allow you to open and or write files like .Rprofile or .Renviron under MacOS X (this is the case of BBedit as reported by one user). You have to options. Edit a file like "some_file" with your editor or R, and then go to the shell (that is the Term application) and change the name in ".some_file" using the command "mv some_file .some_file". The second option is to edit the file directory with a unix editor like "emacs". Again from the shell simply use "emacs .some_file", edit it and save it (ctrl+x, ctrl+s) then exit (ctrl+x, ctrl+c). You will no longer see this file from the shell unless you use commands like "ll".
Q	On exit: Why I can't save the workspace image via file dialog under MacOS X ?
A	As before, files starting with a dot, such as ".RData" cannot be managed directly via standard dialogs (you can see invisible files but you can't specify them as filenames !) To save the workspace image, you can either save it with a different name (e.g. "RData", but in this the workspace image will not be reloaded the next you start R), or you save it beofre quitting R: type "save.image()" from the R Console and then "q()" replying "n" when R asks for "Save workspace image? [y/n/c]:".
Q	How can I work on a separate directory for each of my projects?
A	Under Unix you usually create a directory, go into it and launch R. Under MacOS you can create a directory and put all the files that you need there. You then (or before) run R in its own directory and use the menu item "Tools->Change Working Directory" to change the current working directory to directory you have created. You can then work as you do in Unix. You can save/load workspace image to this directory, as well as the command history files. You can then reload these next time you work.
Q	How can I interrupt lengthy operations or output ?
A	You can now use the standard Macintosh control break sequence, that is you should press "Cmd option" and "." (dot). This will interrupt any R loops. The "Esc" key gives you the same result.
Q	How can I change memory settings for R ? (MacOS pre X only)
A	You cannot use the standard settings as on other platforms. You should assign memory to R from the Finder/Information dialog for R application. See Section "Memory" above.
Q	When I use to send R output to a file like "my_file", R seems to work on this file but I cannot find it. What happened ? (MacOS X only)
A	On MacOS X it is important to specify correctly the file names. If you want the file to be created in your current working directory you have to put a ":" before file name, such as ":myfile" otherwise the file will be created as "/my_file", i.e. in the root "/" directory. This is in particular important when you specify directories relative to your current working directory.

REMERCIEMENTS
I would like to thank among the others (only few I can remember due to my brain volatility...) some of the people who have contantly sent me feedback on this Macintosh port of R or simply suggetested me some possibile directions. So, merci, in random order, to P. Macdonald, P. Flint, R. Gill, K. Pflugshaupt, J. DeLeeuw, G. Sawitzki and half of the R-Core.

Last edited 2001 December 4th, Stefano M. Iacus stefano.iacus@unimi.it

Menu	Item	Shortcut	Brief description
Apple (or Application Menu under MacOS X)
	About R		Opens the R information dialog. Reports release informations.
	Preferences	(under OS X only, see the Config menu for pre X Systems)	Opens the R Preferences pane

File
	New Edit Window	N	Opens an empty editable window. You can usethis as an internal editor for R. If the current active window isa graphic device window than a new macintosh() device will be opened.
	Edit Object	E	Is the equivalent of "edit(object)"
	Source File	O	Opens a file and sources it. This is equivalent to "source(file)"
	Open File For Editing		Opens a file in an editable window.Useful when you want to modify an existing script and test it.
	File Show	F	Open a file in a non editable window. This isthe equivalent of R command "show.file(file)"
	Load Workspace File	L	If you want to load a wspace image otherthan ".RData"
	Save Workspace As		If you want to save an image file other the ".RData"
	Page Setup		Calls the printer driver page setup
	Print	P	Print the text window (R Console etc) or the imagein the graphic device window. The image is rescaled to the page dimension of your printer.
	Save	S	Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphic device window.
	Save As...		Save the window. This could be the content ofthe R Console i.e. your current R session any text window or the graphicdevice window. This menu acts as a standard "Save As" menu so you have to specify each time the filename.
	Close	W	Closes the current window. If it is the R Console window than it is interpreted as quitting R.
	Quit	Q	This menu item is on the Application Menu under MacOS X

Edit
	Undo	Z
	Cut	X
	Copy	C	If you use it on a graphic device window theimage is copied to the clipboard (see also knownbugs)
	Paste	V
	Copy & Paste		You copy some text and the resultis pasted into the R Console window. You use thiswhen you select a piece of R code of text windowand then you want to R to execute it. This is quite useful when you want to test part of your script of the examples of an help window
	Clear
	Select All	A
	Goto line		Active only for editable windows. It moves thecursor to a certain line

Tools
	Show Workspace		It is equivalent to "ls()"
	Clear Workspace		It is equivalent to "rm(list=ls())"
	Load Workspace		Loads the ".RData" file; equivalent to load(".RData")
	Save Workspace		Save the workspace to ".RData"; equivalent to "save.image()"
	Load History		It is equivalent to "loadhistory()"
	Save History		It is equivalent to "savehistory()"
	Show History		It is equivalent to "history()"
	Change Working Directory	D	Allows the user to change the workingdirectory by using a standard dialog
	Show Working Directory		It is equivalent to "getwd()"
	Reset Working Directory		It is equivalent to "setwd(R.home())"
	Show Libraries		It is equivalent to "library()"
	Show DataSets		It is equivalent to "data()"

Windows
	R Console		This menu contains by default only the "R Console" item and it is dynamically changed by appending/removing the names of any new/closed window

Config
	Allow Interrupt		It is equivalent to set the option "Interrupt=TRUE" in the .Renvironment config file but this can be changed at runtime. This menu is syncronized with the option you select in the Preference pane.
	On Open Source		It is equivalent to set the option "OnOpenSource=TRUE" in the .Renvironment config file but this can be changed at runtime. Useful to work with external editor such as Alpha. This menu is syncronized with the option you select in the Preference pane.
	Preferences	(under Mac OS only)	Opens the R Preferences pane
Help
	R Help	?	It is equivalent to "help.start()"
	Help On Topic		Opens a dialog where the user can specify an item he or she wants to see. equivalent to "help(topic)" or "?topic"
	Search Help On		Opens a dialog where the user can specify an argument to have help on. It is equivalent to"help.search("topic")"
	Run An Example		Opens a dialog where the user can specify an item of which he or she wants to run anexample of. It is equivalent to "example(topic)".
	Link Packages Help		After installing a new package you need to link help files database.

get.menu.cmd("label")	returns the R Command associated to menu item "label" and the corresponding menu number
get.num.cmd(menunum)	returns the R Command associated to menu item number "menunum" and the corresponding menu label
del.menu.cmd("label")	removes the menu item "label" from the User menu
del.num.cmd(menunum)	removes the menu item numbered "menunum" from the User menu
del.usr.cmd("label")	removes the whole User's menu
add.menu.cmd("label","RCommand")	adds a menu item to the User's menu, if any, with associated the R command "RCommand"

R for Macintosh FAQ/DOC

Version for R 1.4.0

Version for `R 1.4.0`