playwith.API: The playwith API

Description

The playwith Application Programming Interface.

Arguments

Device management

These are similar to dev.set etc.

playDevCur(): returns the current or last active playState -- this is not necessarily the active graphics device.
playDevList(): lists all open playStates.
playDevSet(playState): sets the current playState, and sets the active graphics device.
playDevOff(playState): closes the device and window (dev.off() also works).

Common user commands

These functions are also available as menu items.

playGetIDs(playState, type, labels): returns indices (or labels) of currently brushed or labelled data points.
playSetIDs(playState, value, type, space, add, redraw, pos): sets which data points are brushed or labelled. type defaults to "brushed"; space is ignored unless type = "labelled".
playClear(playState, type, redraw): remove one or more of the types "annotations", "labelled", "brushed". The latter will also apply to any linked plots. If redraw = FALSE the display will not be updated.
playUndo(playState): reverts the last change any annotations (including the set of labelled and brushed data points).
updateLinkedSubscribers(playState, redraw): triggers a redraw of any linked plots.
playUnlink(playState): removes links from the given plot to any other plots (for linked brushing).
playSourceCode(playState): returns (deparsed) R code to reproduce the current plot display.

Interaction

These functions allow the user to click or drag on the plot. Click or drag locations are converted into the native coordinates of whatever plot space they occurred in (but are available as device coordinates too).

playSelectData(playState, prompt, scales, foo): interactively select data from the plot (one point or a whole region).
playPointInput(playState, prompt): prompt for a click on the plot. Similar to locator.
playLineInput(playState, prompt, scales): prompt to drag a line.
playRectInput(playState, prompt, scales): prompt to drag a rectangular region.
playPrompt(playState, text): sets the statusbar text. Pass NULL to reset. The GUI is frozen when the prompt is set and unfrozen when reset.
playFreezeGUI(playState), playThawGUI(playState): disables or re-enables the GUI.

Working with the display

playDo(playState, expr, space, clip.off, return.code): evalutes the given expression in the given plot space, i.e. after moving to the corresponding grid viewport.
playAnnotate(playState, annot, space, add, redraw): adds the annotation (a call or expression to draw on the plot) to the list of persistent annotations, and draws them. These will always be drawn after plotting (unless they are removed by the user).
rawXLim(playState, space): gets or sets the x axis limits, in native coordinates of the given space (viewport).
rawYLim(playState, space): same as rawXLim, for y axis limits.
spaceCoordsToDataCoords(playState, xy): converts raw space (viewport) coordinates to the data scale by applying an inverse log transformation if necessary. If there are no log scales this does nothing.
dataCoordsToSpaceCoords(playState, xy): converts data coordinates to raw space (viewport) coordinates by applying a log transformation if necessary. If there are no log scales this does nothing.

Working with the call

callArg(playState, arg, eval, data): gets or sets arguments to the main plot call.
mainCall(playState): gets or replaces the main plot call (which is not necessarily the same as the top-level call, playState$call).
updateMainCall(playState): locates the main plot call within the top-level call -- by matching against the given main.function, or by guessing. This allows callArg() to work correctly; it should be called if playState$call is replaced.
playReplot(playState): redraws the plot by evaluating the plot call, and runs update actions. This should be called after changing plot arguments (or annotations if that requires a redraw). However, if the data has changed or the type of plot (e.g. the high-level plot function) has changed, playNewPlot should be used instead. playReplot is triggered when zooming, editing plot settings, removing annotations, etc.
playNewPlot(playState): redraws the plot by evaluating the plot call, updates the main call, runs init actions (such as detecting whether zooming, identifying or brushing data points is possible), as well as running update actions as with playReplot. Note: playNewPlot is triggered when the call text is edited manually in the GUI.

Working with data

xyData(playState, space): attempts to extract plot data in terms of x and y locations, but in the original data form (such as factor, date or time). This uses the generic function plotCoords to generate plot locations; new methods can be defined for non-standard plot types.
xyCoords(playState, space): same as xyData, converted to numeric coordinates.
getDataArg(playState, eval): attempts to extract the underlying data set (typically a data.frame), which may contain more variables than those currently plotted. This may come from a data argument to the plot call, or from a with() block.

Details

playwith plots (incorporating a plot, window and device) are represented by a playState object.

The following sections list the API functions that can be used to work with the plot, and to write new interactive tools. See the links to specific help pages for details. In case these are insufficient, you may work with the playState object itself.

Examples

Run this code

if (interactive()) {

demo(package = "playwith")

}

Run the code above in your browser using DataLab