Commander               package:Rcmdr               R Documentation

_R _C_o_m_m_a_n_d_e_r

_D_e_s_c_r_i_p_t_i_o_n:

     Start the R Commander GUI (graphical user interface)

_U_s_a_g_e:

     Commander()

_D_e_t_a_i_l_s:

     *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); 
     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, 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.

     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 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.

     Pressing _Control-A_ selects all of the text in 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.

     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. 

     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, 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. 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:


     '_a_s_k._o_n._e_x_i_t' if 'TRUE' (the default), then the user is asked
          whether to save the script file and the output file when the
          'Rcmdr' exits.

     '_a_t_t_a_c_h._d_a_t_a._s_e_t' if 'TRUE' (the default is 'FALSE'), the active
          data set is attached to the search path.

     '_c_h_e_c_k._p_a_c_k_a_g_e_s' 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.

     '_c_o_m_m_a_n_d._t_e_x_t._c_o_l_o_r' Color for commands in the output window; the
          default is '"red"'.

     '_c_o_n_s_o_l_e._o_u_t_p_u_t' If 'TRUE', output is directed to the _R Console_,
          and the  _R Commander_ output window is not displayed. The
          default is 'FALSE'.

     '_c_o_n_t_r_a_s_t_s' 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.

     '_c_r_i_s_p._d_i_a_l_o_g_s' 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'.

     '_d_e_f_a_u_l_t._f_o_n_t' The default font, as an X11 font specification,
          given in a character string.  If specified, this value takes
          precedence over the default font size (below). This option is
          only for non-Windows systems.

     '_d_e_f_a_u_l_t._f_o_n_t._s_i_z_e' The size, in points, of the default font. The
          default is 10 for Windows systems and 12 for other systems
          Unless otherwise specified (see the previous item), the
          default font is '"*helvetica-medium-r-normal-*-xx*"', where
          'xx' is the default font size. This option is only for
          non-Windows systems.

     '_d_o_u_b_l_e._c_l_i_c_k' 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'.

     '_e_r_r_o_r._t_e_x_t._c_o_l_o_r' Color for error messages; the default is
          '"red"'.

     '_e_t_c' Set to the path of the directory containing the 'Rcmdr'
          configuration files; defaults to the 'etc' subdirectory of
          the installed 'Rcmdr' package.

     '_g_r_a_b._f_o_c_u_s' 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'.

     '_l_e_n_g_t_h._o_u_t_p_u_t._s_t_a_c_k' 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'').

     '_l_o_a_d._a_t._s_t_a_r_t_u_p' A character vector of names of packages to be
          loaded  when the '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.

     '_l_o_g._c_o_m_m_a_n_d_s' If 'TRUE' (the default), commands are echoed to the
          script window; if 'FALSE', the script window is not
          displayed.

     '_l_o_g._f_o_n_t._s_i_z_e' 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 for Windows systems and 12 for other
          systems.

     '_l_o_g._h_e_i_g_h_t' 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'.

     '_l_o_g._t_e_x_t._c_o_l_o_r' Color for text in the script window; the default
          is '"black"'.

     '_l_o_g._w_i_d_t_h' The width of the script and output windows, in
          characters. The default is 80.

     '_m_u_l_t_i_p_l_e._s_e_l_e_c_t._m_o_d_e' 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.

     '_o_u_t_p_u_t._h_e_i_g_h_t' 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'.

     '_o_u_t_p_u_t._t_e_x_t._c_o_l_o_r' Color for output in the output window; the
          default is '"blue"'.

     '_p_l_a_c_e_m_e_n_t' 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.

     '_p_l_u_g_i_n_s' 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.

     '_s_u_p_p_r_e_s_s._m_e_n_u_s' 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'.

     '_s_u_p_p_r_e_s_s._X_1_1._w_a_r_n_i_n_g_s' On (some?) Linux 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
          prior to R version 2.4.0) 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. This problem only applies to R versions before
          2.4.0, and the default value of the option is set
          accordingly.

     '_r_e_t_a_i_n._m_e_s_s_a_g_e_s' If 'TRUE' (the default is '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".

     '_R_E_x_c_e_l_S_u_p_p_o_r_t' If 'TRUE' (the default is 'FALSE'), menus and
          output are handled by Excel.

     '_s_c_a_l_e._f_a_c_t_o_r' A scaling factor to be applied to all Tk elements,
          such as fonts. This works well only in Windows. The default
          is 'NULL'.

     '_s_h_o_w_D_a_t_a._t_h_r_e_s_h_o_l_d' If the number of variables in the active data
          set exceeds this value (default, 100), then '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.

     '_s_h_o_w._e_d_i_t._b_u_t_t_o_n' 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).

     '_s_o_r_t._n_a_m_e_s' Set to 'TRUE' (the default) if you want variable
          names to be sorted alphabetically in variable lists.

     '_t_k_w_a_i_t' 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.

     '_u_s_e._r_g_l' 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.

     '_v_a_r_i_a_b_l_e._l_i_s_t._h_e_i_g_h_t' the number of variables to display in
          variable-list boxes; longer lists may be viewed by scrolling.
           The default is 4. 

     '_w_a_r_n_i_n_g._t_e_x_t._c_o_l_o_r' Color for warning messages; the default is
          '"darkgreen"'.

     Many 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"))
     })

     R Commander options can also be permanently set in the same
     manner. For more information about R initialization, see
     '?Startup'.

_W_a_r_n_i_n_g:

     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.

_K_n_o_w_n _P_r_o_b_l_e_m:

     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.

_N_o_t_e:

     This version may be compatible with SciViews, which currently runs
     only under Windows systems: <URL:
     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.

_A_u_t_h_o_r(_s):

     John Fox jfox@mcmaster.ca

_S_e_e _A_l_s_o:

     Plugins, Rcmdr.Utilities

_E_x_a_m_p_l_e_s:

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

