Dialog.data.frame
takes as input a data frame, and uses details
about all the variables in the data frame to call S-PLUS 4.5 or later
graphical user interface functions to enter one observation into that
data frame. An optional
fun
argument is used to add read-only
fields to show derived values in the dialog. For
factor
or
character
variables, a pop-up list of possible values is set up, and
"label"
attributes of variables are used as field prompts. For
variables having
"units"
attributes for units of measurement, these
units are added to the end of the prompt, enclosed in brackets. The
vectors in the input data frame can optionally be used to also
determine legal ranges for data, and default values. Depending on
defaultAuto
, the observed data can be used to derive default values
for categorical variables (mode category), binary or logical variables
(mode), and continuous variables (median). If an input data frame is
not specified, other parameters specifying the data attributes must be
given:
types
,
varnames
,
prompts
,
values
,
limits
, and these
parameters can also be given to override characteristics of the
observed data.
fitPar
is a utility function that collects information for one of the
model fits that are passed to
Dialog.Design
.
Dialog.Design
retrieves information from one or more model fits that
were created with
Design
in effect. These fits must have been run
through the
fitPar
function to collect additional information about
each fit such as functions that transform predicted values.
Dialog.Design
obtains all the information about the predictors such
as ranges and default values from the fit object, assuming that
datadist
was in effect when the fit was made.
Dialog.Design
creates functions to add predicted values and confidence limits to the
menu as read-only fields. It also adds
dataRep
information at the
end of the menu. The created functions are passed, along with
information about the predictors, to
Dialog.data.frame
. The
different fit objects passed to
Dialog.Design
through
fitPar
need
not have the same predictors. All unique predictors are found from
all fits, and these are placed at the beginning of the created menu,
in the order encountered. If
vary
is specified, not all fits need
have the predictor specified in
vary
. When a fit did not contain
this variable, only a single predicted value will be obtained for that
model.
plotDialogResults
is a function that is used in conjunction with
auxFun
and
Dialog.Design
(see below). It makes sense to pass
plotDialogResults
or
"plotDialogResults"
as the
auxFun
argument
to
Dialog.Design
if
conf.type
is not
"none"
for at least
some of the fits (
fitPar
objects) given to
Dialog.Design
.
Dialog(data, types=rep('',length(data)), varnames=names(data), prompts=NULL, values=NULL, basename=deparse(substitute(data)), prefix=paste(basename,'.',sep=''), Name=paste('menu',basename, sep='.'), resultName=paste('Result',basename,sep='.'), callbackName=paste('CallBack',basename,sep='.'), runmenuName=paste('runmenu',basename,sep='.'), required=T, limits=NULL, defaultAuto=c('factor','none','binfactor','all'), defaultValues=NULL, fun=NULL, funlabel=NULL, funArgType=c('list','data.frame'), funExtra=NULL, fungroups=NULL, auxFun=NULL, auxExtra=NULL, header=basename, helpCommand='page(DialogHelpText,multi=T)', where=1) Dialog(fitinfo, ..., vary=NULL, varyPrefix=F, basename=fitinfo[[1]], prefix=paste(basename,'.',sep=''), prompts=NULL, required=T, limits=NULL, defaultAuto=c('factor','none','binfactor','all'), defaultValues=NULL, funExtra=NULL, datarep=NULL, auxFun='plotDialogResults', auxExtra=NULL, header=basename, helpCommand='page(DialogHelpText,multi=T)', where=1) fitPar(fitname, label='Predicted Value', lp=T, lplabel=label, lp.round=2, conf.int=.95, conf.type=c('mean','individual','both','none'), fun=NULL, fun.round=lp.round) plotDialogResults(results, extra)
fitPar
Design
k
lists where
k
is the number of
fitPar
objects passed to
Dialog.Design
, plus one for an optional element
named
vary
plus one if a
datarep
object was
also passed to
Dialog.Design
. Aside from the
datarep
object
(named
"datarep"
) and the
vary
object, the lists contain the
fitPar
information along with a list named
estimates
that contain
the predicted values and confidence limits.
Dialog.data.frame
if
types
is not.
data
is not. Values are
"logical", "binary", "factor"
,
"string", "integer", "float"
.
types
.
Specified if
data
is not.
Dialog.data.frame
is a string vector specifying field prompts in
the same order as variables in
data
or
varnames
. For
Dialog.Design
this is a named vector specifying overrides to
predictor variable labels as they were used in the model fits. For
example, to override labels for
age
,
sex
to specify customized
prompts, use
prompts=c(age=
Age [years]', sex='Sex')'.
Dialog.data.frame
when
data
is omitted, you must specify
values of categorical predictors using for example
values=list(sex=c("female","male"), treatment=c("placebo","drug")
.
prefix
.
The default is the name of the
data
argument given to
Dialog.data.frame
or the name of the first fit object given to
Dialog.Design
. It is best specified by the user, and
basename
or
prefix
should be chosen so that GUI objects stored in _Prefs should be
uniquely named.
prefix
when their names are formed. The default
for
prefix
is
basename
followed by a period.
Name
function.
required=F
to not require any
values to be entered, or specify a vector of predictor variable
names corresponding to a subset you wish to be required.
limits="data"
to restrict values to be in the range of the observed
data. Specify for example
limits=list(age=c(0,100),
height=c(30,84))
to have control over the limits to be imposed during
data entry.
defaultValues
is specified and is not
"none"
, default
values for factor variables will appear by their prompts, and unless
defaultValues
is given for such variables, the values that pop up
are the most frequent categories. Specify
defaultAuto="binfactor"
to also use modal values for binary or logical variables. Specify
"all"
to use automatic default values for all predictors. For
continuous predictors, the median values are the default values.
defaultAuto
, for example
defaultValues=list(age=50, sex="male")
.
Dialog.Design
,
fun
is a list of (usually) simple functions
along with labels (prompts) for them, that are used to transform
linear predictors. For example,
fun=list("Predicted
Probability"=plogis, "Predicted Odds"=exp)
are useful for binary
logistic models.
fun
, for
Dialog.data.frame
.
fun
functions for obtaining derived values.
Specify
funArgType="data.frame"
to
Dialog.data.frame
to convert
the list to a data frame before calling the functions. The list of
data frame is the first argument given to these functions.
fun
and
funlabel
there are per group. For
example, if
fun
produces a vector of 7 values and the first 3
pertain to
"Speed"
and the last 4 to
"Size"
, specify
fungroups=c(Speed=3, Size=4)
. Specify e.g.
c("Speed of Travel"=3)
when group names are not legal S-PLUS names. These group names are
used to organize values into groups, with overall labels.
fun
) are
displayed. The argument passed to this function is the
"results"
attribute returned by
fun
. For
Dialog.Design
, this
"results"
object is created automatically. It is a list of lists containing
the
fitPar
objects augmented with an
estimates
object containing
predictions (
linear.predictors
) and confidence limits (
upper
,
lower
,
iupper
,
ilower
, where
i
stands for "individual" and
others are for the mean). There are additional element of
results
.
The
data
element contains a data frame of the predictor values
entered by the user. A
vary
list contains the variable and its
settings that were specified to
Dialog
as
vary
. A
datarep
element
contains the result of
predict(dataRep object)
if
datarep
was given.
auxFun
can be a character string containing the name of the
function, or the actual function itself. If the former case it is
assumed that the function is available in the search list when the
menu is run.
auxFun
is useful for plotting results that are
presented in printed form in the menu. The
plotDialogResults
(the
default value of
auxFun
for
Dialog.Design
) function is set up to
plot the
results
object. Specify
auxFun=NULL
to suppress
invocation of any auxiliary function when Apply is pressed.
auxFun
basename
.
helpCommand
uses the
page
command
to display general help text found in a character vector
DialogHelpText
.
fitPar
objects, to allow for more than one model to be
evaluated in the menu
vary
is of the form
list(treatment=levels(treatment)
.
vary
variable name will not appear as a label in the
menu. Set
varyPrefix=T
to use the variable name as a prefix to the
vary
values, or set
varyPrefix
to a single character string to use
that prefix instead.
dataRep
vary
is not present. Defaults to
lplabel
or the name of the first
fun
if these are specified and
label
is not.
F
to prevent the ordinary predicted value (linear predictors)
from being displayed. This is useful for example when
fun
specifies
the logistic transformation and you want to specify predicted
probabilities but not predicted logits.
lp=T
lp.round
decimal
places (default is 2) before being displayed.
"mean"
to display
ordinary limits. Use
"individual"
to display confidence limits for
individual responses when using
ols
. Specify
conf.type="both"
to
display both confidence intervals for means and intervals for
individuals.
Dialog.Design
in
fun
to be
rounded to
fun.round
decimal places before being displayed. Default
uses two digits to the right. If there is more than one function in
fun
, elements of
fun.round
are assumed to be specified in the order
of the functions. If only one
fun.round
is given it is assumed to
apply to all of the functions.
plotDialogResults
, including
many graphical parameters. See the function for details.
When
vary
and
dataRep
are both used, the frequencies reported
regarding the
dataRep
information are the minimum number of matches
over all levels of
vary
.
fitPar
returns a list containing the name of the model fit along
with all of the information given to
fitPar
, with unspecified
options set to defaults. A vector of names of predictors used in the
fit is also contained in the result.
Dialog.data.frame
and
Dialog.Design
return a function definition that will start the
menu. You can use for example
.guiFirst <- Dialog(...)
to set up
for automatic invocation of the menu the next time you start S-PLUS.
Frank Harrell
Department of Biostatistics
Vanderbilt University School of Medicine
f.harrell@vanderbilt.edu
# Create a data frame, and generate a GUI to input data like that # Display the square root of one of the variables plus the # value of a binary variable test <- expand.grid(age=21:50, sex=c('female','male'), sick=0:1) Dialog(test, fun=function(z) round(sqrt(z$age)+z$sick,1), funlabel='Square root of age, +sick', limits=list(age=c(10,70)), fungroups=c('Calculated Values'=1)) runmenu.test() # Use a linear model in log(total cost) for the support dataset available # from hesweb1.med.virginia.edu/s/data, display predictions from a # binary logistic model for hospital death, and display various # predictions from a fitted Cox proportional hazards survival model # (1- and 2-year survival probability and median survival time). # The models do not use the # same predictors, so all the predictors from all models are first combined. # Prompts for all but two variables come from variable labels that were # orginally stored in the data frame. Prompts for two variables are defined # in the call to Dialog. # In this example, there is no prompt for the race variable as race is # automatically varied over all its levels, for models that have race # as one of the predictors. dd <- datadist(support) options(datadist='dd') costfit <- ols(log(totcst) ~ dzgroup + rcs(age,4) + race + sex + rcs(meanbp,5) + pol(scoma,2), data=support, subset=totcst>0) hospmortfit <- lrm(hospdead ~ rcs(age,4) + sex + rcs(meanbp,5) + rcs(crea,4), data=support) survivalfit <- cph(Surv(d.time, death) ~ dzgroup*rcs(age,4), surv=T, data=support) drep <- dataRep(~ dzgroup + roundN(age,20), data=support) drep Data Representativeness n=1000 dataRep(formula = ~ dzgroup + roundN(age, 20), data = support) Specifications for Matching Type dzgroup exact categorical age round Parameters dzgroup ARF/MOSF w/Sepsis COPD CHF Cirrhosis Coma Colon Cancer Lung Cancer MOSF w/Malig age to nearest 20 33 unique combinations of variable values were found. surv <- Survival(survivalfit) # Derive function to estimate S(t|Xbeta) surv1 <- function(lp) surv(365, lp) # Derive function to get S(1|Xbeta) surv2 <- function(lp) surv(365*2, lp) # Function to get S(2|Xbeta) survq <- Quantile(survivalfit) # Derive function to get S inverse survmed <- function(lp) survq(.5, lp) # Derive function for S inverse(.5) # At present, Dialog does not support stratification in cph when # predicting survival probabilities or survival times, unless strata # are specified explicitly when surv or survmed are called. Dialog(fitPar('costfit', lp=F, conf.type='both', fun=list('Median Cost ($/1000)'=function(y)exp(y)/1000), fun.round=0), fitPar('hospmortfit', lp=F, conf.type='mean', fun=list('Probability of Death in Hospital'=plogis),label=''), fitPar('survivalfit', lp=F, conf.type='none', fun=list('1-Year Survival'=surv1, '2-Year Survival'=surv2, 'Median Survival Time [days]'=survmed), fun.round=c(2,2,0), label='Survival Predictions'), vary=list(race=levels(support$race)), basename='SUPPORT', header='SUPPORT Predictive Models', prompts=c(scoma='SUPPORT Coma Score', sex='Sex'), defaultAuto='binfactor', limits='data', datarep=drep) # lp=F prevents predicted log(totcst) and logit(prob of death) # from being displayed runmenu.SUPPORT() # Generate data and fit two ols models for a clinical trial in which # we are predicting follow-up values of two baseline variables. # Graphically display predictions for both treatments, along with # baseline values (using a triangle, between the two lines for treatment) n <- 500 set.seed(17) # to reproduce results treatment <- sample(c('Drug','Placebo'), n, T) label(treatment) <- 'Treatment' age <- rnorm(n, 50, 10) sex <- sample(c('female','male'), n, T) sys.bp <- rnorm(n, 120, 8) dias.bp <- rnorm(n, 80, 8) label(sys.bp) <- 'Systolic Blood Pressure [mmHg]' label(dias.bp) <- 'Diastolic Blood Pressure [mmHg]' drep <- dataRep(~ roundN(age,2.5) + sex) # Now simulate blood pressures after one year of follow-up sys.bp1 <- sys.bp + (age-50)/5 + (sex=='male') - 3*(treatment=='Drug')+ rnorm(n, 0, 4) dias.bp1<- dias.bp+ (age-50)/5 + (sex=='male') - 3.5*(treatment=='Drug')+ rnorm(n, 0, 4) dd <- datadist(age, sex, treatment, sys.bp, dias.bp) options(datadist='dd') fitsys <- ols(sys.bp1 ~ sys.bp + age + sex + treatment) fitdias <- ols(dias.bp1 ~ dias.bp + age + sex + treatment) Dialog(fitPar('fitsys', lplabel='Systolic BP at Year 1', lp.round=1, conf.type='both'), fitPar('fitdias',lplabel='Diastolic BP at Year 1', lp.round=1, conf.type='both'), vary=list(treatment=c('Placebo','Drug')), basename='BP', header='Hypertension Trial Predictions', limits='data', datarep=drep, auxExtra=list(baseline.vars=c('sys.bp','dias.bp'))) # Set up a function that will cause the menu to be displayed # as soon as S-PLUS is started. Some options are also given. .guiFirst <- function() { guiSetOption('AutoAddPages','Every Graph') graphsheet(Name='Hypertension Trial', background.color='user9') # or guiSetOption('BackColorStd','user9') and wait for first # plot to open a graphsheet guiExecuteBuiltIn( '$$SPlusMenuBar$Object_Browser$Window$Tile_Vertical') # Can add library() commands here as needed (or put in .First) # Install button to allow menu to be easily invoked in the future if(!length(locate.menu.item('Hypertension Predictions'))) add.menu.item(name="Hypertension Predictions", action='runmenu.BP()') # Type delete.menu.item('Hypertension Predictions') to remove button # Invoke menu now runmenu.BP() invisible() }