Rcmdr (version 2.4-0)

Rcmdr.Utilities: Rcmdr Utility Functions

Description

These functions support writing additions to the Rcmdr package, preferably by writing an Rcmdr plug-in package. Although it is not recommended, additional R code can also be placed in files with file type .R in the etc subdirectory of the Rcmdr package. In this case, you can 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()
anovaP()
beginRmdBlock()
beginRnwBlock()
checkActiveDataSet()
checkActiveModel()
checkBoxes(window=top, frame=stop("frame not supplied"), 
    boxes=stop("boxes not supplied"), 
    initialValues=NULL, labels=stop("labels not supplied"), 
    title=NULL, ttk=FALSE)  # 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)
closeCommander(ask=TRUE, ask.save=ask)
closeDialog(window, release=TRUE)  # macro
CommanderWindow()
data(..., list = character(), package = NULL, lib.loc = NULL, 
    verbose = getOption("verbose"), envir = .GlobalEnv)
dataSetsP(n=1)
defmacro(..., expr)
dialogSuffix(window=top, onOK=onOK, onCancel=onCancel, rows, columns, 
	focus=top, bindReturn=TRUE, 
    preventGrabFocus=FALSE, preventDoubleClick=FALSE, preventCrisp,
    use.tabs=FALSE, notebook=notebook, tabs=c("dataTab", "optionsTab"), 
    tab.names=c("Data", "Options"), grid.buttons=FALSE, resizable=FALSE,
    force.wait=FALSE)  # macro
doItAndPrint(command, log=TRUE, rmd=log)
EffectP()
endRmdBlock()
endRnwBlock()
enterMarkdown(command)
enterKnitr(command)
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 combobox
getFrame(object)
# S3 method for listbox
getFrame(object)
# S3 method for combobox
getSelection(object)
# S3 method for listbox
getSelection(object)
getRcmdr(x, mode="any", fail=TRUE)
gettextRcmdr(...)
glmP()
GrabFocus(value)
groupsBox(recall=NULL, label=gettextRcmdr("Plot by:"), 
    initialLabel=gettextRcmdr("Plot by groups"),
    errorText=gettextRcmdr("There are no factors in the active data set."),
    variables=Factors(),
    plotLinesByGroup=FALSE, positionLegend=FALSE, 
    plotLinesByGroupsText=gettextRcmdr("Plot lines by group"), 
    initialGroup=NULL, initialLinesByGroup=1, window=top)  # macro
groupsLabel(frame=top, groupsBox=groupsBox, columnspan=1, 
    initialText=NULL, ratio=FALSE)  # macro
hclustSolutionsP()
initializeDialog(window=top, title="", offset=10, preventCrisp,
    use.tabs=FALSE, notebook=notebook, 
    tabs=c("dataTab", "optionsTab"),
    suppress.window.resize.buttons=TRUE)  # macro
is.valid.name(x)
is.valid.number(string)
is.SciViews()
justDoIt(command)
knitrP()
Library(package, pos=length(search()), rmd=TRUE)
listAllModels(envir=.GlobalEnv, ...)
listAOVModels(envir=.GlobalEnv, ...)
listDataSets(envir=.GlobalEnv, ...)
listFactors(dataSet=ActiveDataSet())
listGeneralizedLinearModels(envir=.GlobalEnv, ...)
listLinearModels(envir=.GlobalEnv, ...)
listMultinomialLogitModels(envir=.GlobalEnv, ...)
listNumeric(dataSet=ActiveDataSet())
listPlugins(loaded=FALSE)
listProportionalOddsModels(envir=.GlobalEnv, ...)
listTwoLevelFactors(dataSet=ActiveDataSet())
listVariables(dataSet=ActiveDataSet())
lmP()
logger(command, rmd=TRUE)
logLikP()
LogWindow()
MacOSXP(release)
manualTranslationP()
MarkdownP()
mavericksP()
Message(message, type=c("note", "error", "warning"))
MessagesWindow()
modelCapability(capability)
modelFormula(frame=top, hasLhs=TRUE, rhsExtras=NULL,
    formulaLabel=gettextRcmdr("Model Formula"))  # macro
modelsP(n=1)
multinomP()
Numeric(names)
numericP(n=1)
OKCancelHelp(window=top, helpSubject=NULL, model=FALSE, 
    reset=NULL, apply=NULL, helpPackage=NULL)  # macro
OutputWindow()
packageAvailable(name)
polrP()
popCommand(keep=FALSE)
popOutput(keep=FALSE)
putDialog(dialog, values=NULL, resettable=TRUE)
putRcmdr(x, value)
radioButtons(window=top, name=stop("name not supplied"), 
    buttons=stop("buttons not supplied"), 
    values=NULL, initialValue=..values[1], 
    labels=stop("labels not supplied"), 
    title="", title.color=getRcmdr("title.color"), 
    right.buttons=FALSE, command=function(){})   # macro
RappP()
RcmdrEditor(buffer, title="R Commander Editor", ok,
    help=NULL, file.menu=NULL, edit.menu=NULL, context.menu=NULL, 
    toolbar.buttons=NULL)
RcmdrTclSet(name, value)
RcmdrTkmessageBox(message, icon=c("info", "question", "warning",
    "error"), type=c("okcancel", "yesno", "ok"), default, title="")
removeLastRmdBlock()
removeLastRnwBlock()
removeNullRmdBlocks()
removeNullRnwBlocks()
removeStrayRmdBlocks()
removeStrayRnwBlocks()
RExcelSupported()
rglLoaded()
RmdWindow()
RnwWindow()
setBusyCursor()
setIdleCursor()
sortVarNames(x)
subOKCancelHelp(window=subdialog, helpSubject=NULL)  # macro
subsetBox(window = top, subset.expression = NULL, model = FALSE)  # macro
suppressMarkdown(command)
tclvalue(x)
titleLabel(...)
tkfocus(...)
tkspinbox(parent, ...)
trim.blanks(text)
TwoLevelFactors(names)
twoLevelFactorsP(n=1)
UpdateModelNumber(increment=1)
variableComboBox(parentWindow, variableList=Variables(),
    export="FALSE", state="readonly",
    initialSelection=gettextRcmdr(""),
    title="")
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"), 
    vars=NULL)
WindowsP()
X11P()

# the following functions are exported for technical reasons, # but are not meant to be called directly

commanderPosition()

Arguments

ask

ask for confirmation.

ask.save

ask whether to save contents of script and output windows.

apply

if non-null (the default is NULL), an Apply button is included in the dialog's button bar. This argument should be set to the quoted name of the function that initiates the dialog; when the button is pressed, the onOK function for the dialog is executed, and then the function named in apply is (re)called.

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.

buffer

a text string, typically representing the contents of a text widget, such as an R Markdown or knitr document.

buttons

vector of quoted names for buttons in a set of related radio buttons.

capability

character string giving the name of a column in the R Commander model-capabilities table, including the name of a column added by a plug-in; see model-capabilities.txt in the Rcmdr sources for the standard table; e.g., "sum" indicates the availability of an applicable summary() method for the current model.

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.

context.menu

NULL or a list containing one or more two-element lists: the first element, label, supplies the text label for a menu item in the RcmdrEditor right-click context menu; the second element, command, is a call-back function to be evaluated when the menu item is selected. If NULL (the default), no item will be added to the file menu.

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.

edit.menu

NULL or a list containing one or more two-element lists: the first element, label, supplies the text label for a menu item in the RcmdrEditor Edit menu; the second element, command, is a call-back function to be evaluated when the menu item is selected. If NULL (the default), no item will be added to the file menu.

envir

the environment to be searched; should generally be left at the default.

errorText

error message to print if a suitable factor isn't available.

export

export selection?

expr

expression constituting the body of the macro; typically a compound expression.

fail

if TRUE, the default, getRcmdr will generate an error if the object sought doesn't exist; if FALSE and the object doesn't exist, NULL is returned.

file.menu

NULL or a list containing one or more two-element lists: the first element, label, supplies the text label for a menu item in the RcmdrEditor File menu; the second element, command, is a call-back function to be evaluated when the menu item is selected. If NULL (the default), no item will be added to the file menu.

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.

force.wait

call tkwait.window so that processing is suspended until the dialog is closed; overrides the Rcmdr tkwait.dialog option (see Commander) if the latter is set to FALSE (its default). The force.wait argument should be set to TRUE for subdialogs.

formulaLabel

text label printed above the formula widget.

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.

grid.buttons

insert call to tkgrid for the buttons frame (default FALSE); use TRUE for tabbed dialogs and optionally for other dialogs.

groupsBox

listbox object for selecting groups variable.

initialText

initial text to display in the groups label; if NULL, "<No groups selected>" will be displayed.

hasLhs

does the model formula have a left-hand side?

help

a two element list: the first element, label, supplies the text label for a menu item in the RcmdrEditor Help menu; the second element, command, is a call-back function to be evaluated when the menu item is selected. If NULL (the default), no item will be added to the editor Help menu.

helpSubject

the quoted name of a help subject, to be called as help(helpSubject) when the dialog Help button is pressed.

helpPackage

the quoted name of the package in which to look for help; the default, NULL, produces a search in all loaded packages --- see help.

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.

keep

if TRUE, keep (rather than pop) last output or command in the stack; the default is FALSE.

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.

lib.loc

see documentation for data.

list

see documentation for data.

listHeight

Maximum number of elements displayed simultaneously in list box.

loaded

if TRUE, plug-in packages that are loaded are included in the vector of names returned.

log

echo command to the script 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.

n

number of items to check for.

name

quoted name.

names

optional names to be stored.

notebook

notebook windows for a tabbed dialog (default notebook).

object

an object (depends on context).

offset

in pixels, from top-left of Commander window.

ok

a function called when the OK button is pressed in a RcmdrEditor window that saves the editor buffer to the appropriate Tcl variable.

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; also see documentation for data.

parent

parent Tk window.

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 just before the end of the path.

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

this argument is ignored, and is present only for backwards compatibility.

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. In MacOSXP, the minimum release (version) required.

ratio

If FALSE, the default, the test will be expressed as a test for a difference (e.g., a difference in means); if TRUE, as a test for a ratio (e.g., a ratio of variances).

reportError

if TRUE, report an error message.

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

resizable

should the dialog be resizable by the user? The default is FALSE.

rhsExtras

show controls for splines and polynomials for a model formula; for backwards compatibility, defaults to TRUE for a two-sided formula and FALSE for a one-sided formula.

right.buttons

radio button placed to right of button-labels; defaults to FALSE.

rmd

enter the command in the R Markdown tab.

rows, columns

numbers of rows and columns of widgets in the dialog box; this is actually no longer used, but is still present for backwards compatibility.

selectmode

"single" or "multiple".

state

state of the combobox widget; default "readonly" means user can't type in the box; set to "normal" to permit typing.

strict

if TRUE, only use first element of class vector.

string

a character string, or vector of strings, to be tested whether it can be coerced to a number or numbers; returns either TRUE or FALSE.

subset.expression

a quoted expression to subset the data set.

suppress.window.resize.buttons

if TRUE, the default, the window maximize/minimize buttons will not be displayed.

tab.names

text to print as tab labels (default c("Data", "Options")).

tabs

quoted names of tabs for a tabbed dialog (default c("dataTab", "optionsTab")).

text

a text string.

title

Window or dialog-box-element title.

title.color

color for title above radio buttons; defaults to "blue".

toolbar.buttons

NULL or a list containing one or more three-element lists: the first element, label, supplies the text label for a button in the RcmdrEditor toolbar; the second element, command, is a call-back function to be evaluated when the button is pressed; the third element is the name of a tk image to display as an icon in the button. If NULL (the default), no buttons will be added to the toolbar.

ttk

use ttk themed widget for check boxes.

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.

use.tabs

(default FALSE) construct a tabbed dialog.

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.

vars

a vector of one or more variable names; if given type argument is ignored.

verbose

see documentation for data.

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 titleLabel, arguments to be passed to labelRcmdr and from there to ttklabel; 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. Also see the RcmdrPlugin.survival package for examples.

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''). Use popOutput(keep=TRUE) to access the last output but keep it in the stack. 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.

Normally commands also generate an R Markdown block. suppressMarkdown takes a command in character-string form and adds an attribute to it that will cause the command not to be entered in the R Markdown tab. This is useful when a command, such as identify, requires direct user interaction and won't generate useful Markdown. enterMarkdown can be used to enter command blocks directly in the R Markdown tab; this should rarely be required. The functions beginRmdBlock, endRmdBlock, removeNullRmdBlocks, removeLastRmdBlock, and removeStrayRmdBlocks should normally not be called directly. The functions enterKnitr, beginRnwBlock, endRnwBlock, removeNullRnwBlocks, removeLastRnwBlock, and removeStrayRnwBlocks perform similar functions for Knitr documents.

Checking for errors:

The function is.valid.name checks whether a character string specifies a valid name for an R object. The function is.valid.number checks whether a character string (or vector) can be coerced to a number (or numbers). 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. The function is.SciViews always returns FALSE since the SciViews GUI is no longer supported.

The function modelCapability() returns TRUE if there is an active statistical model and if it has the specified capability. For example, modelCapability("sum") returns TRUE if the model-capabilities table indicates that there's an applicable summary() method for the active model. Otherwise, FALSE is returned. If the specified capability doesn't exist, a warning is printed.

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 associated methods for the generic functions getFrame and getSelection); a drop-down "combo" box, variablecomboBox (with getFrame and getSelection methods); 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. The tkspinbox function is omitted from the tcltk package and may be used to create a spinbox widget. The titleLabel function may be used to format a title label to use the standard title label font and color.

``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. WindowsP(), MacOSXP(), and X11P() return TRUE if the R Commander is running under Windows, Mac OS X, or X-Windows, consecutively.

Translating text:

The gettextRcmdr function simply passes its argument(s) to gettext, adding the argument domain="R-Rcmdr" It is not meant to be used in plug-in packages.

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, subset, 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 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), and are used in the R Commander to deal with scoping issues related to Tcl/Tk.

The tkfocus function is exported for historical reasons.

The data function, imported from the utils package, is exported for technical reasons.

References

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