eval.parameters: Interactive menu

Description

eval.parameters provides an interactive menu on a X11 graphical device of R

Usage

eval.parameters(variable, entry, update, simulate, dev, create = TRUE, 
		col.rect = "red", col.bg = "blue", col.sep = "grey", 
                col.left = "red", col.mid = "white", col.right = "white", 
                col.line = "red", col.txt = "black",
                cex=0.8, cex.i=cex, sep="-----", ...)

Arguments

variable

string. The name of the variable to be changed. The name consist of $ and [[]] expression pointing to sublists of a list. The complete list must be given by name in ...

entry

A list of lists. See Details.

update

logical. If TRUE then simulate is called after each interactive input.

simulate

function that is called if simulations are to updated. The parameters must equal the variables given by ...; the function must return the complete list indicated by variable.

dev

Before calling eval.parameters() split.screen must have been called. dev gives the screen on which the interactive menu should be plotted.

create

logical. If TRUE missing list elements of variable are created.

col.rect

colour of the button for free input.

col.bg

colour of a interactive bar

col.sep

colour of the separating line

col.left

colour of preceding element

col.mid

colour for the message

col.right

colour of subsequent element

col.line

colour of the marking line in interactive bars of absolute choice.

col.txt

colour of headers

cex

font height of headers

cex.i

font height of text for elements

sep

style of added characters in separating line.

...

The input variables given by name; the names may not start with a dot; There the complete list to which variable refers must be given. Further additional parameters for the function simulate.

Value

The first variable given in ..., which is a list. To this list the entry .history is added. If the users enters exit immediately at any point, the program stops with an error message.

Details

eval.parameters shows a menu list on X11. Depending on the mode of the variables the menu bars have a different appearance and behave differently if the user clicks on the bar. Most of the menu bars have a small rectangle on the right hand side. If this rectangle is pressed the input of a variable is expected in the xterm where R is run.

entry is a list of lists. Each list may contain the following elements:

name: header for menu button ifvaris notNULL; otherwise printed instead of a menu button
var:
- NULL: ifval=NULLthen it is a separating line in colourcol.sep;nameis surrounded bysep; all other elements of the list are ignored. Ifvalis a string thenvalis interpreted as a function; a special string is "simulate", which entails the call of the functionsimulatewith the appropriate parameters.
- string : selected element of the list that is given byvariable.A special string "undo" will be installed to undo things.
val:
- function(d, v)gives the update forvar. Ifvis missing, a starting value (for d=1/2) is expected. Otherwise,vis the current value ofvaranddis the choice of the user, a value in$[0,1]$
- TRUE: logical bar.
- FALSE: logical bar. The value forvaris negated before shown. In the menu, the negative value forvaris shown.
- NULL: a string is read from the terminal inotvar.
- character (vector): ifvaris given then this vector of strings is interpreted as belonging to a categorical variable$1,\ldots,\code{length(val)}$andvargives the number of the selected elements. Ifvar=NULLthenvalis interpreted as a function; a special string is "simulate", which entails the call of the functionsimulatewith the appropriate parameters.
delta: logical. In the menu bar absolute values are plotted ifdelta=FALSEand increments otherwise. Only considered ifvalis a function.
cond: The menue points is shown only if the given condition is satisfied. The condition must be expressed by named elements of the list variable, see example.
col: colour that overwrites the standard colour for the rectangle or the separating text.
update: logical. If not missing, its value overwrites locally the value of the global parameterupdate.
...: additional parameters forsimulatethat overwrite the values given in...in the call ofeval.parameters.

Examples

Run this code

## the following lines define a menu that does not make
  ## too much sense, but shows the various kinds of buttons

  quadratic <- function(d, v, a, mini=0, maxi=Inf) {
    d <- pmin(1, pmax(0, d)) - 0.5
    d <- ((d>0) * 2 - 1) * d^2 * a * 4
    if (missing(v)) d else pmax(mini, pmin(maxi, v + d))
  }

  simulate <- function(H, par) { ## not a serious example
    Print(c(H$x$var, par, runif(1)))
    return(H)  ## the function must return the first parameter
  }

  entry <- list(
     list(name="Nonsense Menu"),
     list(name="Simulate!", val="simulate", col="blue"),
     list(name="show H", val="str(H)", col="blue"),
     list(name="colx", var="colour",
          val=c("red", "green", "blue", "brown")),
     list(name="open", var="closed", val=FALSE, par=4.5),
     list(name="modifying", var="modify", val=TRUE, par=5),
     list(name="probability", var="probab", delta=FALSE,
          val=function(d, v) pmin(1, pmax(0, d))),
     list(name="variance", var="var", delta=TRUE,
          val=function(d, v) quadratic(d, v, 10)),
     list(name="name", var="name", par=3, cond="modify")
    )

  scr <- split.screen(rbind(c(0, 0.45, 0, 1), c(0.5, 1, 0, 1)))
  ## before proceeding make sure that both the screen and the xterm
  ## are completely visible

  H <- list(modify=5, x=list()) # note that in this example eval.parameters 
  ##          will be called by by H$x, hence modify=5 will be left
  ##          unchanged.
  options(locatorBell=FALSE)  useraction("start.register")  ## registring the user's input
  Print(eval.parameters("H$x", entry, simulate, update=TRUE, dev=scr[2],
     H=H, par=17)) # do not forget to call by name
  getactions()

  ## replay the user's input
  useraction("replay")
  Print(eval.parameters("H$x", entry, simulate, update=TRUE, dev=scr[2],
     H=H, par=17))