playwith {plotAndPlayGTK}R Documentation

An interactive plot GUI

Description

Open a GTK+ window to view and interact with a plot.

Usage

playwith(expr, name = "plot", nav.scales = c("x","y"), trans.scales = c("y"), 
         buttons = list("annotate", "identify", "zoom", "zoomfit"), 
         extra.buttons = list("zero"), basic.buttons=plotAndPlayBasicButtons, 
         labels = NULL, label.args = list(cex = 1), identify.call = NULL, 
         plot.call, is.lattice = NA, eval.args = NA, invert.match = F, 
         envir = parent.frame(), restore.on.close = NULL)

Arguments

expr an expression to create a plot, like plot(mydata). Note, this can have lots of arguments, just like a normal plot call (see examples). Can also be a chunk of code in {braces}, but that form does not allow interaction.
name character value to identify the plot window.
nav.scales one or more of c("x","y") defining which scale(s) to navigate along (e.g. zoom in).
trans.scales one or more of c("x","y") defining which scale(s) to transform (e.g. log).
buttons a list of buttons for the toolbar. Each element should be a call to generate a gtkToolItem, or a character string. If it is a character string, that element is taken from the pre-defined plotAndPlayButtons. See the Details and Examples sections.
extra.buttons same as buttons, provided for convenient additions to the default set.
basic.buttons same as buttons, the default here is almost always useful, so you probably do not want to change this.
labels a character vector of labels for data points, for use in identify. If missing, it will be guessed from the plot call. If identify.call is given, this is ignored.
label.args a list of arguments passed to identify and text: can include cex, col and font. Will also be added to identify.call if that is given.
identify.call a call to be evaluated when the identify button is clicked. If missing, it will be constructed from the plot call. Generally this argument should not be needed.
plot.call a plot call ( call object), if given this is used instead of expr.
is.lattice whether the plot is a Lattice plot, i.e. returns a trellis object. If NA, the call name is matched against known Lattice function names.
eval.args whether to evaluate the plot call arguments: can be TRUE, FALSE, NA (don't eval global vars) or a regular expression matching symbols to evaluate. See below.
invert.match whether to evaluate arguments that do NOT match the regular expression given in eval.args.
envir environment to use in evaluating the call arguments (see eval.args)
restore.on.close a gtkWindow to bring to front when the plot window is closed.

Details

This function generates a general-purpose graphical user interface for R plots. It tries to work out what kind of plot it is, and how you might want to interact with it. This is based firstly on whether the plot function name is recognised as a Lattice plot or not. If it is a not a standard high-level function you may need is.lattice=T.

In order for the plot to be modified, its supporting data needs to be stored. By default, all non-global data is copied into an attached environment and stored. More on this below.

This function will also try to guess labels for data points. It does this by evaluating the x argument (data argument for Lattice plots), or part of the formula. To suppress this evaluation, give labels explicitly (may be labels=NA).

Each element of buttons should be a call to generate a gtkToolItem (typically a gtkToolButton), or text, in which case it is taken from the pre-defined set. Type str(plotAndPlayButtons) to see the pre-defined set of button handlers. However, you can usually ignore this, as most buttons will be automatically added to the toolbar for relevant plots. Specifically:

But these may be overridden by specifying buttons explicitly.

See plotAndPlayButtons if you want to define new buttons.

The interaction features require that all variables appearing in the plot call remain accessible:

The default setting eval.args=NA causes variables appearing in the plot call to be evaluated and stored, except if they are defined in the global environment (i.e. user workspace). This method should work in most cases, but: Functions appearing in the plot call will be evaluated each time the plot is updated – so random data as in plot(rnorm(100)) will keep changing, with confusing consequences! You should therefore generate random data prior to the plot call. Changes to variables in the global environment will also cause inconsistencies in previously generated plots (e.g. labels on data points may be wrong).

If eval.args=T then variables appearing in the plot call will be evaluated and stored even if they are defined in the global environment. Use this if the global variables might change (or be removed) before the plot is destroyed.

If a regular expression is given for eval.args then only variables whose names match it will be evaluated, and this includes global variables, as with eval.args=T. In this case you can set invert.match=T to evaluate variables that are not matched. For example eval.args="^tmp" will evaluate variables whose names begin with "tmp"; eval.args="^foo$", invert=T will evaluate everything except foo.

If eval.args=F then the plot call will be left alone (not evaluated until plot time).

Value

playwith invisibly returns the value from the plot call (which for lattice plots is a trellis object).

Author(s)

Felix Andrews felix@nfrac.org

See Also

setAutoPlaywith, plotAndPlayButtons, xyplot, Lattice

Examples

## Not run: 

## `playwith` a base graphics plot: interaction and annotation
## -- from example(plot.default)
playwith(plot(cars$speed, cars$dist, xlab = "Speed", ylab = "Distance",
         panel.first = lines(lowess(cars$speed, cars$dist), lty = "dashed"),
         pch = 0, cex = 1.2, col = "blue"))

# you might get an error "Plot margins too small"; make window bigger and repeat

require(lattice)

## multiple lattice panels; identify points with nice labels
playwith(xyplot(Income ~ log(Population / Area) | state.region, 
        data=data.frame(state.x77)))

## same plot with 2 pages (2 panels per page); new plot window
playwith(xyplot(Income ~ log(Population / Area) | state.region, 
        data=data.frame(state.x77), layout=c(2,1)), name="other plot")

## time series plot: navigate x-axis only, transform y-axis
treering2 <- window(treering, start=1)
playwith(plot(treering2), nav.scales="x", trans.scales="y", 
        labels=paste(time(treering2),"CE"), 
        extra.buttons=list("logscale"))

## see what the current call is (for last focused plot window)
plotAndPlayGetState()$call

## example of evaluating and storing arguments in the plot call
globalOne <- 1:10
localStuff <- function() {
        localOne <- 10:1
        playwith(plot(localOne, globalOne))
}
localStuff()
## see which objects have been copied and stored with the plot
sapply(plotAndPlayGetState()$env, object.size)

## brushing multivariate scatterplots, see help(panel.brush.splom)
playwith(splom(environmental))

## simple spin and zoom for 3D plots
playwith(wireframe(volcano, drape=TRUE))

## example of the 'layers' button with a panel function
## -- from example(xyplot)
EE <- equal.count(ethanol$E, number=9, overlap=1/4)
playwith(xyplot(NOx ~ C | EE, data = ethanol,
       prepanel = function(x, y) prepanel.loess(x, y, span = 1),
       xlab = "Compression Ratio", ylab = "NOx (micrograms/J)",
       panel = function(x, y) {
           panel.grid(h=-1, v= 2)
           panel.xyplot(x, y)
           panel.loess(x,y, span=1)
       },
       aspect = "xy"))

## a code chunk: no interaction, only annotation, saving, etc
## -- from example(plot.default)
x <- 0:12
y <- sin(pi/5 * x)
playwith({
   op <- par(mfrow = c(3,3), mar = .1+ c(2,2,3,1))
   for (tp in c("p","l","b",  "c","o","h",  "s","S","n")) {
      plot(y ~ x, type = tp,
        main = paste("plot(*, type = \"",tp,"\")",sep=""))
      if(tp == "S") {
         lines(x,y, type = "s", col = "red", lty = 2)
         mtext("lines(*, type = \"s\", ...)", col = "red", cex=.8)
      }
   }
   par(op)
})

## see help(plotAndPlayButtons) for examples of defining new buttons!

## End(Not run)

[Package plotAndPlayGTK version 0.8.72 Index]