Commander {Rcmdr} | R Documentation |
Start the R Commander GUI (graphical user interface)
Commander()
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, or STATA 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); commands and output appear in the output window (the initially empty text window below the script window); and the active data set is attached to the search path. 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, but each line after the first must be indented with one or more spaces or tabs. 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.
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"). If no text is selected, the Submit button (or Control-R) 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 window or the output window. Edit functions such as search are performed in the script window unless you first click in the output window to make it the active window.
Pressing Control-S will save the script or output window.
Right-clicking the mouse (clicking button 3 on a three-button mouse) in the script or output 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.
Exit from the Commander via the File -> Exit menu or by closing the Commander window.
Customization and Configuration
Configuration files reside in the etc
subdirectory of the package.
The Rcmdr
menus can be customized by editing the file Rcmdr-menus.txt
.
Some functions (e.g., hist
) that do not normally create visible printed output when executed
from the R Console command prompt will do so — unless prevented — when executed from the
Commander script window. Such output
can be suppressed by listing the names of these functions in the log-exceptions.txt
file.
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. A demo addition is provided in the file
BoxCox.demo
. To activate the demo, rename this file to BoxCox.R
,
and uncomment the corresponding menu line in Rcmdr-menus.txt
. Alternatively, you can edit
the source package and recompile it.
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:
attach.data.set
TRUE
(the default is FALSE
), the active data set is attached to the
search path.check.packages
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
"red"
.console.output
TRUE
, output is directed to the R Console, and the
R Commander output window is not displayed. The default is FALSE
.contrasts
contrasts
option; the default isc("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.crisp.dialogs
TRUE
, dialogs should appear on the screen fully drawn, rather than built up
widget by widget. This option should affect the Windows version of R only, but should in any event be harmless.
The default is TRUE
under Windows for R versions 2.1.1 and above, and FALSE
otherwise.
If you're working on Windows and encounter increased stability problems, trying setting this option to
FALSE
.default.font
default.font.size
"*helvetica-medium-r-normal-*-xx*"
, where xx
is the default font size. This option is only for non-Windows systems.double.click
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
"red"
.grab.focus
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
.load.at.startup
Rcmdr
package is loaded; the default is to load only the car
package. Other required packages will be loaded as needed. If it is available, the
car
package will be loaded at when the Commander starts in any event.log.commands
TRUE
(the default), commands are echoed to the script window;
if FALSE
, the script window is not displayed.log.font.size
log.height
log.height
to 0 has the same effect as setting log.commands
to FALSE
.log.text.color
"black"
.log.width
multiple.select.mode
"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.output.height
output.height
to 0 has the same effect as setting console.output
to TRUE
.output.text.color
"blue"
.placement
"-40+20"
, which puts the window near the upper-right corner of the screen.suppress.X11.warnings
TRUE
(the default when running
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
TRUE
(the default is code{FALSE}), 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".scale.factor
NULL
.showData.threshold
edit()
rather than showData()
is used to display the data set. A disadvantage is that control doesn't
return to the Commander until the edit window is closed. 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
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
TRUE
(the default) if you want variable names to be sorted
alphabetically in variable lists.tkwait
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
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.warning.text.color
"darkgreen"
.Many options can also be set via the File -> Options menu, which will restart the Commander after options are set.
This version is compatible with SciViews, which currently runs only under Windows systems:
http://www.sciviews.org/SciViews-R; see Rcmdr.sciviews-specific
.
Under Windows, the Rcmdr
package can also be run under the Rgui in SDI (single-document
interface) mode, or under rterm.exe
; you might experience problems running the Rcmdr
under
ESS
withNTEmacs or XEmacs.
John Fox jfox@mcmaster.ca
options(Rcmdr=list(log.font.size=12, contrasts=c("contr.Sum", "contr.poly")))