R Commander

Description

Start the R Commander GUI (graphical user interface)

Usage

Commander()

Details

Getting Started

The default R Commander interface consists of (from top to bottom) a menu bar, a toolbar, a script window, an output window, and a messages window.

Commands to read, write, transform, and analyze data are entered using the menus in the menu bar at the top of the Commander window. Most menu items lead to dialog boxes requesting further specification. I suggest that you explore the menus to see what is available.

Below the menu bar is a toolbar with (from left to right) an information field displaying the name of the active data set; buttons for editing and displaying the active data set; and an information field showing the active statistical model. There is also a Submit button for re-executing commands in the script window. The information fields for the active data set and active model are actually buttons that can be used to select the active data set and model from among, respectively, data frames or suitable model objects in memory.

Almost all commands require an active data set. When the Commander starts, there is no active data set, as indicated in the data set information field. A data set becomes the active data set when it is read into memory from an R package or imported from a text file, SPSS data set, Minitab data set, STATA data set, or an Excel, Access, or dBase data set. In addition, the active data set can be selected from among R data frames resident in memory. You can therefore switch among data sets during a session.

By default, commands are logged to the script window (the initially empty text window immediately below the toolbar), and commands and output appear in the output window (the initially empty text window below the script window). To alter these and other defaults, see the information below on configuration.

Some Rcmdr dialogs (those in the Statistics -> Fit models menu) produce linear, generalized linear, or other models. When a model is fit, it becomes the active model, as indicated in the information field in the R Commander toolbar. Items in the Models menu apply to the active model. Initially, there is no active model. If there are several models in memory, you can select the active model from among them.

If command logging in turned on, R commands that are generated from the menus and dialog boxes are entered into the script window in the Commander. You can edit these commands in the normal manner and can also type new commands into the script window. Individual commands can be continued over more than one line, the several lines of a multi-line command must be submitted simultaneously. (It is not necessary, as in earlier versions of the R Commander, to begin continuation lines with white space.) The contents of the script window can be saved during or at the end of the session, and a saved script can be loaded into the script window. The contents of the output window can also be edited or saved to a text file. Finally, editing operations also work in the messages window.

To re-execute a command or set of commands, select the lines to be executed using the mouse and press the Submit button at the right of the toolbar (or Control-R, for "run", or Control-Tab). If no text is selected, the Submit button (or Control-R or Control-Tab) submits the line containing the text-insertion cursor. Note that an error will be generated if the submitted command or commands are incomplete.

Pressing Control-F brings up a find-text dialog box (which can also be accessed via Edit -> Find) to search for text in the script, output, or messages window. Edit functions such as search are performed in the script window unless you first click in the output or messages window to make it the active window.

Pressing Control-S will save the script or output window.

Pressing Control-A selects all of the text in the script, output, or messages window.

In addition, the following Control-key combinations work in the script, output, and messages windows: Control-X, cut; Control-C, copy; Control-V, insert; Control-Z or Alt-Backspace, undo; and Control-W, redo.

Right-clicking the mouse (clicking button 3 on a three-button mouse, or Control-left-clicking) in the script, output, or message window brings up a "context" menu with the Edit-menu items, plus (in the script window) a Submit item.

When you execute commands from the Commander window, you must ensure that the sequence of commands is logical. For example, it makes no sense to fit a statistical model to a data set that has not been read into memory.

Pressing a letter key (e.g., "a") in a list box will scroll the list box to bring the next entry starting with that letter to the top of the box.

You can cancel an R Commander dialog box by pressing the Esc key.

Exit from the Commander via the File -> Exit menu or by closing the Commander window.

Customization and Configuration

The preferred way of customizing the R Commander is to write a plug-in package: see help("Plugins").

Alternatively, configuration files reside in the etc subdirectory of the package, or in the locations given by the etc and etcMenus options (see below).

The Rcmdr menus can be customized by editing the file Rcmdr-menus.txt.

You can add R code to the package, e.g., for creating additional dialogs, by placing files with file type .R in the etc directory, also editing Rcmdr-menus.txt to provide additional menus, sub-menus, or menu-items. Alternatively, you can edit the source package and recompile it.

To reiterate, however, the preferred procedure is to write an R Commander plug-in package.

A number of functions are provided to assist in writing dialogs, and Rcmdr state information is stored in a separate environment. See help("Rcmdr.Utilities") and the manual supplied in the doc directory of the Rcmdr package for more information.

In addition, several features are controlled by run-time options, set via the options("Rcmdr") command. These options should be set before the package is loaded. If the options are unset, which is the usual situation, defaults are used. Specify options as a list of name=value pairs. You can set none, one, several, or all options. The available options are as follows:

ask.to.exit

if TRUE (the default), then the user is asked whether he or she wants to exit the Rcmdr; if this option is set to FALSE, then the subsequent option is also set to FALSE.

ask.on.exit

if TRUE (the default), then the user is asked whether to save the script file and the output file when the Rcmdr exits.

attach.data.set

if TRUE (the default is FALSE), the active data set is attached to the search path.

check.packages

if TRUE (the default), on start-up, the presence of all of the Rcmdr recommended packages will be checked, and if any are absent, the Rcmdr will offer to install them.

command.text.color

Color for commands in the output window; the default is "red".

console.output

If TRUE, output is directed to the R Console, and the R Commander output window is not displayed. The default is FALSE, unless the R Commander is running under RStudio, in which case the default is TRUE.

crisp.dialogs

If TRUE, dialogs should appear on the screen fully drawn, rather than built up widget by widget. Prior to R 2.6.1, this option only works on the Windows version of R, but should in any event be harmless. The default is TRUE. If you encounter stability problems, try setting this option to FALSE.

default.contrasts

Serves the same function as the general contrasts option; the default is
c("contr.Treatment", "contr.poly"). When the Commander exits, the contrasts option is returned to its pre-existing value. Note that contr.Treatment is from the car package.

default.font

The default font for GUI elements such as menus and text labels, in the form of a Tk font specification, given in a character string. For example, "-family Helvetica -size 12" specifies a 12-point Helvetica font. If specified, this value takes precedence over the default font size (below). Absent a compelling reason for changing the font, it is generally more convenient simply to change the default font size.

default.font.size

The size, in points, of the default font. The default is 10. To set the font size for R input and output, see the log.font.size option. It is recommended that Windows users set the Rcmdr scale factor option to control font size.

retain.selections

If TRUE (the default), dialogs remember their previous state, where appropriate, as long as the data set isn't changed; some dialogs, e.g., for probabilities, retain selections even when the data set chanages.

double.click

Set to TRUE if you want a double-click of the left mouse button to press the default button in all dialogs. The default is FALSE.

error.text.color

Color for error messages; the default is "red".

etc

Set to the path of the directory containing the Rcmdr configuration files; defaults to the etc subdirectory of the installed Rcmdr package.

grab.focus

Set to TRUE for the current Tk window to "grab" the focus — that is, to prevent the focus from being changed to another Tk window. On some systems, grabbing the focus in this manner apparently causes problems. The default is TRUE. If you experience focus problems, try setting this option to FALSE.

iconify.commander

If TRUE, the Commander window is minimized on startup; the default is FALSE.

length.output.stack

The R Commander maintains a list of output objects, by default including the last several outputs; the default length of the output stack is 10. popOutput() “pops” (i.e., returns and removes) the first entry of the output stack. Note that, as a stack, the queue is LIFO (“last in, first out”).

length.command.stack

The R Commander also maintains a list of commands that is managed similarly; the default length of this stack is also 10.

log.commands

If TRUE (the default), commands are echoed to the script window; if FALSE, the script window is not displayed.

log.font.size

The font size, in points, to be used in the script window, in the output window, in recode dialogs, and in compute expressions — that is, where a monospaced font is used. The default is 10. It is recommended that Windows users set the Rcmdr scale factor option to control font size.

log.height

The height of the script window, in lines. The default is 10. Setting log.height to 0 has the same effect as setting log.commands to FALSE.

log.text.color

Color for text in the script window; the default is "black".

log.width

The width of the script and output windows, in characters. The default is 80.

messages.height

The height of the messages window, in lines. The default is 3.

multiple.select.mode

Affects the way multiple variables are selected in variable-list boxes. If set to "extended" (the default), left-clicking on a variable selects it and deselects any other variables that are selected; Control-left-click toggles the selection (and may be used to select additional variables); Shift-left-click extends the selection. This is the standard Windows convention. If set to "multiple", left-clicking toggles the selection of a variable and may be used to select more than one variable. This is the behaviour in the Rcmdr prior to version 1.9-10.

number.messages

If TRUE, the default, messages in the messages window are numbered.

output.height

The height of the output window, in lines. The default is twice the height of the script window, or 20 if the script window is suppressed. Setting output.height to 0 has the same effect as setting console.output to TRUE.

output.text.color

Color for output in the output window; the default is "blue".

placement

Placement of the R Commander window, in pixels; the default is "-40+20", which puts the window near the upper-right corner of the screen.

plugins

A character vector giving the names of Rcmdr plug-in packages to load when the Commander starts up. Plug-in packages can also be loaded from the Tools -> Load Rcmdr plug-in(s) menu. See Plugins.

prefixes

A four-item character vector to specify the prefixes used when output is directed to the R console; the default is c("Rcmdr> ", "Rcmdr+ ", "RcmdrMsg: ", "RcmdrMsg+ ").

suppress.menus

if TRUE, the Commander menu bar and tool bar are suppressed, allowing another program (such as Excel) to take over these functions. The default (of course) is FALSE.

suppress.X11.warnings

On (some?) Linux and Mac OS X systems, multiple X11 warnings are generated by Rcmdr commands after a graphics-device window has been opened. Set this option to TRUE (the default when running interactively under X11) to suppress reporting of these warnings. An undesirable side effect is that then all warnings and error messages are intercepted by the Rcmdr, even those for commands entered at the R command prompt. Messages produced by such commands will be printed in the Commander Messages window after the next Rcmdr-generated command. Some X11 warnings may be printed when you exit from the Commander.

retain.messages

If TRUE (the default), the contents of the message window are not erased between messages. In any event, a "NOTE" message will not erase a preceding "WARNING" or "ERROR".

RExcelSupport

If TRUE (the default is FALSE), menus and output are handled by Excel.

scale.factor

A scaling factor to be applied to all Tk elements, such as fonts. This works well only in Windows. The default is NULL.

showData.threshold

If the number of variables in the active data set exceeds this value (default, 100), then View() rather than showData() is used to display the data set. The reason for the option is that showData() is very slow when the number of variables is large; setting the threshold to 0 suppresses the use of showData altogether.

show.edit.button

Set to TRUE (the default) if you want an Edit button in the Commander window, permitting you to edit the active data set. Windows users may wish to set this option to FALSE to suppress the Edit button because changing variable names in the data editor can cause R to crash (though I believe that this problem as been solved).

sort.names

Set to TRUE (the default) if you want variable names to be sorted alphabetically in variable lists.

tkwait

This option addresses a problem that, to my knowledge, is rare, and may occur on some non-Windows systems. If the Commander causes R to hang, then set the tkwait option to TRUE; otherwise set the option to FALSE or ignore it. An undesirable side effect of setting the tkwait option to TRUE is that the R session command prompt is suppressed until the Commander exits. One can still enter commands via the script window, however. In particular, there is no reason to use this option under Windows, and it should not be used with the Windows R GUI with buffered output when output is directed to the R console.

use.rgl

If TRUE (the default), the rgl package will be loaded if it is present in an accessible library; if FALSE, the rgl package will be ignored even if it is available. The rgl package can sometimes cause problems when running R under X11.

variable.list.height

the number of items (typically variables) to display in list boxes; longer lists may be viewed by scrolling. The default is 4.

variable.list.width

a two-item vector controlling the width of list boxes, in characters, giving the minimum and maximum width to display; the default is c(20, Inf). If the widest item name falls in this range, then its number of characters determines the width of the box. Note: This specification works only approximately.

warning.text.color

Color for warning messages; the default is "darkgreen".

Some options can also be set via the File -> Options menu, which will restart the Commander after options are set.

If you want always to launch the R Commander when R starts up, you can include the following code in one of R's start-up files (e.g., in the Rprofile.site file in R's etc subdirectory):

local({
old <- getOption("defaultPackages")
options(defaultPackages = c(old, "Rcmdr"))
})

Warning

The R Commander Script window does not provide a true console to R, and may have certain limitations. I don't recommend using the R Commander for serious programming or for data analysis that relies primarily on scripts — use a programming editor instead. If you encounter any problems with the Script window, however, I'd appreciate it if you brought them to my attention.

Known Problems

Occasionally, under Windows, after typing some text into a dialog box (e.g., a subsetting expression in the Subset Data Set dialog), buttons in the dialog (e.g., the OK button) will have no effect when they are pressed. Clicking anywhere inside or outside of the dialog box should restore the function of the buttons. As far as I have been able to ascertain, this is a problem with Tcl/Tk for Windows. I have not seen this behavior in some time and the problem may have been solved.

Note

This version may be compatible with SciViews: http://www.sciviews.org/SciViews-R; see Rcmdr.sciviews-specific. This version should be compatiable with the RExcel package, which can use the R Commander menus.

Under Windows, the Rcmdr package can be run under the Rgui in the SDI (single-document interface) mode, or under rterm.exe. You might experience problems running the Rcmdr under ESS with NTEmacs or XEmacs; under other R consoles; or under the Rgui in the MDI (multiple-document interface) mode.

Author(s)

John Fox jfox@mcmaster.ca

References

Fox, J. (2005) The R Commander: A Basic Statistics Graphical User Interface to R. Journal of Statistical Software, 14(9): 1–42.

Fox, J. (2007) Extending the R Commander by "plug in" packages. R News, 7(3): 46–52.

See Also

Plugins, Rcmdr.Utilities

Examples

    options(Rcmdr=list(log.font.size=12, default.contrasts=c("contr.Sum", "contr.poly")))