Arguments common to l_plot functions

Like plot in R, l_plot is the generic plotting function for objects in loon.

This is the workhorse of loon and is often a key part of many other displays (e.g. l_pairs and l_navgraph)

Because plots in loon are interactive, the functions which create them have many arguments in common. The value of these arguments become `infostates` once the plot is instantiated. These can be accessed and set using the usual R square bracket operators `[]` and `[]<-` using the statename as a string. The state names can be found from an instantiated loon plot either via l_info_states() or, more in keeping with the R programming style, via names() (uses the method names.loon() for loon objects).

The same state names can be passed as arguments with values to a l_plot() call. As arguments many of the common ones are desribed below.

Arguments

x

the x and y arguments provide the x and y coordinates for the plot. Any reasonable way of defining the coordinates is acceptable. See the function xy.coords for details. If supplied separately, they must be of the same length.
y

argument description is as for the x argument above.
by

loon plots can be separated by some variables into multiple panels. This argument can take a formula, n dimensional state names (see l_nDimStateNames) an n-dimensional vector and data.frame or a list of same lengths n as input.
on

if the x or y is a formula, an optional data frame containing the variables in the x or by. If the variables are not found in data, they are taken from environment, typically the environment from which the function is called.
layout

layout facets as 'grid', 'wrap' or 'separate'
connectedScales

Determines how the scales of the facets are to be connected depending on which layout is used.
linkingGroup

a string naming a group of plots to be linked. All plots with the same linkingGroup will have the same values of their linked states (see l_getLinkedStates() and l_setLinkedStates()).
linkingKey

an n-dimensional character vector of unique entries. The entries identify which points match other points in other plots. Default is c("0", "1", ..., "n-1") (for numerical n).
itemLabel

an n-dimensional character vector whose values are displayed in a pop-up box over any point whenever the mouse hovers over that point (provided showItemLabels = TRUE).

This action is commonly known as providing a "tool tip". Note that all objects drawn in any layer of a plot (e.g. maps) will have an itemLabel.
showItemLabels

a logical (default FALSE) which indicates whether the "tool tip" itemLabel is to be displayed whenever the mouse hovers over it.
color

colours of points (default "grey60"); colours are repeated until matching the number points,
glyph
the string names of primitive glyphs:

squares or boxes

"square", "csquare", "osquare",

triangles

"triangle", "ctriangle", "otriangle",

diamonds

"diamond", "cdiamond", or "odiamond".

Note that prefixes "c" and "o" may be thought of as closed and open, respectively. The set of values are returned by l_primitiveGlyphs().

the string names of constructed glyphs

text as glyphs

see l_glyph_add_text()

point ranges

see l_glyph_add_pointrange()

polygons

see l_glyph_add_polygon()

parallel coordinates

see l_glyph_add_serialaxes()

star or radial axes

see l_glyph_add_serialaxes()

or any plot created using R

see l_make_glyphs()

Note that glyphs are constructed and given a stringname to be used in the inspector.

size

size of the symbol (roughly in terms of area)
active

a logical determining whether points appear or not (default is TRUE for all points). If a logical vector is given of length equal to the number of points, then it identifies which points appear (TRUE) and which do not (FALSE).
selected

a logical determining whether points appear selected at first (default is FALSE for all points). If a logical vector is given of length equal to the number of points, then it identifies which points are (TRUE) and which are not (FALSE).
xlabel

Label for the horizontal (x) axis. If missing, one will be inferred from x if possible.
ylabel

Label for the vertical (y) axis. If missing, one will be inferred from y (or x) if possible.
title

Title for the plot, default is an empty string.
minimumMargins

the minimal size (in pixels) of the margins around the plot (bottom, left, top, right)
showLabels

logical to determine whether axes label (and title) should be presented.
showScales

logical to determine whether numerical scales should be presented on both axes.
showGuides

logical to determine whether to present background guidelines to help determine locations.
guidelines

colour of the guidelines shown when showGuides = TRUE (default "white").
guidesBackground

colour of the background to the guidelines shown when showGuides = TRUE (default "grey92").
foreground

foreground colour used by all other drawing (default "black").
background

background colour used for the plot (default "white")
parent

a valid Tk parent widget path. When the parent widget is specified (i.e. not NULL) then the plot widget needs to be placed using some geometry manager like tkpack or tkplace in order to be displayed. See the examples below.
...

named arguments to modify plot states.

Details

The interactive displays permit a number of direct interactions using the mouse and keyboard, these include: zooming towards the mouse cursor using the mouse wheel, panning by right-click dragging and various selection methods using the left mouse button such as sweeping, brushing and individual point selection. See the documentation for l_plot for more details about the interaction gestures.

See also

the demos demo(l_glyph_sizes, package = "loon"), demo(l_glyphs, package = "loon"), and demo(l_make_glyphs, package = "loon").

Examples

   if (FALSE) {
    # default use as scatterplot

    p1 <- with(iris, l_plot(x = Sepal.Length,
                            y = Sepal.Width,
                            color=Species,
                            title = "Sepal sizes"))

    # The names of the info states that can be
    # accessed or set.  They can also be given values as
    # arguments to l_plot.default()
    names(p1)
    versicolor <- (iris$Species == "versicolor")
    p1["size"] <- 10
    p1["glyph"][versicolor]<- "csquare"
    p1["minimumMargins"][1] <- 100
  }