Rcmdr.Utilities {Rcmdr}R Documentation

Rcmdr Utility Functions

Description

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)
ActiveDataSet(name)
activeDataSetP()
activeModel(model)
ActiveModel(name)
activeModelP()
checkActiveDataSet()
checkActiveModel()
checkBoxes(window=top, frame, boxes, initialValues=NULL, labels)  # 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()
dialogSuffix(window=top, onOK=onOK, 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()
## 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"))  # macro
groupsLabel(frame=top, groupsBox=groupsBox, columnspan=1)  # macro
hclustSolutionsP()
initializeDialog(window=top, title="", offset=10, preventCrisp=FALSE)  # macro
is.valid.name(x)
justDoIt(command)
listAllModels(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()
Message(message, type=c("note", "error", "warning"))
MessagesWindow()
modelFormula(frame=top, hasLhs=TRUE)  # macro
modelsP()
Numeric(names)
numericP()
OKCancelHelp(window=top, helpSubject=NULL, model=FALSE)  # macro
OutputWindow()
packageAvailable(name)
putRcmdr(x, value)
radioButtons(window=top, name, buttons, values=NULL, initialValue=..values[1], 
    labels, title)  # macro
RcmdrTclSet(name, value)
RcmdrTkmessageBox(message, icon=c("info", "question", "warning",
    "error"), type=c("okcancel", "yesno", "ok"), default)
subOKCancelHelp(window=subdialog, helpSubject=NULL)  # macro
subsetBox(window=top, model=FALSE)  # macro
trim.blanks(text)
TwoLevelFactors(names)
twoLevelFactorsP()
UpdateModelNumber(increment=1)
variableListBox(parentWindow, variableList=Variables(), bg="white",
    selectmode="single", export="FALSE", initialSelection=NULL, 
    listHeight = 4, title)
Variables(names)

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

commanderPosition()

Arguments

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.
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.
envir the environment to be searched; should generally be left at the default.
export export selection?
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.
groupsBox listbox object for selecting groups variable.
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.
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.
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 TRUE or FALSE, depending upon the function.
name quoted name.
names optional names to be stored.
n number of variables 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.
plotLinesByGroup include a check box for plotting lines by group?
plotLinesByGroupsText the label for the plot-lines-by-group check box.
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.
reportError if TRUE, report an error message.
rows, columns numbers of rows and columns of widgets in the dialog box.
values vector of quoted values associated with radio buttons or check boxes.
selectmode "single" or "multiple".
strict if TRUE, only use first element of class vector.
text a text string.
title Window or dialog-box-element title.
type quoted type of object to check; used to generate check-replace dialog box; or type of message to print in Message window.
value an object to be stored.
variableList a vector of variable names.
window, parentWindow a Tk window.
x an R object name, as a character string.
... For gettextRcmdr, text string or vector of text strings to translate; 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.

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

Translating text: The gettextRcmdr function simply passes its argument(s) to gettext, adding the argument domain="R-Rcmdr".

Miscelaneous: The function trim.blanks removes spaces from the beginning and end of a character string.

Some of these functions, marked # macro under 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).

Author(s)

John Fox jfox@mcmaster.ca

References

T. Lumley (2001) Programmer's niche: Macros in R. R News, 1(3), 11–13.


[Package Rcmdr version 1.1-6 Index]