# Rcmdr.Utilities

0th

Percentile

##### Rcmdr Utility Functions

These functions support writing additions to the Rcmdr package. Additional R code can be placed in files with file type .R in the etc subdirectory of the package. Add menus, submenus, and menu items by editing the file Rcmdr-menus.txt in the same directory.

##### Usage
activateMenus()
activeDataSet(dsname, flushModel=TRUE, flushDialogMemory=TRUE)
ActiveDataSet(name)
activeDataSetP()
activeModel(model)
ActiveModel(name)
activeModelP()
aicP()
checkActiveDataSet()
checkActiveModel()
checkBoxes(window=top, frame, boxes, initialValues=NULL, labels, title=NULL)  # macro
checkClass(object, class, message=NULL)  # macro
checkFactors(n=1)
checkMethod(generic, object, message=NULL, default=FALSE, strict=FALSE,
reportError=TRUE)  # macro
checkNumeric(n=1)
checkReplace(name, type=gettextRcmdr("Variable"))
checkTwoLevelFactors(n=1)
checkVariables(n=1)
closeDialog(window, release=TRUE)  # macro
CommanderWindow()
dataSetsP(n=1)
defmacro(..., expr)
dialogSuffix(window=top, onOK=onOK, onCancel=onCancel, rows=1, columns=1,
focus=top, bindReturn=TRUE,
preventGrabFocus=FALSE, preventDoubleClick=FALSE, preventCrisp=FALSE)  # macro
doItAndPrint(command, log=TRUE)
errorCondition(window=top, recall=NULL, message, model=FALSE)  # macro
exists.method(generic, object, default=TRUE, strict=FALSE)
Factors(names)
factorsP(n=1)
formulaFields(model, hasLhs=TRUE, glm=FALSE)
flushDialogMemory(what)
gassign(x, value)
getDialog(dialog, defaults=NULL)
## S3 method for class 'listbox':
getFrame(object)
## S3 method for class 'listbox':
getSelection(object)
getRcmdr(x, mode="any")
gettextRcmdr(...)
glmP()
GrabFocus(value)
groupsBox(recall=NULL, label=gettextRcmdr("Plot by:"),
initialLabel=gettextRcmdr("Plot by groups"),
plotLinesByGroup=FALSE, positionLegend=FALSE,
plotLinesByGroupsText=gettextRcmdr("Plot lines by group"),
initialGroup=NULL, initialLinesByGroup=1)  # macro
groupsLabel(frame=top, groupsBox=groupsBox, columnspan=1, initialText=NULL)  # macro
hclustSolutionsP()
initializeDialog(window=top, title="", offset=10, preventCrisp=FALSE)  # macro
is.valid.name(x)
justDoIt(command)
Library(package, pos=4)
listAllModels(envir=.GlobalEnv, ...)
listAOVModels(envir=.GlobalEnv, ...)
listDataSets(envir=.GlobalEnv, ...)
listFactors(dataSet=ActiveDataSet())
listGeneralizedLinearModels(envir=.GlobalEnv, ...)
listLinearModels(envir=.GlobalEnv, ...)
listMultinomialLogitModels(envir=.GlobalEnv, ...)
listNumeric(dataSet=ActiveDataSet())
listProportionalOddsModels(envir=.GlobalEnv, ...)
listTwoLevelFactors(dataSet=ActiveDataSet())
listVariables(dataSet=ActiveDataSet())
lmP()
logger(command)
LogWindow()
MacOSXP()
Message(message, type=c("note", "error", "warning"))
MessagesWindow()
modelFormula(frame=top, hasLhs=TRUE)  # macro
modelsP(n=1)
multinomP()
Numeric(names)
numericP(n=1)
OKCancelHelp(window=top, helpSubject=NULL, model=FALSE, reset=NULL)  # macro
OutputWindow()
packageAvailable(name)
polrP()
popCommand()
popOutput()
putDialog(dialog, values=NULL, resettable=TRUE)
putRcmdr(x, value)
initialValue=..values[1], labels,
title="", title.color="blue", right.buttons=TRUE, command=function(){})  # macro
RcmdrTclSet(name, value)
RcmdrTkmessageBox(message, icon=c("info", "question", "warning",
"error"), type=c("okcancel", "yesno", "ok"), default, title="")
RExcelSupported()
sortVarNames(x)
subOKCancelHelp(window=subdialog, helpSubject=NULL)  # macro
subsetBox(window = top, subset.expression = NULL, model = FALSE)  # macro
tclvalue(x)
trim.blanks(text)
TwoLevelFactors(names)
twoLevelFactorsP(n=1)
UpdateModelNumber(increment=1)
variableListBox(parentWindow, variableList=Variables(), bg="white",
selectmode="single", export="FALSE", initialSelection=NULL,
listHeight=getRcmdr("variable.list.height"), title)
Variables(names)
varPosn(variables, type=c("all", "factor", "numeric", "nonfactor", "twoLevelFactor"))

# the following function is exported for technical reasons,
# but is not meant to be called directly

commanderPosition()
##### Arguments
ask whether to save contents of script and output windows.
bg
background color.
bindReturn
if TRUE, the Return key is bound to the onOK function in the dialog.
boxes
vector of quoted names for check boxes, used to generate each box and its associated variable.
buttons
vector of quoted names for buttons in a set of related radio buttons.
class
quoted name of class.
columnspan
number of dialog-box columns to be spanned by frame.
command
a character string that evaluates to an R command or (in the case of radioButton) a function to be called when a button is pressed.
dataSet, dsname
the quoted name of a data frame in memory.
default
default button: if not specified, "ok" for "okcancel", "yes" for "yesno", and "ok" for "ok"; or look for a default method; for putDialog, a list of defaults for the dialog box if there are no stored previous values.
defaults
a list of named default values for options in a dialog if no previous selections are stored.
dialog
the quoted name of a dialog box under which previous selections are stored.
envir
the environment to be searched; should generally be left at the default.
export
export selection?
expr
expression constituting the body of the macro; typically a compound expression.
flushDialogMemory
remove saved values of dialog options so that getDialog returns NULL for all dialogs.
flushModel
set (or reset) the active model to NULL? Should normally be TRUE when the active data set is changed; an exception is when variables are simply added to, deleted from, or modified in the data set set.
focus
Tk window to get the focus.
frame
frame or quoted name for frame depending upon the function.
generic
quoted name of generic function.
glm
TRUE if the model is a glm object, FALSE otherwise.
groupsBox
listbox object for selecting groups variable.
initialText
initial text to display in the groups label; if NULL, "" will be displayed.
hasLhs
does the model formula have a left-hand side?
helpSubject
the quoted name of a help subject, to be called as help(helpSubject) when the dialog Help button is pressed.
icon
Message-box icon.
increment
increment to model number; -1 to set back after error.
initialGroup
quoted name of variable to define groups, set as initial selection in Groups variable list; NULL (the default) for no initial selection.
initialLinesByGroup
if 1, the lines-by-groups check box is initially checked; 0 to uncheck.
initialLabel
label for groups button before a selection is made.
initialSelection
index of item initially selected, 0-base indexing.
initialValue
for a set of related radio buttons.
initialValues
for a set of related check boxes.
label
label prefix for groups button after a selection is made.
labels
a vector of character strings to label a set of radio buttons or check boxes.
listHeight
Maximum number of elements displayed simultaneously in list box.
if TRUE, plug-in packages that are loaded are included in the vector of names returned.
log
echo command to the log window, as well as executing it and printing its output.
message
error (or other) message.
mode
mode of object to retrieve.
model
the name of a model, as a character string, or a model object, or TRUE or FALSE, depending upon the function.
name
quoted name.
names
optional names to be stored.
n
number of items to check for.
object
an object (depends on context).
offset
in pixels, from top-left of Commander window.
onOK
function to execute when the OK button is pressed.
onCancel
function to execute when the Cancel button or Esc key is pressed.
package
quoted name of package to load.
plotLinesByGroup
include a check box for plotting lines by group?
plotLinesByGroupsText
the label for the plot-lines-by-group check box.
pos
position on search path at which to load package; default is 4.
positionLegend
include a check box for a legend?
preventGrabFocus
prevent the dialog box from grabbing the focus.
preventDoubleClick
prevent double-clicking from pressing the OK button, even when the double.click option is set; necessary for statistical modelling dialogs, which use double-clicking to build the model formula.
preventCrisp
prevent call to tclServiceMode, which (rarely) causes problems with some dialogs.
recall
function to call after error --- usually the function that initiates the dialog.
release
release the focus if the grab.focus option has been set.
reset
quoted name of dialog function, to be invoked with all defaults by Reset button.
resettable
should dialog state be reset when the data set changes? The default is code{TRUE}.
reportError
if TRUE, report an error message.
right.buttons
radio button placed to right of button-labels; defaults to TRUE.
rows, columns
numbers of rows and columns of widgets in the dialog box.
selectmode
"single" or "multiple".
strict
if TRUE, only use first element of class vector.
subset.expression
a quoted expression to subset the data set.
text
a text string.
title
Window or dialog-box-element title.
title.color
color for title above radio buttons; defaults to "blue".
type
quoted type of object to check; used to generate check-replace dialog box; or type of message to print in Message window. For varPosn, type of variable list.
value
an object to be stored or assigned.
values
vector of quoted values associated with radio buttons or check boxes; for putDialog, a list of current selections to be stored in support of dialog memory.
variableList
a vector of variable names.
variables
a vector of one or more variable names.
what
optional character vector of one or more dialog names for which the memory is to be flushed; if not specified, all dialog memory will be flushed.
window, parentWindow
a Tk window.
x
an R object name, as a character string, or a tcl variable or object, or a vector of variable names to be sorted.
...
For gettextRcmdr, text string or vector of text strings to translate; for defmacro, arguments for the macro; otherwise disregard.
##### Details

There are several groups of functions exported by the Rcmdr package and documented briefly here. To see how these functions work, it is simplest to examine the dialog-generating functions in the Rcmdr package. Executing and logging commands: The functions doItAndPrint, justDoIt, and logger control the execution, logging, and printing of commands generated by menus and dialogs. logger(command) adds command to the log/script window and to the output window. justDoIt(command) causes command to be executed. doItAndPrint(command) does both of these operations, and also prints the output produced by the command. The R Commander maintains a list of output objects, by default including the last 10 outputs. 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''). There is also a stack of commands, which is accessed similarly by popCommand(). Ocassionally, it's necessary to assign an object directly in the global environment, and this can be done with the gassign function. Checking for errors: The function is.valid.name checks whether a character string specifies a valid name for an R object. The functions checkActiveDataSet, checkActiveModel, checkFactors, checkNumeric, checkTwoLevelFactors, and checkVariables check for the existence of objects and write an error message to the log if they are absent (or insufficiently numerous, in the case of different kinds of variables). The function checkReplace opens a dialog to query whether an existing object should be replaced. The function checkMethod, checks whether a method exists for a particular generic that is appropriate for a particular object. The function checkClass checks whether an object is of a specific class. Both of these functions write error messages to the log if the condition fails. The function errorCondition reports an error to the user and (optionally) re-starts a dialog. Information: Several functions return vectors of object names: listAllModels, listAOVModels, listDataSets, listGeneralizedLinearModels, listFactors, listLinearModels, listMultinomialLogitModels, listNumeric, listProportionalOddsModels, listTwoLevelFactors, listVariables. The functions activeDataSet and activeModel respectively report or set the active data set and model. The function packageAvailable reports whether the named package is available to be loaded (or has possibly already been loaded). The function exists.method checks whether a method exists for a particular generic that is appropriate for a particular object, and returns TRUE or FALSE. Building dialog boxes: Several functions simplify the process of constructing Tk dialogs: initializing a dialog box, initializeDialog, and completing the definition of a dialog box, dialogSuffix; a set of check boxes, checkBoxes; a set of radio buttons, radioButtons; a list box with associated scrollbars and state variable, variableListBox (and the associated functions getFrame and getSelection); a button and subdialog for selecting a "grouping" variable, groupsBox; displaying the currently defined groups in a dialog, groupsLabel; a dialog-box structure for entering a model formula, modelFormula; a text box for entering a subsetting expression, subsetBox; OK, Cancel, and Help buttons for dialogs, OKCancelHelp, and subdialogs, subOKCancelHelp. The functions putDialog, getDialog, and varPosn support dialog-box memory---i.e., retaining selections across invocations of a dialog. Themed'' Tk widgets: Tk 8.5 introduced so-called themed'' widgets, which look better than the traditional Tk widgets. Several functions, contributed by Brian Ripley, are written to access the new widgets by switching automatically between the new and old widget sets depending upon the availability of the former: buttonRcmdr, to access either ttkbutton or tkbutton; labelRcmdr, to access either ttklabel or tklabel; ttkentry, to access either ttkentry or tkentry; ttkframe, to access either ttkframe or tkframe; ttkradiobutton, to access either ttkradiobutton or tkradiobutton; and ttkscrollbar, to access either ttkscrollbar or tkscrollbar. Note that the last four functions mask functions of the same names in the tcltk package. Predicate' functions: A number of functions of the form nameP are predicate' functions, which return TRUE or FALSE depending upon whether some condition obtains. For example, lmP() returns TRUE if there is an active model that is a linear model; and factorsP(2) returns TRUE if there are at least two factors in the active data set. Translating text: The gettextRcmdr function simply passes its argument(s) to gettext, adding the argument domain="R-Rcmdr". Miscellaneous: The function trim.blanks removes spaces from the beginning and end of a character string. The function installPlugin installs an Rcmdr plug-in from a ZIP file or directory; this function may be used to create self-installing plug-ins in the form of packages. The function nobs returns the number of observations on which a statistical model is based. The function formulaFields returns information about the left-hand side, right-hand side, data, subject, and (for GLMs) family and link, of a model object. The function sortVarNames sorts variable names, including those containing numerals, into a more "natural" order than does the standard sort function. The function Library may be used to load packages; it checks whether a package is already loaded, and if not by default puts it in position 4 on the search path. The function RExcelSupported is used for the RExcel interface. Some of these functions, marked # macro} under \emph{Usage}, are "macro-like" in their behaviour, in that they execute in the environment from which they are called. These were defined with an adaptation (used with permission) of Thomas Lumley's defmacro function, described in Lumley (2001). T. Lumley (2001) Programmer's niche: Macros in R. R News, 1(3), 11--13. [object Object] misc

##### Aliases
• Rcmdr.Utilities
• activeDataSet
• ActiveDataSet
• activeDataSetP
• activeModel
• ActiveModel
• activeModelP
• aicP
• checkActiveDataSet
• checkActiveModel
• checkBoxes
• checkClass
• checkFactors
• checkMethod
• checkNumeric
• checkReplace
• checkTwoLevelFactors
• checkVariables
• closeCommander
• closeDialog
• commanderPosition
• CommanderWindow
• dataSetsP
• defmacro
• dialogSuffix
• doItAndPrint
• errorCondition
• exists.method
• Factors
• factorsP
• formulaFields
• flushDialogMemory
• gassign
• getDialog
• getFrame
• getFrame.listbox
• getRcmdr
• getSelection
• getSelection.listbox
• gettextRcmdr
• glmP
• GrabFocus
• groupsBox
• groupsLabel
• hclustSolutionsP
• initializeDialog
• is.valid.name
• justDoIt
• Library
• listAllModels
• listAOVModels
• listDataSets
• listGeneralizedLinearModels
• listFactors
• listLinearModels
• listMultinomialLogitModels
• listNumeric
• listPlugins
• listProportionalOddsModels
• listTwoLevelFactors
• listVariables
• lmP
• logger
• LogWindow
• MacOSXP
• Message
• MessagesWindow
• modelFormula
• modelsP
• multinomP
• Numeric
• numericP
• OKCancelHelp
• OutputWindow
• packageAvailable
• polrP
• popCommand
• popOutput
• putDialog
• putRcmdr
• RcmdrTclSet
• RcmdrTkmessageBox
• RExcelSupported
• sortVarNames
• subOKCancelHelp
• subsetBox
• tclvalue
• trim.blanks
• TwoLevelFactors
• twoLevelFactorsP
• UpdateModelNumber
• variableListBox
• Variables
• varPosn
• buttonRcmdr
• labelRcmdr
• ttkentry
• ttkframe