The playwith Application Programming Interface.
playwith plots (incorporating a plot, window and device)
are represented by a
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.
These are similar to
returns the current or last
playState – this is not necessarily the active
lists all open
sets the current
playState, and sets the active
closes the device and window (
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
type defaults to
space is ignored unless
type = "labelled".
playClear(playState, type, redraw)
remove one or more of the
latter will also apply to any linked plots. If
redraw = FALSE the display will not be updated.
reverts the last change any annotations (including the set of labelled and brushed data points).
triggers a redraw of any linked plots.
removes links from the given plot to any other plots (for linked brushing).
returns (deparsed) R code to reproduce the current plot display.
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).
a click on the plot. Similar to
playLineInput(playState, prompt, scales)
prompt to drag a line.
playRectInput(playState, prompt, scales)
prompt to drag a rectangular region.
statusbar text. Pass
NULL to reset. The GUI is
frozen when the prompt is set and unfrozen when reset.
disables or re-enables the GUI.
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).
gets or sets the x axis limits, in native coordinates of the given space (viewport).
rawXLim, for y axis limits.
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.
converts data coordinates to raw space (viewport) coordinates by applying a log transformation if necessary. If there are no log scales this does nothing.
callArg(playState, arg, eval, data)
gets or sets arguments to the main plot call.
gets or replaces
the main plot call (which is not necessarily the same as
the top-level call,
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.
redraws the plot by evaluating the plot call, and runs
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)
playNewPlot should be used instead.
playReplot is triggered when zooming,
editing plot settings, removing annotations, etc.
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
playNewPlot is triggered when the call text
is edited manually in the GUI.
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.
xyData, converted to numeric coordinates.
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
argument to the plot call, or from a
Felix Andrews email@example.com
1 2 3 4 5