loon: A Toolkit for Interactive Data Visualization and Exploration

Description

Loon is a toolkit for highly interactive data visualization. Interactions with plots are provided with mouse and keyboard gestures as well as via command line control and with inspectors that provide graphical user interfaces (GUIs) for modifying and overseeing plots.

Details

Currently, loon implements the following statistical graphs: histogram, scatterplot, serialaxes plot (star glyphs, parallel coordinates) and a graph display for creating navigation graphs.

Some of the implemented scatterplot features, for example, are zooming, panning, selection and moving of points, dynamic linking of plots, layering of visual information such as maps and regression lines, custom point glyphs (images, text, star glyphs), and event bindings. Event bindings provide hooks to evaluate custom code at specific plot state changes or mouse and keyboard interactions. Hence, event bindings can be used to add to or modify the default behavior of the plot widgets.

Loon's capabilities are very useful for statistical analysis tasks such as interactive exploratory data analysis, sensitivity analysis, animation, teaching, and creating new graphical user interfaces.

To get started using loon read the package vignettes or visit the loon website at https://great-northern-diver.github.io/loon/.

Author(s)

Maintainer: R. Wayne Oldford rwoldford@uwaterloo.ca [thesis advisor]

Authors:

• Adrian Waddell adrian@waddell.ch

Other contributors:

• Zehao Xu z267xu@uwaterloo.ca [contributor]

• Martin Gauch martin.gauch@student.kit.edu [contributor]

See Also

Useful links:

• https://great-northern-diver.github.io/loon/

• Report bugs at https://github.com/great-northern-diver/loon/issues

Euclidean distance between two vectors, or between column vectors of two matrices.

Description

Quickly calculates and returns the Euclidean distances between m vectors in one set and n vectors in another. Each set of vectors is given as the columns of a matrix.

Usage

L2_distance(a, b, df = 0)

Arguments

Details

This fully vectorized (VERY FAST!) function computes the Euclidean distance between two vectors by:

||A-B|| = sqrt ( ||A||^2 + ||B||^2 - 2*A.B )

Originally written as L2_distance.m for Matlab by Roland Bunschoten of the University of Amsterdam, Netherlands.

Value

An m by n matrix containing the Euclidean distances between the column vectors of the matrix a and the column vectors of the matrix b.

Author(s)

Roland Bunschoten (original), Adrian Waddell, Wayne Oldford

See Also

dist

Examples

A <- matrix(rnorm(400), nrow = 10)
B <- matrix(rnorm(800), nrow = 10)
L2_distance(A[,1, drop = FALSE], B[,1, drop = FALSE])
d_AB <- L2_distance(A,B)
d_BB <- L2_distance(B,B, df = 1) # force diagonal to be zero

Data to re-create Hans Rosling's famous "Us and Them" animation

Description

This data was sourced from https://www.gapminder.org/ and contains Population, Life Expectancy, Fertility, Income, and Geographic.Region information between 1962 and 2013 for 198 countries.

Usage

UsAndThem

Format

A data frame with 9855 rows and 8 variables

Country

country name

Year

year of recorded measurements

Population

country's population

LifeExpectancy

average life expectancy in years at birth

Fertility

in number of babies per woman

Income

Gross domestic product per person adjusted for inflation and purchasing power (in international dollars)

Geographic.Region

one of six large global regions

Geographic.Region.ID

two letter identification of country

Source

https://www.gapminder.org/

Convert a loongraph object to an object of class graph

Description

Loon's native graph class is fairly basic. The graph package (on bioconductor) provides a more powerful alternative to create and work with graphs. Also, many other graph theoretic algorithms such as the complement function and some graph layout and visualization methods are implemented for the graph objects in the RBGL and Rgraphviz R packages. For more information on packages that are useful to work with graphs see the gRaphical Models in R CRAN Task View at https://cran.r-project.org/web/views/.

Usage

as.graph(loongraph)

Arguments

Details

See https://www.bioconductor.org/packages/release/bioc/html/graph.html for more information about the graph R package.

Value

graph object of class loongraph

Examples

if (requireNamespace("graph", quietly = TRUE)) {
  g <- loongraph(letters[1:4], letters[1:3], letters[2:4], FALSE)
  g1 <- as.graph(g)
}

Convert a graph object to a loongraph object

Description

Sometimes it is simpler to work with objects of class loongraph than to work with object of class graph.

Usage

as.loongraph(graph)

Arguments

Details

See https://www.bioconductor.org/packages/release/bioc/html/graph.html for more information about the graph R package.

For more information run: l_help("learn_R_display_graph.html.html#graph-utilities")

Value

graph object of class loongraph

Examples

if (requireNamespace("graph", quietly = TRUE)) {
  graph_graph  = graph::randomEGraph(LETTERS[1:15], edges=100)
  loon_graph <- as.loongraph(graph_graph)
}

Turn a loon size to a grid size

Description

The size of loon is determined by pixel (px), while, in grid graphics, the size is determined by pointsize (pt)

Usage

as_grid_size(
  size,
  type = c("points", "texts", "images", "radial", "parallel", "polygon", "lines"),
  adjust = 1,
  ...
)

Arguments

Return a 6 hexidecimal digit color representations

Description

Return a 6 hexidecimal digit color representations

Usage

as_hex6color(color)

Arguments

Details

Compared with hex12tohex6(), it could accommodate 6 digit code, 12 digit code or real color names.

See Also

l_hexcolor, hex12tohex6, l_colorName

Examples

color <- c("#FF00FF", "#999999999999", "red")
# return 12 hexidecimal digit color
loon:::l_hexcolor(color)
# return 6 hexidecimal digit color
as_hex6color(color)
# return color names
l_colorName(color)

## Not run: # WRONG COLORS
hex12tohex6(color)
## End(Not run)

A Character Data Frame to a Numerical Data Frame

Description

Turn a data frame of characters to a data frame of numerical values. If the character cannot be converted to numerical in direct, it will be turned to factor first, then to numerical data

Usage

char2num.data.frame(chardataframe)

Arguments

Examples

data <- data.frame(x = c("1", "2", "3"),
                   y = c("foo", "bar", "foo"),
                   z = 4:6)
# ERROR
# data + 1
numData <- char2num.data.frame(data)
numData + 1

if(interactive()) {
  s <- l_serialaxes(iris)
  data <- s["data"]
  # it is a character data frame
  data[1,1]
  numData <- char2num.data.frame(data)
  numData[1,1]
}

Create a palette with loon's color mapping

Description

Used to map nominal data to colors. By default these colors are chosen so that the categories can be well differentiated visually (e.g. to highlight the different groups)

Usage

color_loon()

Details

This is the function that loon uses by default to map values to colors. Loon's mapping algorithm is as follows:

1. if all values already represent valid Tk colors (see tkcolors) then those colors are taken

2. if the number of distinct values is less than the number of values in loon's color mapping list then they get mapped according to the color list, see l_setColorList and l_getColorList.

3. if there are more distinct values than there are colors in loon's color mapping list then loon's own color mapping algorithm is used. See loon_palette and the details section in the documentation of l_setColorList.

For other mappings see the col_numeric and col_factor functions from the scales package.

Value

A function that takes a vector with values and maps them to a vector of 6 digit hexadecimal encoded color representation (strings). Note that loon uses internally 12 digit hexadecimal encoded color values. If all the values that get passed to the function are valid color names in Tcl then those colors get returned hexencoded. Otherwise, if there is one or more elements that is not a valid color name it uses the loons default color mapping algorithm.

See Also

l_setColorList, l_getColorList, loon_palette, l_hexcolor, l_colorName, as_hex6color

Examples

pal <- color_loon()
pal(letters[1:4])
pal(c('a','a','b','c'))
pal(c('green', 'yellow'))

# show color choices for different n's
if (requireNamespace("grid", quietly = TRUE)) {
  grid::grid.newpage()
  grid::pushViewport(grid::plotViewport())
  grid::grid.rect()
  n <- c(2,4,8,16, 21)
  # beyond this, colors are generated algorithmically
  # generating a warning
  grid::pushViewport(grid::dataViewport(xscale=c(0, max(n)+1),
                     yscale=c(0, length(n)+1)))
  grid::grid.yaxis(at=c(1:length(n)), label=paste("n =", n))
  for (i in rev(seq_along(n))) {
   cols <- pal(1:n[i])
   grid::grid.points(x = 1:n[i], y = rep(i, n[i]),
                     default.units = "native", pch=15,
                     gp=grid::gpar(col=cols))
  }
  grid::grid.text("note the first i colors are shared for each n",
                  y = grid::unit(1,"npc") + grid::unit(1, "line"))
}

Create the Complement Graph of a Graph

Description

Creates a complement graph of a graph

Usage

complement(x)

Arguments

Value

graph object

Create the Complement Graph of a loon Graph

Description

Creates a complement graph of a graph

Usage

## S3 method for class 'loongraph'
complement(x)

Arguments

Details

This method is currently only implemented for undirected graphs.

Value

graph object of class loongraph

Create a complete graph or digraph with a set of nodes

Description

From Wikipedia: "a complete graph is a simple undirected graph in which every pair of distinct vertices is connected by a unique edge. A complete digraph is a directed graph in which every pair of distinct vertices is connected by a pair of unique edges (one in each direction

Usage

completegraph(nodes, isDirected = FALSE)

Arguments

Details

Note that this function masks the completegraph function of the graph package. Hence it is a good idead to specify the package namespace with ::, i.e. loon::completegraph and graph::completegraph.

For more information run: l_help("learn_R_display_graph.html.html#graph-utilities")

Value

graph object of class loongraph

Examples

g <- loon::completegraph(letters[1:5])

Create a named grob or a template grob depending on a test

Description

Creates and returns a grid object using the function given by 'grobFun' when 'test' is 'TRUE' Otherwise a simple 'grob()' is produced with the same parameters. All grob parameters are given in '...'.

Usage

condGrob(test = TRUE, grobFun = grid::grob, name = "grob name", ...)

Arguments

Value

A grob as produced by either the 'grobFun' given or by 'grob()' using the remaining arguments. If 'test = FALSE' then the name is suffixed by ": 'grobFun name' arguments".

Examples

myGrob <- condGrob(test = (runif(1) > 0.5),
                   grobFun = textGrob,
                   name = "my label",
                   label = "Some random text")
myGrob

Layout as a grid

Description

Layout as a grid

Usage

facet_grid_layout(
  plots,
  subtitles,
  by = NULL,
  prop = 10,
  parent = NULL,
  title = "",
  xlabel = "",
  ylabel = "",
  labelLocation = c("top", "right"),
  byrow = FALSE,
  swapAxes = FALSE,
  labelBackground = l_getOption("facetLabelBackground"),
  labelForeground = l_getOption("foreground"),
  labelBorderwidth = 2,
  labelRelief = "ridge",
  plotWidth = 200,
  plotHeight = 200,
  sep = "*",
  maxCharInOneRow = 10,
  new.toplevel = TRUE,
  ...
)

Arguments

layout separately

Description

layout separately

Usage

facet_separate_layout(
  plots,
  subtitles,
  title = "",
  xlabel = "",
  ylabel = "",
  sep = "*",
  maxCharInOneRow = 10,
  ...
)

Arguments

Layout as a wrap

Description

Layout as a wrap

Usage

facet_wrap_layout(
  plots,
  subtitles,
  prop = 10,
  parent = NULL,
  title = "",
  xlabel = "",
  ylabel = "",
  nrow = NULL,
  ncol = NULL,
  labelLocation = "top",
  byrow = TRUE,
  swapAxes = FALSE,
  labelBackground = l_getOption("facetLabelBackground"),
  labelForeground = l_getOption("foreground"),
  labelBorderwidth = 2,
  labelRelief = "ridge",
  plotWidth = 200,
  plotHeight = 200,
  sep = "*",
  maxCharInOneRow = 10,
  new.toplevel = TRUE,
  ...
)

Arguments

Return the Displayed Color

Description

Always reflect the current displayed color.

Usage

get_display_color(color, selected)

Arguments

Details

In loon, each element (i.e. point, bin, line) has a "temporary" color and a "permanent" color. If one element is selected, the color is switched to the "temporary" color to highlight it. If the selection state is eliminated, the "permanent" color of this element will be displayed. Our function always gives the "temporary" displayed color.

Value

The color shown on the plot

Examples

if(interactive()) {
  p <- l_plot(1:10)
  p['selected'][c(1,3,5)] <- TRUE

  displayedColor <- get_display_color(p['color'], p['selected'])
  plot(1:10, bg = as_hex6color(displayedColor), pch = 21)
}

Creates a loon plot for each facet from an existing loon plot.

Description

A generic function used by l_facet when facetting an existing loon plot.

Usage

get_facets(widget, ...)

Arguments

Value

A list containing the named components plots, subtitles, child = child, and new.toplevel containing the facets as plots and other relevant information to construct the facetted plot.

See Also

l_facet

Return Font Information

Description

Return Font Information

Usage

get_font_info_from_tk(tkFont)

Arguments

Value

A list of font information, containing font "family", font "face" and font "size"

Examples

fontscales <- l_getOption("font-scales")
get_font_info_from_tk(fontscales)

Get Layer States

Description

Return the input widget states

Usage

get_layer_states(target, native_unit = TRUE, omit = NULL)

Arguments

Details

get layer states

Examples

if(interactive()){
p <- l_plot(x = c(0,1), y = c(0,1))
l <- l_layer_rectangle(p, x = c(0,0.5), y = c(0, 0.5))
# the coordinates are in `unit`
get_layer_states(p)
# the coordinates are numerical
get_layer_states(p, native_unit = FALSE)
# get `l_layer` state
get_layer_states(l)
}

Get the Order of the Display

Description

In loon, if points (in scatter plot) or lines (in parallel or radial coordinate) are highlighted, the displayed order will be changed. This function always reflects the current displayed order

Usage

get_model_display_order(widget)

Arguments

Examples

if(interactive()) {
  p <- l_plot(rnorm(10))
  get_model_display_order(p)
  p['selected'][c(1,3,5,7)] <- TRUE
  # The 1st, 3rd, 5th, 7th points will be drawn afterwards
  # to make sure that they are displayed on top
  get_model_display_order(p)
}

Glyph to Pch

Description

turn a loon point glyph to an R graphics plotting 'character' (pch)

Usage

glyph_to_pch(glyph)

Arguments

Value

a pch type

Examples

glyph_to_pch(c("circle", "ocircle", "ccircle",
               "square", "osquare", "csquare",
               "triangle", "otriangle", "ctriangle",
               "diamond", "cdiamond", "odiamond",
               "foo"))

Make each space in a node apprear only once

Description

Reduce a graph to have unique node names

Usage

graphreduce(graph, separator)

Arguments

Details

Note this is a string based operation. Node names must not contain the separator character!

Value

graph object of class loongraph

Examples

G <- completegraph(nodes=LETTERS[1:4])
LG <- linegraph(G)

LLG <- linegraph(LG)

R_LLG <- graphreduce(LLG)

Create and optionally draw a grid grob from a loon widget handle

Description

Create and optionally draw a grid grob from a loon widget handle

Usage

grid.loon(target, name = NULL, gp = gpar(), draw = TRUE, vp = NULL)

Arguments

Value

a grid grob of the loon plot

See Also

loonGrob, plot.loon

Examples

## Not run: 
library(grid)
widget <- with(iris, l_plot(Sepal.Length, Sepal.Width))
grid.loon(widget)

## End(Not run)

Convert 12 hexadecimal digit color representations to 6 hexidecimal digit color representations

Description

Tk colors must be in 6 hexadecimal format with two hexadecimal digits for each of the red, green, and blue components. Twelve hexadecimal digit colors have 4 hexadecimal digits for each. This function converts the 12 digit format to the 6 provided the color is preserved.

Usage

hex12tohex6(x)

Arguments

Details

Function throws a warning if the conversion loses information. The l_hexcolor function converts any Tcl color specification to a 12 digit hexadecimal color representation.

Examples

x <- l_hexcolor(c("red", "green", "blue", "orange"))
x
hex12tohex6(x)

Convert an R list to a nested Tcl list

Description

This is a helper function to create a nested Tcl list from an R list (i.e. a list of vectors).

Usage

l_Rlist2nestedTclList(x)

Arguments

Value

a string that represents the tcl nested list

See Also

l_nestedTclList2Rlist

Examples

x <- list(c(1,3,4), c(4,3,2,1), c(4,3,2,5,6))
l_Rlist2nestedTclList(x)

Evaluate a function on once the processor is idle

Description

It is possible for an observer to call the configure method of that plot while the plot is still in the configuration pipeline. In this case, a warning is thrown as unwanted side effects can happen if the next observer in line gets an outdated notification. In this case, it is recommended to use the l_after_idle function that evaluates some code once the processor is idle.

Usage

l_after_idle(fun)

Arguments

Query the aspect ratio of a plot

Description

The aspect ratio is defined by the ratio of the number of pixels for one data unit on the y axis and the number of pixels for one data unit on the x axes.

Usage

l_aspect(widget)

Arguments

Value

aspect ratio

Examples

## Not run: 
p <- with(iris, l_plot(Sepal.Length ~ Sepal.Width, color=Species))

l_aspect(p)
l_aspect(p) <- 1

## End(Not run)

Set the aspect ratio of a plot

Description

The aspect ratio is defined by the ratio of the number of pixels for one data unit on the y axis and the number of pixels for one data unit on the x axes.

Usage

l_aspect(widget) <- value

Arguments

Details

Changing the aspect ratio with l_aspect<- changes effectively the zoomY state to obtain the desired aspect ratio. Note that the aspect ratio in loon depends on the plot width, plot height and the states zoomX, zoomY, deltaX, deltaY and swapAxes. Hence, the aspect aspect ratio can not be set permanently for a loon plot.

Examples

## Not run: 
p <- with(iris, l_plot(Sepal.Length ~ Sepal.Width, color=Species))

l_aspect(p)
l_aspect(p) <- 1

## End(Not run)

Get the set of basic path types for loon plots.

Description

Loon's plots are constructed in TCL and identified with a path string appearing in the window containing the plot. The path string begins with a unique identifier for the plot and ends with a suffix describing the type of loon plot being displayed.

The path identifying the plot is the string concatenation of both the identifier and the type.

This function returns the set of the base (non-compound) loon path types.

Usage

l_basePaths()

Value

character vector of the base path types.

See Also

l_compoundPaths l_getFromPath l_loonWidgets

Get labels for each observation according to bin cuts in the histogram.

Description

l_binCut divides l_hist widget x into current histogram intervals and codes values x according to which interval they fall (if active). It is modelled on cut in base package.

Usage

l_binCut(widget, labels, digits = 2, inactive)

Arguments

Value

A vector of bin identifiers having length equal to the total number of observations in the histogram. The type of vector depends on the labels argument. For default labels = NULL, a factor is returned, for labels = FALSE, a vector of bin numbers, and for arbitrary vector labels a vector of bins labelled in order of labels will be returned. Inactive cases appear in no bin and so are assigned the value of active when given. The default active value also depends on labels: when labels = NULL, the default active is "(-Inf, Inf)"; when labels = FALSE, the default active is -1; and when labels is a vector of length equal to the number of bins, the default active is NA. The value of active denotes the bin name for the inactive cases.

See Also

l_getBinData, l_getBinIds, l_breaks

Examples

if(interactive()) {
h <- l_hist(iris)
h["active"] <- iris$Species != "setosa"
binCut <- l_binCut(h)
h['color'] <- binCut
## number of bins
nBins <- length(l_getBinIds(h))
## ggplot color hue
gg_color_hue <- function(n) {
  hues <- seq(15, 375, length = n + 1)
  hcl(h = hues, l = 65, c = 100)[1:n]
}
h['color'] <- l_binCut(h, labels = gg_color_hue(nBins), inactive = "firebrick")
h["active"] <- TRUE
}

Create a Canvas Binding

Description

Canvas bindings are triggered by a mouse/keyboard gesture over the plot as a whole.

Usage

l_bind_canvas(widget, event, callback)

Arguments

Details

Canvas bindings are used to evaluate callbacks at certain X events on the canvas widget (underlying widget for all of loon's plot widgets). Such X events include re-sizing of the canvas and entering the canvas with the mouse.

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

canvas binding id

See Also

l_bind_canvas_ids, l_bind_canvas_get, l_bind_canvas_delete, l_bind_canvas_reorder

Examples

# binding for when plot is resized
if(interactive()){
p <- l_plot(iris[,1:2], color=iris$Species)

printSize <- function(p) {
    size <- l_size(p)
    cat(paste('Size of widget ', p, ' is: ',
              size[1], 'x', size[2], ' pixels\n', sep=''))
}

l_bind_canvas(p, event='<Configure>', function(W) {printSize(W)})

id <- l_bind_canvas_ids(p)
id

l_bind_canvas_get(p, id)

}

Delete a canvas binding

Description

Remove a canvas binding

Usage

l_bind_canvas_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_canvas, l_bind_canvas_ids, l_bind_canvas_get, l_bind_canvas_reorder

Get the event pattern and callback Tcl code of a canvas binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_canvas_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_canvas, l_bind_canvas_ids, l_bind_canvas_delete, l_bind_canvas_reorder

Examples

# binding for when plot is resized
if(interactive()){
p <- l_plot(iris[,1:2], color=iris$Species)

printSize <- function(p) {
    size <- l_size(p)
    cat(paste('Size of widget ', p, ' is: ',
              size[1], 'x', size[2], ' pixels\n', sep=''))
}

l_bind_canvas(p, event='<Configure>', function(W) {printSize(W)})

id <- l_bind_canvas_ids(p)
id

l_bind_canvas_get(p, id)

}

List canvas binding ids

Description

List all user added canvas binding ids

Usage

l_bind_canvas_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with canvas binding ids

See Also

l_bind_canvas, l_bind_canvas_get, l_bind_canvas_delete, l_bind_canvas_reorder

Examples

# binding for when plot is resized
if(interactive()){
p <- l_plot(iris[,1:2], color=iris$Species)

printSize <- function(p) {
    size <- l_size(p)
    cat(paste('Size of widget ', p, ' is: ',
              size[1], 'x', size[2], ' pixels\n', sep=''))
}

l_bind_canvas(p, event='<Configure>', function(W) {printSize(W)})

id <- l_bind_canvas_ids(p)
id

l_bind_canvas_get(p, id)

}

Reorder the canvas binding evaluation sequence

Description

The order the canvas bindings defines how they get evaluated once an event matches event patterns of multiple canvas bindings.

Usage

l_bind_canvas_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_canvas, l_bind_canvas_ids, l_bind_canvas_get, l_bind_canvas_delete

Add a context binding

Description

Creates a binding that evaluates a callback for particular changes in the collection of contexts of a display.

Usage

l_bind_context(widget, event, callback)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

context binding id

See Also

l_bind_context_ids, l_bind_context_get, l_bind_context_delete, l_bind_context_reorder

Delete a context binding

Description

Remove a context binding

Usage

l_bind_context_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_context, l_bind_context_ids, l_bind_context_get, l_bind_context_reorder

Get the event pattern and callback Tcl code of a context binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_context_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_context, l_bind_context_ids, l_bind_context_delete, l_bind_context_reorder

List context binding ids

Description

List all user added context binding ids

Usage

l_bind_context_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with context binding ids

See Also

l_bind_context, l_bind_context_get, l_bind_context_delete, l_bind_context_reorder

Reorder the context binding evaluation sequence

Description

The order the context bindings defines how they get evaluated once an event matches event patterns of multiple context bindings.

Usage

l_bind_context_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_context, l_bind_context_ids, l_bind_context_get, l_bind_context_delete

Add a glyph binding

Description

Creates a binding that evaluates a callback for particular changes in the collection of glyphs of a display.

Usage

l_bind_glyph(widget, event, callback)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

glyph binding id

See Also

l_bind_glyph_ids, l_bind_glyph_get, l_bind_glyph_delete, l_bind_glyph_reorder

Delete a glyph binding

Description

Remove a glyph binding

Usage

l_bind_glyph_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_glyph, l_bind_glyph_ids, l_bind_glyph_get, l_bind_glyph_reorder

Get the event pattern and callback Tcl code of a glyph binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_glyph_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_glyph, l_bind_glyph_ids, l_bind_glyph_delete, l_bind_glyph_reorder

List glyph binding ids

Description

List all user added glyph binding ids

Usage

l_bind_glyph_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with glyph binding ids

See Also

l_bind_glyph, l_bind_glyph_get, l_bind_glyph_delete, l_bind_glyph_reorder

Reorder the glyph binding evaluation sequence

Description

The order the glyph bindings defines how they get evaluated once an event matches event patterns of multiple glyph bindings.

Usage

l_bind_glyph_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_glyph, l_bind_glyph_ids, l_bind_glyph_get, l_bind_glyph_delete

Create a Canvas Binding

Description

Canvas bindings are triggered by a mouse/keyboard gesture over the plot as a whole.

Usage

l_bind_item(widget, tags, event, callback)

Arguments

Details

Item bindings are used for evaluating callbacks at certain mouse and/or keyboard gestures events (i.e. X events) on visual items on the canvas. Items on the canvas can have tags and item bindings are specified to be evaluated at certain X events for items with specific tags.

Note that item bindings get currently evaluated in the order that they are added.

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

item binding id

See Also

l_bind_item_ids, l_bind_item_get, l_bind_item_delete, l_bind_item_reorder

Delete a item binding

Description

Remove a item binding

Usage

l_bind_item_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_item, l_bind_item_ids, l_bind_item_get, l_bind_item_reorder

Get the event pattern and callback Tcl code of a item binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_item_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_item, l_bind_item_ids, l_bind_item_delete, l_bind_item_reorder

List item binding ids

Description

List all user added item binding ids

Usage

l_bind_item_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with item binding ids

See Also

l_bind_item, l_bind_item_get, l_bind_item_delete, l_bind_item_reorder

Reorder the item binding evaluation sequence

Description

The order the item bindings defines how they get evaluated once an event matches event patterns of multiple item bindings.

Reordering item bindings has currently no effect. Item bindings are evaluated in the order in which they have been added.

Usage

l_bind_item_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_item, l_bind_item_ids, l_bind_item_get, l_bind_item_delete

Add a layer binding

Description

Creates a binding that evaluates a callback for particular changes in the collection of layers of a display.

Usage

l_bind_layer(widget, event, callback)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

layer binding id

See Also

l_bind_layer_ids, l_bind_layer_get, l_bind_layer_delete, l_bind_layer_reorder

Delete a layer binding

Description

Remove a layer binding

Usage

l_bind_layer_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_layer, l_bind_layer_ids, l_bind_layer_get, l_bind_layer_reorder

Get the event pattern and callback Tcl code of a layer binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_layer_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_layer, l_bind_layer_ids, l_bind_layer_delete, l_bind_layer_reorder

List layer binding ids

Description

List all user added layer binding ids

Usage

l_bind_layer_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with layer binding ids

See Also

l_bind_layer, l_bind_layer_get, l_bind_layer_delete, l_bind_layer_reorder

Reorder the layer binding evaluation sequence

Description

The order the layer bindings defines how they get evaluated once an event matches event patterns of multiple layer bindings.

Usage

l_bind_layer_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_layer, l_bind_layer_ids, l_bind_layer_get, l_bind_layer_delete

Add a navigator binding

Description

Creates a binding that evaluates a callback for particular changes in the collection of navigators of a display.

Usage

l_bind_navigator(widget, event, callback)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

navigator binding id

See Also

l_bind_navigator_ids, l_bind_navigator_get, l_bind_navigator_delete, l_bind_navigator_reorder

Delete a navigator binding

Description

Remove a navigator binding

Usage

l_bind_navigator_delete(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_navigator, l_bind_navigator_ids, l_bind_navigator_get, l_bind_navigator_reorder

Get the event pattern and callback Tcl code of a navigator binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_navigator_get(widget, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_navigator, l_bind_navigator_ids, l_bind_navigator_delete, l_bind_navigator_reorder

List navigator binding ids

Description

List all user added navigator binding ids

Usage

l_bind_navigator_ids(widget)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with navigator binding ids

See Also

l_bind_navigator, l_bind_navigator_get, l_bind_navigator_delete, l_bind_navigator_reorder

Reorder the navigator binding evaluation sequence

Description

The order the navigator bindings defines how they get evaluated once an event matches event patterns of multiple navigator bindings.

Usage

l_bind_navigator_reorder(widget, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_navigator, l_bind_navigator_ids, l_bind_navigator_get, l_bind_navigator_delete

Add a state change binding

Description

The callback of a state change binding is evaluated when certain states change, as specified at binding creation.

Usage

l_bind_state(target, event, callback)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

state change binding id

See Also

l_info_states, l_bind_state_ids, l_bind_state_get, l_bind_state_delete, l_bind_state_reorder

Delete a state binding

Description

Remove a state binding

Usage

l_bind_state_delete(target, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

See Also

l_bind_state, l_bind_state_ids, l_bind_state_get, l_bind_state_reorder

Get the event pattern and callback Tcl code of a state binding

Description

This function returns the registered event pattern and the Tcl callback code that the Tcl interpreter evaluates after a event occurs that matches the event pattern.

Usage

l_bind_state_get(target, id)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

Character vector of length two. First element is the event pattern, the second element is the Tcl callback code.

See Also

l_bind_state, l_bind_state_ids, l_bind_state_delete, l_bind_state_reorder

List state binding ids

Description

List all user added state binding ids

Usage

l_bind_state_ids(target)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with state binding ids

See Also

l_bind_state, l_bind_state_get, l_bind_state_delete, l_bind_state_reorder

Reorder the state binding evaluation sequence

Description

The order the state bindings defines how they get evaluated once an event matches event patterns of multiple state bindings.

Usage

l_bind_state_reorder(target, ids)

Arguments

Details

Bindings, callbacks, and binding substitutions are described in detail in loon's documentation webpage, i.e. run l_help("learn_R_bind")

Value

vector with binding id evaluation order (same as the id argument)

See Also

l_bind_state, l_bind_state_ids, l_bind_state_get, l_bind_state_delete

Gets the boundaries of the histogram bins containing active points.

Description

Queries the histogram and returns the ids of all active points in each bin that contains active points.

Usage

l_breaks(widget)

Arguments

Value

A named list of the minimum and maximum values of the boundaries for each active bins in the histogram.

See Also

l_getBinData, l_getBinIds, l_binCut

Query a Plot State

Description

All of loon's displays have plot states. Plot states specify what is displayed, how it is displayed and if and how the plot is linked with other loon plots. Layers, glyphs, navigators and contexts have states too (also refered to as plot states). This function queries a single plot state.

Usage

l_cget(target, state)

Arguments

See Also

l_configure, l_info_states, l_create_handle

Examples

if(interactive()){

p <- l_plot(iris, color = iris$Species)
l_cget(p, "color")
p['selected']
}

Convert color representations having an alpha transparency level to 6 digit color representations

Description

Colors in the standard tk used by loon do not allow for alpha transparency. This function allows loon to use color palettes (e.g. l_setColorList) that produce colors with alpha transparency by simply using only the rgb.

Usage

l_colRemoveAlpha(col)

Arguments

Examples

x <- l_colRemoveAlpha(rainbow(6))
# Also works with ordinary color string representations
# since it just extracts the rgb values from the colors.
x <- l_colRemoveAlpha(c("red", "blue", "green", "orange"))
x

Get Color Names from the Hex Code

Description

Return the built-in color names by the given hex code.

Usage

l_colorName(color, error = TRUE, precise = FALSE)

Arguments

Details

Function colors returns the built-in color names which R knows about. To convert a hex code to a real color name, we first convert these built-in colours and the hex code to RGB (red/green/blue) values (e.g., "black" –> [0, 0, 0]). Then, using this RGB vector value, the closest (Euclidean distance) built-in colour is determined.

Matching is "precise" whenever the minimum distance is zero; otherwise it is "approximate", locating the nearest R colour.

Value

A vector of built-in color names

See Also

l_hexcolor, hex12tohex6, as_hex6color

Examples

l_colorName(c("#FFFF00000000", "#FF00FF", "blue"))

if(require(grid)) {
# redGradient is a matrix of 20 different colors
redGradient <- matrix(hcl(0, 80, seq(49, 68, 1)),
                      nrow=4, ncol=5, byrow = TRUE)
# a color plate
grid::grid.newpage()
grid::grid.raster(redGradient,
                  interpolate = FALSE)

# a "rough matching";
r <- l_colorName(redGradient)
# the color name of each row is identical...
r
grid::grid.newpage()
# very different from the first plate
grid::grid.raster(r, interpolate = FALSE)

# a "precise matching";
p <- l_colorName(redGradient, precise = TRUE)
# no built-in color names can be precisely matched...
p
}
## Not run: 
# an error will be returned
l_colorName(c("foo", "bar", "red"))

# c("foo", "bar", "red") will be returned
l_colorName(c("foo", "bar", "#FFFF00000000"), error = FALSE)

## End(Not run)

Get the set of basic path types for loon plots.

Description

Loon's plots are constructed in TCL and identified with a path string appearing in the window containing the plot. The path string begins with a unique identifier for the plot and ends with a suffix describing the type of loon plot being displayed.

The path identifying the plot is the string concatenation of both the identifier and the type.

This function returns the set of the loon path types for compound loon plots.

Usage

l_compoundPaths()

Value

character vector of the compound path types.

See Also

l_basePathsl_loonWidgets l_getFromPath

Modify one or multiple plot states

Description

All of loon's displays have plot states. Plot states specify what is displayed, how it is displayed and if and how the plot is linked with other loon plots. Layers, glyphs, navigators and contexts have states too (also refered to as plot states). This function modifies one or multiple plot states.

Usage

l_configure(target, ...)

Arguments

See Also

l_cget, l_info_states, l_create_handle

Examples

if(interactive()){

p <- l_plot(iris, color = iris$Species)
l_configure(p, color='red')
p['size'] <- ifelse(iris$Species == "versicolor", 2, 8)
}

Create a context2d navigator context

Description

A context2d maps every location on a 2d space graph to a list of xvars and a list of yvars such that, while moving the navigator along the graph, as few changes as possible take place in xvars and yvars.

Contexts are in more detail explained in the webmanual accessible with l_help. Please read the section on context by running l_help("learn_R_display_graph.html#contexts").

Usage

l_context_add_context2d(navigator, ...)

Arguments

Value

context handle

See Also

l_info_states, l_context_ids, l_context_add_geodesic2d, l_context_add_slicing2d, l_context_getLabel, l_context_relabel

Create a geodesic2d navigator context

Description

Geodesic2d maps every location on the graph as an orthogonal projection of the data onto a two-dimensional subspace. The nodes then represent the sub-space spanned by a pair of variates and the edges either a 3d- or 4d-transition of one scatterplot into another, depending on how many variates the two nodes connected by the edge share (see Hurley and Oldford 2011). The geodesic2d context inherits from the context2d context.

Contexts are in more detail explained in the webmanual accessible with l_help. Please read the section on context by running l_help("learn_R_display_graph.html#contexts").

Usage

l_context_add_geodesic2d(navigator, ...)

Arguments

Value

context handle

See Also

l_info_states, l_context_ids, l_context_add_context2d, l_context_add_slicing2d, l_context_getLabel, l_context_relabel

Create a slicind2d navigator context

Description

The slicing2d context implements slicing using navigation graphs and a scatterplot to condition on one or two variables.

Contexts are in more detail explained in the webmanual accessible with l_help. Please read the section on context by running l_help("learn_R_display_graph.html#contexts").

Usage

l_context_add_slicing2d(navigator, ...)

Arguments

Value

context handle

Examples

if(interactive()){

names(oliveAcids) <- c('p','p1','s','o','l','l1','a','e')
nodes <- apply(combn(names(oliveAcids),2),2,
              function(x)paste(x, collapse=':'))
G <- completegraph(nodes)
g <- l_graph(G)
nav <- l_navigator_add(g)
con <- l_context_add_slicing2d(nav, data=oliveAcids)

# symmetric range proportion around nav['proportion']
con['proportion'] <- 0.2

con['conditioning4d'] <- "union"
con['conditioning4d'] <- "intersection"
}

Delete a context from a navigator

Description

Navigators can have multiple contexts. This function removes a context from a navigator.

Usage

l_context_delete(navigator, id)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#contexts")

See Also

l_context_ids, l_context_add_context2d, l_context_add_geodesic2d, l_context_add_slicing2d, l_context_getLabel, l_context_relabel

Query the label of a context

Description

Context labels are eventually used in the context inspector. This function queries the label of a context.

Usage

l_context_getLabel(navigator, id)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#contexts")

See Also

l_context_getLabel, l_context_add_context2d, l_context_add_geodesic2d, l_context_add_slicing2d, l_context_delete

List context ids of a navigator

Description

Navigators can have multiple contexts. This function list the context ids of a navigator.

Usage

l_context_ids(navigator)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#contexts")

See Also

l_context_delete, l_context_add_context2d, l_context_add_geodesic2d, l_context_add_slicing2d, l_context_getLabel, l_context_relabel

Change the label of a context

Description

Context labels are eventually used in the context inspector. This function relabels a context.

Usage

l_context_relabel(navigator, id, label)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#contexts")

See Also

l_context_getLabel, l_context_add_context2d, l_context_add_geodesic2d, l_context_add_slicing2d, l_context_delete

A generic function to transfer the values of the states of one 'loon' structure to another.

Description

l_copyStates reads the values of the states of the 'source' and assigns them to the states of the same name on the 'target'.

Usage

l_copyStates(
  source,
  target,
  states = NULL,
  exclude = NULL,
  excludeBasicStates = TRUE,
  returnNames = FALSE
)

Arguments

Value

a character vector of the names of the states successfully copied (for each plot whose states were affected), or NULL if none were copied or 'returnNames == FALSE'.

See Also

l_saveStates l_info_states saveRDS

Examples

if(interactive()){
# Source and target are `l_plots`
   p <- with(iris,
         l_plot(x = Sepal.Width, y = Petal.Width,
                color = Species, glyph = "ccircle",
                size = 10, showGuides = TRUE,
                title = "Edgar Anderson's Iris data"
               )
           )

   p2 <- with(iris,
          l_plot(x = Sepal.Length, y = Petal.Length,
                 title = "Fisher's Iris data"
                 )
              )
# Copy the states of p to p2
# First just the size and title
   l_copyStates(source = p, target = p2,
                states = c("size", "title")
                )
# Copy all but those associated with the variables
   l_copyStates(source = p, target = p2)

# Suppose p had a linkingGroup, say "Edgar"
   l_configure(p, linkingGroup = "Edgar", sync = "push")

# To force this linkingGroup to be copied to a new plot
   p3 <- with(iris,
          l_plot(x = Sepal.Length, y = Petal.Length,
                 title = "Fisher's Iris data"
                 )
              )
   l_copyStates(source = p, target = p3,
                states = c("linkingGroup"),
                # To allow this to happen:
                excludeBasicStates = FALSE
                )

   h <- with(iris,
             l_hist((Petal.Width * Petal.Length),
                    showStackedColors = TRUE,
                    yshows = "density")
                    )
   l_copyStates(source = p, target = h)

   sa <- l_serialaxes(iris, axes = "parallel")
   l_copyStates(p, sa)

   pp <- l_pairs(iris, showHistograms = TRUE)
   suppressWarnings(l_copyStates(p, pp))

   pp2 <- l_pairs(iris,
                  color = iris$Species,
                  showGuides = TRUE,
                  title ="Iris data",
                  glyph = "ctriangle")
   l_copyStates(pp2, pp)
   l_copyStates(pp2, p)
}

For the target compound loon plot, creates the final grob from the class of the 'target' and the 'arrangeGrob.args'

Description

For the target compound loon plot, creates the final grob from the class of the 'target' and the 'arrangeGrob.args'

Usage

l_createCompoundGrob(target, arrangeGrob.args)

Arguments

Value

a grob (or list of grobs) that can be handed to 'gTree()' as 'children = gList(returnedValue)' as the final grob constructed for the compound loon plot. Default for an 'l_compound' is to simply execute 'gridExtra::arrangeGrob(arrangeGrob.args)'.

Create a loon object handle

Description

This function can be used to create the loon object handles from a vector of the widget path name and the object ids (in the order of the parent-child relationships).

Usage

l_create_handle(target)

Arguments

Details

loon's plot handles are useful to query and modify plot states via the command line.

For more information run: l_help("learn_R_intro.html#re-creating-object-handles")

See Also

l_getFromPath

Examples

if(interactive()){


# plot handle
p <- l_plot(x=1:3, y=1:3)
p_new <- l_create_handle(unclass(p))
p_new['showScales']

# glyph handle
gl <- l_glyph_add_text(p, text=LETTERS[1:3])
gl_new <- l_create_handle(c(as.vector(p), as.vector(gl)))
gl_new['text']

# layer handle
l <- l_layer_rectangle(p, x=c(1,3), y=c(1,3), color='yellow', index='end')
l_new <- l_create_handle(c(as.vector(p), as.vector(l)))
l_new['color']

# navigator handle
g <- l_graph(linegraph(completegraph(LETTERS[1:3])))
nav <- l_navigator_add(g)
nav_new <- l_create_handle(c(as.vector(g), as.vector(nav)))
nav_new['from']

# context handle
con <- l_context_add_context2d(nav)
con_new <- l_create_handle(c(as.vector(g), as.vector(nav), as.vector(con)))
con_new['separator']

}

Get layer-relative index of the item below the mouse cursor

Description

Checks if there is a visual item below the mouse cursor and if there is, it returns the index of the visual item's position in the corresponding variable dimension of its layer.

Usage

l_currentindex(widget)

Arguments

Details

For more details see l_help("learn_R_bind.html#item-bindings")

Value

index of the visual item's position in the corresponding variable dimension of its layer

See Also

l_bind_item, l_currenttags

Examples

if(interactive()){

p <- l_plot(iris[,1:2], color=iris$Species)

printEntered <- function(W) {
    cat(paste('Entered point ', l_currentindex(W), '\n'))
}

printLeave <- function(W) {
    cat(paste('Left point ', l_currentindex(W), '\n'))
}

l_bind_item(p, tags='model&&point', event='<Enter>',
            callback=function(W) {printEntered(W)})

l_bind_item(p, tags='model&&point', event='<Leave>',
            callback=function(W) {printLeave(W)})

}

Get tags of the item below the mouse cursor

Description

Retrieves the tags of the visual item that at the time of the function evaluation is below the mouse cursor.

Usage

l_currenttags(widget)

Arguments

Details

For more details see l_help("learn_R_bind.html#item-bindings")

Value

vector with item tags of visual

See Also

l_bind_item, l_currentindex

Examples

if(interactive()){

printTags <- function(W) {
    print(l_currenttags(W))
}

p <- l_plot(x=1:3, y=1:3, title='Query Visual Item Tags')

l_bind_item(p, 'all', '<ButtonPress>', function(W)printTags(W))
}

Convert an R data.frame to a Tcl dictionary

Description

This is a helper function to convert an R data.frame object to a Tcl data frame object. This function is useful when changing a data state with l_configure.

Usage

l_data(data)

Arguments

Value

a string that represents with data.frame with a Tcl dictionary data structure.

Export a loon plot as an image

Description

The supported image formats depend on your system and Tcl/Tk configuration. Export to PostScript ('.ps', '.eps') always works. Export to PDF ('.pdf') works if the command-line tool 'epstopdf' is installed. Export to bitmap formats such as '.png', '.jpg', '.bmp', '.tiff', or '.gif' may work if supported by your Tcl/Tk environment — this often, but not always, requires the Img Tcl extension.

If a selected format fails, use '.ps' or consider capturing a screenshot.

Usage

l_export(widget, filename, width, height)

Arguments

Details

Pressing 'Ctrl-P' in a loon plot window also opens an interactive export dialog.

Value

The file path of the exported image.

See Also

l_export_valid_formats, plot.loon

Return a list of the available image formats when exporting a loon plot

Description

The supported image formats are dependent on the system environment. Plots can always be exported to the Postscript format. Exporting displays as .pdfs is only possible when the command line tool epstopdf is installed. Finally, exporting to either png, jpg, bmp, tiff or gif requires the Img Tcl extension. When choosing one of the formats that depend on the Img extension, it is possible to export any Tk widget as an image including inspectors.

Usage

l_export_valid_formats()

Value

a vector with the image formats available for exporting a loon plot.

Layout Facets across multiple panels

Description

It takes a loon widget and forms a matrix of loon widget facets.

Usage

l_facet(widget, by, on, layout = c("grid", "wrap", "separate"), ...)

## S3 method for class 'loon'
l_facet(
  widget,
  by,
  on,
  layout = c("grid", "wrap", "separate"),
  connectedScales = c("cross", "row", "column", "both", "x", "y", "none"),
  linkingGroup,
  nrow = NULL,
  ncol = NULL,
  inheritLayers = TRUE,
  labelLocation = c("top", "right"),
  labelBackground = "gray80",
  labelForeground = "black",
  labelBorderwidth = 2,
  labelRelief = c("groove", "flat", "raised", "sunken", "ridge", "solid"),
  plotWidth = 200,
  plotHeight = 200,
  parent = NULL,
  ...
)

## S3 method for class 'l_serialaxes'
l_facet(
  widget,
  by,
  on,
  layout = c("grid", "wrap", "separate"),
  linkingGroup,
  nrow = NULL,
  ncol = NULL,
  labelLocation = c("top", "right"),
  labelBackground = "gray80",
  labelForeground = "black",
  labelBorderwidth = 2,
  labelRelief = c("groove", "flat", "raised", "sunken", "ridge", "solid"),
  plotWidth = 200,
  plotHeight = 200,
  parent = NULL,
  ...
)

Arguments

Value

an 'l_facet' object (an 'l_compound' object), being a list with named elements, each representing a separate interactive plot. The names of the plots should be self explanatory and a list of all plots can be accessed from the 'l_facet' object via 'l_getPlots()'.

Examples

if(interactive()) {
  library(maps)
  p <- with(quakes, l_plot(long, lat, linkingGroup = "quakes"))
  p["color"][quakes$mag < 5 & quakes$mag >= 4] <- "lightgreen"
  p["color"][quakes$mag < 6 & quakes$mag >= 5] <- "lightblue"
  p["color"][quakes$mag >= 6] <- "firebrick"
  # A Fiji map
  NZFijiMap <- map("world2", regions = c("New Zealand", "Fiji"), plot = FALSE)
  l_layer(p, NZFijiMap,
          label = "New Zealand and Fiji",
          color = "forestgreen",
          index = "end")
  fp <- l_facet(p, by = "color", layout = "grid",
                linkingGroup = "quakes")

  size <- c(rep(50, 2), rep(25, 2), rep(50, 2))
  color <- c(rep("red", 3), rep("green", 3))
  p <- l_plot(x = 1:6, y = 1:6,
              size = size,
              color = color)
  g <- l_glyph_add_text(p, text = 1:6)
  p['glyph'] <- g
  on <- data.frame(Factor1 = c(rep("A", 3), rep("B", 3)),
                   Factor2 = rep(c("C", "D"), 3))
  cbind(on, size = size, color = color)
  fp <- l_facet(p, by = Factor1 ~ Factor2, on = on)
}

if(interactive()) {

# serialaxes facets
s <- l_serialaxes(iris[, -5], color = iris$Species)
fs <- l_facet(s, layout = "wrap", by = iris$Species)
# The linkingGroup can be printed or accessed by
l_configure(s, linkingGroup = fs[[1]]['linkingGroup'], sync = "pull")
}

Get information on current bins from a histogram

Description

Queries the histogram and returns information about all active cases contained by the histogram's bins.

Usage

l_getBinData(widget)

Arguments

Value

A nested list of the bins in the histogram which contain active points. Each bin is a list of the counts, the point indices, and the minimum (x0) and maximum (x1) of that bin. Loon histogram bins are open on the left and closed on the right by default, namely "(x0, x1]". The counts and the points further identify the number and ids of all points, those which are selected, and those of each colour in that bin (identified by their hex12 colour from tcl).

See Also

l_getBinIds, l_breaks, l_binCut

Gets the ids of the active points in each bin of a histogram

Description

Queries the histogram and returns the ids of all active points in each bin that contains active points.

Usage

l_getBinIds(widget)

Arguments

Value

A named list of the bins in the histogram and the ids of their active points.

See Also

l_getBinData, l_breaks, l_binCut

Get loon's color mapping list

Description

The color mapping list is used by loon to convert nominal values to color values, see the documentation for l_setColorList.

Usage

l_getColorList()

Value

a vector with hex-encoded colors

See Also

l_setColorList

A helper function to determine which, if any, linked variables in a plot are now deprecated.

Description

Checks which linkable states are linked, whether their input state is the default one, valid, and equal to the plot current states. It is not intended for the general user.

Usage

l_getDeprecatedLinkedVar(
  widget,
  args,
  modifiedLinkedStates = character(0L),
  l_className = NULL
)

Arguments

Value

a named vector, or list of vectors, of logicals indicating whether these linkable states need be deprecated or not.

Create loon objects from path name

Description

This function can be used to create the loon objects from a valid widget path name. The main difference from l_create_handle is that l_getFromPath can take a loon compound widget path but l_create_handle cannot.

Usage

l_getFromPath(target)

Arguments

Details

For more information run: l_help("learn_R_intro.html#re-creating-object-handles")

See Also

l_create_handle l_loonWidgets

Examples

## Not run: 
 l_pairs(iris, showHistogram = TRUE)
 # The path can be found at the top of tk title
 # Suppose it is the first loon widget, this path should be ".l0.pairs"
 p <- l_create_handle(".l0.pairs") # error
 p <- l_getFromPath(".l0.pairs")

## End(Not run)

Extract a loongraph or graph object from loon's graph display

Description

The graph display represents a graph with the nodes, from, to, and isDirected plot states. This function creates a loongraph or a graph object using these states.

Usage

l_getGraph(widget, asloongraph = TRUE)

Arguments

Value

a loongraph or a graph object

See Also

l_graph, loongraph

Query the States that are Linked with Loon's Standard Linking Model

Description

Loon's standard linking model is based on three levels, the linkingGroup and linkingKey states and the used linkable states. See the details in the documentation for l_setLinkedStates.

Usage

l_getLinkedStates(widget)

Arguments

Value

vector with state names that are linked states

See Also

l_setLinkedStates

For the target compound loon plot, determines location (only and excluding the grobs) arguments to pass to 'gridExtra::arrangeGrob()'

Description

For the target compound loon plot, determines location (only and excluding the grobs) arguments to pass to 'gridExtra::arrangeGrob()'

Usage

l_getLocations(target)

## S3 method for class 'l_facet'
l_getLocations(target)

## S3 method for class 'l_pairs'
l_getLocations(target)

## S3 method for class 'l_ts'
l_getLocations(target)

Arguments

Value

a list of an appropriate subset of the named location arguments 'c("ncol", "nrow", "layout_matrix", "heights", "widths")'. There are as many heights and widths as there are plots returned by l_getPlots(); these specify the relative height and width of each plot in the display. layout_matrix is an nrow by ncol matrix whose entries identify the location of each plot in l_getPlots() by their index.

Examples

if(interactive()) {

pp <- l_pairs(iris, showHistograms = TRUE)
ll <- l_getLocations(pp)
nplots <- length(l_getPlots(pp))
# the plots returned by l_getPlots(pp) are positioned
# in order by the layout_matrix
ll$layout_matrix
}

Get the value of a loon display option

Description

All of loon's displays access a set of common options. This function accesses and returns the current value of the named option.

Usage

l_getOption(option)

Arguments

Value

the value of the named option.

See Also

l_getOptionNames, l_userOptions, l_userOptionDefault, l_setOption

Examples

l_getOption("background")

Get the names of all loon display options

Description

All of loon's displays access a set of common options. This function accesses and returns the names of all loon options.

Usage

l_getOptionNames()

Value

a vector of all loon display option names.

See Also

l_getOption, l_userOptions, l_userOptionDefault, l_setOption

Examples

l_getOptionNames()

For the target compound loon plot, determines all the loon plots in that compound plot.

Description

For the target compound loon plot, determines all the loon plots in that compound plot.

Usage

l_getPlots(target)

## S3 method for class 'l_facet'
l_getPlots(target)

## S3 method for class 'l_pairs'
l_getPlots(target)

## S3 method for class 'l_ts'
l_getPlots(target)

Arguments

Value

a list of the named arguments and their values to be passed to 'gridExtra::arrangeGrob()'.

Retrieve saved plot states from the named file.

Description

l_getSavedStates reads a file created by l_saveStates() containing the saved info states of a loon plot returning a loon object of class "l_savedStates". This is helpful, for example, when using RMarkdown or some other notebooking facility to recreate an earlier saved loon plot so as to present it in the document.

Note that if the plot saved was an "l_compound" then l_getSavedStates will return a list of the plots with each list item being the saved states of the corresponding plots.

Usage

l_getSavedStates(file = stop("missing name of file"), ...)

Arguments

Value

a list of class 'l_savedStates' containing the states and their values. Also has an attribute 'l_plot_class' which contains the class vector of the plot 'p'

See Also

l_getSavedStates l_copyStates l_info_states readRDS saveRDS

Examples

if(interactive()){
#
# Suppose you have some plot that you created like
p <- l_plot(iris, showGuides = TRUE)
#
# and coloured groups by hand (using the mouse and inspector)
# so that you ended up with these colours:
p["color"] <- rep(c( "lightgreen", "firebrick","skyblue"),
                  each = 50)
#
# Having determined the colours you could save them (and other states)
# in a file of your choice, here some tempfile:
myFileName <- tempfile("myPlot", fileext = ".rds")
#
# Save the named states of p
l_saveStates(p,
             states = c("color", "active", "selected"),
             file = myFileName)
#
# These can later be retrieved and used on a new plot
# (say in RMarkdown) to set the new plot's values to those
# previously determined interactively.
p_new <- l_plot(iris, showGuides = TRUE)
p_saved_info <- l_getSavedStates(myFileName)
#
# We can tell what kind of plot was saved
attr(p_saved_info, "l_plot_class")
#
# The result is a list of class "l_savedStates" which
# contains the names of the
p_new["color"] <- p_saved_info$color
#
# The result is that p_new looks like p did
# (after your interactive exploration)
# and can now be plotted as part of the document
plot(p_new)
#
# For compound plots, the info_states are saved for each plot
pp <- l_pairs(iris)
myPairsFile <- tempfile("myPairsPlot", fileext = ".rds")
#
# Save the names states of pp
l_saveStates(pp,
             states = c("color", "active", "selected"),
             file = myPairsFile)
pairs_info <-  l_getSavedStates(myPairsFile)
#
# For compound plots, the info states for all constitutent
# plots are saved.  The result is a list of class "l_savedStates"
# whose elements are the named plots as "l_savedStates"
# themselves.
#
# The names of the plots which were saved
names(pairs_info)
#
# And the names of the info states whose values were saved for
# the first plot
names(pairs_info$x2y1)
#
# While it is generally recommended to access (or assign) saved
# state values using the $ sign accessor, paying attention to the
# nested list structure of an "l_savedStates" object (especially for
# l_compound plots), R's square bracket notation [] has also been
# specialized to allow a syntactically simpler (but less precise)
# access to the contents of an l_savedStates object.
#
# For example,
p_saved_info["color"]
#
# returns the saved "color" as a vector of colours.
#
# In contrast,
pairs_info["x2y1"]
# returns the l_savedStates object of the states of the plot named "x2y1",
# but
pairs_info["color"]
# returns a LIST of colour vectors, by plot as they were named in pairs_info
#
# As a consequence, the following two are equivalent,
pairs_info["x2y1"]["color"]
# finds the value of "color" from an "l_savedStates" object
# whereas
pairs_info["color"][["x2y1"]]
# finds the value of "x2y1" from a "list" object
#
# Also, setting a state of an "l_savedStates" is possible
# (though not generally recommended; better to save the states again)
#
p_saved_info["color"] <- rep("red", 150)
# changes the saved state "color" on p_saved_info
# whereas
pairs_info["color"] <- rep("red", 150)
# will set the red color for any plot within pairs_info having "color" saved.
# In this way the assignment function via [] is trying to be clever
# for l_savedStates for compound plots and so may have unintentional
# consequences if the user is not careful.

# Generally, one does not want/need to change the value of saved states.
# Instead, the states would be saved again from the interactive plot
# if change is necessary.
# Alternatively, more nuanced and careful control is maintained using
# the $ selectors for lists.
}

Data Scaling

Description

Scaling the data set

Usage

l_getScaledData(
  data,
  sequence = NULL,
  scaling = c("variable", "observation", "data", "none"),
  displayOrder = NULL,
  reserve = FALSE,
  as.data.frame = FALSE
)

Arguments

Details

The scaling state defines how the data is scaled. The axes display 0 at one end and 1 at the other. For the following explanation assume that the data is in a nxp dimensional matrix. The scaling options are then

See Also

l_serialaxes

For the target (compound) loon plot, determines all arguments (i.e. including the grobs) to be passed to 'gridExtra::arrangeGrob()' so as to determine the layout in 'grid' graphics.

Description

For the target (compound) loon plot, determines all arguments (i.e. including the grobs) to be passed to 'gridExtra::arrangeGrob()' so as to determine the layout in 'grid' graphics.

Usage

l_get_arrangeGrobArgs(target)

Arguments

Value

a list of the named arguments and their values to be passed to 'gridExtra::arrangeGrob()'.

Add non-primitive glyphs to a scatterplot or graph display

Description

Generic method for adding user-defined glyphs. See details for more information about non-primitive and primitive glyphs.

Usage

l_glyph_add(widget, type, ...)

Arguments

Details

The scatterplot and graph displays both have the n-dimensional state 'glyph' that assigns each data point or graph node a glyph (i.e. a visual representation).

Loon distinguishes between primitive and non-primitive glyphs: the primitive glyphs are always available for use whereas the non-primitive glyphs need to be first specified and added to a plot before they can be used.

The primitive glyphs are:

The non-primitive glyph types and their creator functions are:

When adding non-primitive glyphs to a display, the number of glyphs needs to match the dimension n of the plot. In other words, a glyph needs to be defined for each observations. See in the examples.

Currently loon does not support compound glyphs. However, it is possible to cunstruct an arbitrary glyph using any system and save it as a png and then re-import them as as image glyphs using l_glyph_add_image.

For more information run: l_help("learn_R_display_plot.html#glyphs")

Value

String with glyph id. Every set of non-primitive glyphs has an id (character).

See Also

l_glyph_add_text, l_make_glyphs

Other glyph functions: l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

# Simple Example with Text Glyphs
p <- with(olive, l_plot(stearic, eicosenoic, color=Region))
g <- l_glyph_add_text(p, text=olive$Area, label="Area")
p['glyph'] <- g

## Not run: 
demo("l_glyphs", package="loon")

## End(Not run)

# create a plot that demonstrates the primitive glyphs and the text glyphs
p <- l_plot(x=1:15, y=rep(0,15), size=10, showLabels=FALSE)
text_glyph <- l_glyph_add_text(p, text=letters [1:15])
p['glyph'] <- c(
    'circle', 'ocircle', 'ccircle',
    'square', 'osquare' , 'csquare',
    'triangle', 'otriangle', 'ctriangle',
    'diamond', 'odiamond', 'cdiamond',
    rep(text_glyph, 3)
)
}

Default method for adding non-primitive glyphs

Description

Generic function to write new glyph types using loon's primitive glyphs

Usage

## Default S3 method:
l_glyph_add(widget, type, label = "", ...)

Arguments

See Also

Other glyph functions: l_glyph_add(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Add an image glyphs

Description

Image glyphs are useful to show pictures or other sophisticated compound glyphs. Note that images in the Tk canvas support transparancy.

Usage

l_glyph_add_image(widget, images, label = "", ...)

Arguments

Details

For more information run: l_help("learn_R_display_plot.html#images")

See Also

l_glyph_add, l_image_import_array, l_image_import_files, l_make_glyphs

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

p <- with(olive, l_plot(palmitic ~ stearic, color = Region))
img_paths <- list.files(file.path(find.package(package = 'loon'), "images"), full.names = TRUE)
imgs <- setNames(l_image_import_files(img_paths),
                 tools::file_path_sans_ext(basename(img_paths)))
i <- pmatch(gsub("^[[:alpha:]]+-","", olive$Area), names(imgs), duplicates.ok = TRUE)

g <- l_glyph_add_image(p, imgs[i], label="Flags")
p['glyph'] <- g
}

Add a Pointrange Glyph

Description

Pointrange glyphs show a filled circle at the x-y location and also a y-range.

Usage

l_glyph_add_pointrange(
  widget,
  ymin,
  ymax,
  linewidth = 1,
  showArea = TRUE,
  label = "",
  ...
)

Arguments

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

p <- l_plot(x = 1:3, color = c('red', 'blue', 'green'), showScales=TRUE)
g <- l_glyph_add_pointrange(p, ymin=(1:3)-(1:3)/5, ymax=(1:3)+(1:3)/5)
p['glyph'] <- g
}

Add a Polygon Glyph

Description

Add one polygon per scatterplot point.

Usage

l_glyph_add_polygon(
  widget,
  x,
  y,
  linewidth = 1,
  showArea = TRUE,
  label = "",
  ...
)

Arguments

Details

A polygon can be a useful point glyph to visualize arbitrary shapes such as airplanes, animals and shapes that are not available in the primitive glyph types (e.g. cross). The l_glyphs demo has an example of polygon glyphs which we reuse here.

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

x_star <-
    c(-0.000864304235090734, 0.292999135695765, 0.949870354364736,
      0.474503025064823, 0.586862575626621, -0.000864304235090734,
      -0.586430423509075, -0.474070872947277, -0.949438202247191,
      -0.29256698357822)
y_star <-
    c(-1, -0.403630077787381, -0.308556611927398, 0.153846153846154,
      0.808556611927398, 0.499567847882455, 0.808556611927398,
      0.153846153846154, -0.308556611927398, -0.403630077787381)
x_cross <-
    c(-0.258931143762604, -0.258931143762604, -0.950374531835206,
      -0.950374531835206, -0.258931143762604, -0.258931143762604,
      0.259651397291847, 0.259651397291847, 0.948934024776722,
      0.948934024776722, 0.259651397291847, 0.259651397291847)
y_cross <-
    c(-0.950374531835206, -0.258931143762604, -0.258931143762604,
      0.259651397291847, 0.259651397291847, 0.948934024776722,
      0.948934024776722, 0.259651397291847, 0.259651397291847,
      -0.258931143762604, -0.258931143762604, -0.950374531835206)
x_hexagon <-
    c(0.773552290406223, 0, -0.773552290406223, -0.773552290406223,
      0, 0.773552290406223)
y_hexagon <-
    c(0.446917314894843, 0.894194756554307, 0.446917314894843,
      -0.447637568424085, -0.892754249495822, -0.447637568424085)

p <- l_plot(1:3, 1:3)

gl <- l_glyph_add_polygon(p, x = list(x_star, x_cross, x_hexagon),
                          y = list(y_star, y_cross, y_hexagon))

p['glyph'] <- gl

gl['showArea'] <- FALSE
}

Add a Serialaxes Glyph

Description

Serialaxes glyph show either a star glyph or a parallel coordinate glyph for each point.

Usage

l_glyph_add_serialaxes(
  widget,
  data,
  sequence,
  linewidth = 1,
  scaling = "variable",
  axesLayout = "radial",
  showAxes = FALSE,
  andrews = FALSE,
  axesColor = "gray70",
  showEnclosing = FALSE,
  bboxColor = "gray70",
  label = "",
  ...
)

Arguments

See Also

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

p <- with(olive, l_plot(oleic, stearic, color=Area))
gs <- l_glyph_add_serialaxes(p, data=olive[,-c(1,2)], showArea=FALSE)
p['glyph'] <- gs
}

Add a Text Glyph

Description

Each text glyph can be a multiline string.

Usage

l_glyph_add_text(widget, text, label = "", ...)

Arguments

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Examples

if(interactive()){

p <- l_plot(iris, color = iris$Species)
g <- l_glyph_add_text(p, iris$Species, "test_label")
p['glyph'] <- g
}

Delete a Glyph

Description

Delete a glyph from the plot.

Usage

l_glyph_delete(widget, id)

Arguments

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Get Glyph Label

Description

Returns the label of a glyph

Usage

l_glyph_getLabel(widget, id)

Arguments

See Also

l_glyph_add, l_glyph_ids, l_glyph_relabel

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getType(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

Get Glyph Type

Description

Query the type of a glyph

Usage

l_glyph_getType(widget, id)

Arguments

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_ids(), l_glyph_relabel(), l_primitiveGlyphs()

List glyphs ids

Description

List all the non-primitive glyph ids attached to display.

Usage

l_glyph_ids(widget)

Arguments

See Also

l_glyph_add

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_relabel(), l_primitiveGlyphs()

Relabel Glyph

Description

Change the label of a glyph. Note that the label is only displayed in the glyph inspector.

Usage

l_glyph_relabel(widget, id, label)

Arguments

See Also

Other glyph functions: l_glyph_add(), l_glyph_add.default(), l_glyph_add_image(), l_glyph_add_pointrange(), l_glyph_add_polygon(), l_glyph_add_serialaxes(), l_glyph_add_text(), l_glyph_delete(), l_glyph_getLabel(), l_glyph_getType(), l_glyph_ids(), l_primitiveGlyphs()

Examples

if(interactive()){

p <- l_plot(iris, color = iris$Species)
g <- l_glyph_add_text(p, iris$Species, "test_label")
p['glyph'] <- g
l_glyph_relabel(p, g, "Species")
}

Create a Glyphs Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_glyphs_inspector(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_glyphs_inspector()
}

Create a Image Glyph Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_glyphs_inspector_image(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_glyphs_inspector_image()
}

Create a Pointrange Glyph Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_glyphs_inspector_pointrange(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_glyphs_inspector_pointrange()
}

Create a Serialaxes Glyph Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_glyphs_inspector_serialaxes(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_glyphs_inspector_serialaxes()
}

Create a Text Glyph Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_glyphs_inspector_text(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_glyphs_inspector_text()
}

Generic funtction to create an interactive graph display

Description

Interactive graphs in loon are currently most often used for navigation graphs.

Usage

l_graph(nodes, ...)

## S3 method for class 'graph'
l_graph(nodes, ...)

## S3 method for class 'loongraph'
l_graph(nodes, ...)

## Default S3 method:
l_graph(nodes = "", from = "", to = "", isDirected = FALSE, parent = NULL, ...)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#graph")

Value

graph handle

See Also

Other related graph objects, loongraph, completegraph, linegraph, complement, as.graph

Advanced usage l_navgraph, l_ng_plots, l_ng_ranges

Examples

if(interactive()) {
 G <- completegraph(nodes=names(iris))
 LG <- linegraph(G, sep=":")
 g <- l_graph(LG)
}

Create a Graph Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_graph_inspector(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_graph_inspector()
}

Create a Graph Analysis Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_graph_inspector_analysis(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_graph_inspector_analysis()
}

Create a Graph Navigator Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_graph_inspector_navigators(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_graph_inspector_navigators()
}

Create a graphswitch widget

Description

The graphswitch provides a graphical user interface for changing the graph in a graph display interactively.

Usage

l_graphswitch(activewidget = "", parent = NULL, ...)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#graph-switch-widget")

See Also

l_graphswitch_add, l_graphswitch_ids, l_graphswitch_delete, l_graphswitch_relabel, l_graphswitch_getLabel, l_graphswitch_move, l_graphswitch_reorder, l_graphswitch_set, l_graphswitch_get

Add a graph to a graphswitch widget

Description

This is a generic function to add a graph to a graphswitch widget.

Usage

l_graphswitch_add(widget, graph, ...)

Arguments

Details

For more information run: l_help("learn_R_display_graph.html#graph-switch-widget")

Value

id for graph in the graphswitch widget

See Also

l_graphswitch

Add a graph that is defined by node names and a from-to edges list

Description

This default method uses the loongraph display states as arguments to add a graph to the graphswitch widget.

Usage

## Default S3 method:
l_graphswitch_add(
  widget,
  graph,
  from,
  to,
  isDirected,
  label = "",
  index = "end",
  ...
)

Arguments

Value

id for graph in the graphswitch widget

See Also

l_graphswitch

Add a graph to the graphswitch widget using a graph object

Description

Graph objects are defined in the graph R package.

Usage

## S3 method for class 'graph'
l_graphswitch_add(widget, graph, label = "", index = "end", ...)

Arguments

Value

id for graph in the graphswitch widget

See Also

l_graphswitch

Add a graph to the graphswitch widget using a loongraph object

Description

Loongraphs can be created with the loongraph function.

Usage

## S3 method for class 'loongraph'
l_graphswitch_add(widget, graph, label = "", index = "end", ...)

Arguments

Value

id for graph in the graphswitch widget

See Also

l_graphswitch

Delete a graph from the graphswitch widget

Description

Remove a a graph from the graphswitch widget

Usage

l_graphswitch_delete(widget, id)

Arguments

See Also

l_graphswitch

Return a Graph as a loongraph Object

Description

Graphs can be extracted from the graphswitch widget as loongraph objects.

Usage

l_graphswitch_get(widget, id)

Arguments

See Also

l_graphswitch, loongraph

Query Label of a Graph in the Graphswitch Widget

Description

The graphs in the graphswitch widgets have labels. Use this function to query the label of a graph.

Usage

l_graphswitch_getLabel(widget, id)

Arguments

See Also

l_graphswitch

List the ids of the graphs in the graphswitch widget

Description

Every graph in the graphswitch widget has an id. This function returns these ids preserving the oder of how the graphs are listed in the graphswitch.

Usage

l_graphswitch_ids(widget)

Arguments

Move a Graph in the Graph List

Description

Change the postion in of a graph in the graphswitch widget.

Usage

l_graphswitch_move(widget, id, index)

Arguments

See Also

l_graphswitch

Relabel a Graph in the Graphswitch Widget

Description

The graphs in the graphswitch widgets have labels. Use this function the relabel a graph.

Usage

l_graphswitch_relabel(widget, id, label)

Arguments

See Also

l_graphswitch

Reorder the Positions of the Graphs in the Graph List

Description

Define a new graph order in the graph list.

Usage

l_graphswitch_reorder(widget, ids)

Arguments

See Also

l_graphswitch

Change the Graph shown in the Active Graph Widget

Description

The activewidget state holds the widget handle of a graph display. This function replaces the graph in the activewidget with one of the graphs in the graphswitch widget.

Usage

l_graphswitch_set(widget, id)

Arguments

See Also

l_graphswitch

Open a browser with loon's combined (TCL and R) documentation website

Description

l_help opens a browser with the relevant page on the official combined loon documentation website at https://great-northern-diver.github.io/loon/l_help/.

Usage

l_help(page = "index", ...)

Arguments

See Also

help, l_web for R manual or web R manual

Examples

## Not run: 
l_help()
l_help("learn_R_intro")
l_help("learn_R_display_hist")
l_help("learn_R_bind")
# jump to a section
l_help("learn_R_bind.html#list-reorder-delete-bindings")

## End(Not run)

Convert color names to their 12 digit hexadecimal color representation

Description

Color names in loon will be mapped to colors according to the Tk color specifications and are normalized to a 12 digit hexadecimal color representation.

Usage

l_hexcolor(color)

Arguments

Value

a character vector with the 12 digit hexadecimal color strings.

See Also

as_hex6color, hex12tohex6, l_colorName

Examples

if(interactive()){

p <- l_plot(1:2)
p['color'] <- 'red'
p['color']

l_hexcolor('red')
}

Create an interactive histogram

Description

l_hist is a generic function for creating interactive histogram displays that can be linked with loon's other displays.

Usage

l_hist(x, ...)

## Default S3 method:
l_hist(
  x,
  yshows = c("frequency", "density"),
  by = NULL,
  on,
  layout = c("grid", "wrap", "separate"),
  connectedScales = c("cross", "row", "column", "both", "x", "y", "none"),
  origin = NULL,
  binwidth = NULL,
  showStackedColors = TRUE,
  showBinHandle = FALSE,
  color = l_getOption("color"),
  active = TRUE,
  selected = FALSE,
  xlabel = NULL,
  showLabels = TRUE,
  showScales = FALSE,
  showGuides = TRUE,
  parent = NULL,
  ...
)

## S3 method for class 'factor'
l_hist(
  x,
  showFactors = length(unique(x)) < 25L,
  factorLabelAngle,
  factorLabelSize = 12,
  factorLabelColor = l_getOption("foreground"),
  factorLabelY = 0,
  ...
)

## S3 method for class 'character'
l_hist(
  x,
  showFactors = length(unique(x)) < 25L,
  factorLabelAngle,
  factorLabelSize = 12,
  factorLabelColor = l_getOption("foreground"),
  factorLabelY = 0,
  ...
)

## S3 method for class 'data.frame'
l_hist(x, ...)

## S3 method for class 'matrix'
l_hist(x, ...)

## S3 method for class 'list'
l_hist(x, ...)

## S3 method for class 'table'
l_hist(x, ...)

## S3 method for class 'array'
l_hist(x, ...)

Arguments

Details

For more information run: l_help("learn_R_display_hist")

• Note that when changing the yshows state from 'frequency' to 'density' you might have to use l_scaleto_world to show the complete histogram in the plotting region.

• Some arguments to modify layouts can be passed through, e.g. "separate", "byrow", etc. Check l_facet to see how these arguments work.

Value

if the argument by is not set, a loon widget will be returned; else an l_facet object (a list) will be returned and each element is a loon widget displaying a subset of interest.

See Also

Turn interactive loon plot static loonGrob, grid.loon, plot.loon.

Other loon interactive states: l_info_states(), l_plot(), l_serialaxes(), l_state_names(), names.loon()

Examples

if(interactive()){

h <- l_hist(iris$Sepal.Length)

names(h)
h["xlabel"] <- "Sepal length"
h["showOutlines"] <- FALSE

h["yshows"]
h["yshows"] <- "density"
l_scaleto_plot(h)

h["showStackedColors"] <- TRUE
h['color'] <- iris$Species
h["showStackedColors"] <- FALSE
h["showOutlines"] <- TRUE
h["showGuides"] <- FALSE

# link another plot with the previous plot
h['linkingGroup'] <- "iris_data"
h2 <- with(iris, l_hist(Petal.Width,
                        linkingGroup="iris_data",
                        showStackedColors = TRUE))


# Get an R (grid) graphics plot of the current loon plot
plot(h)
# or with more control about grid parameters
grid.loon(h)
# or to save the grid data structure (grob) for later use
hg <- loonGrob(h)

}

Create a Histogram Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_hist_inspector(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_hist_inspector()
}

Create a Histogram Analysis Inspector

Description

Inpectors provide graphical user interfaces to oversee and modify plot states

Usage

l_hist_inspector_analysis(parent = NULL, ...)

Arguments

Value

widget handle

See Also

l_create_handle

Examples

if(interactive()){

i <- l_hist_inspector_analysis()
}

Import Greyscale Images as Tcl images from an Array

Description

Import image grayscale data (0-255) with each image saved as a row or column of an array.

Usage

l_image_import_array(
  array,
  width,
  height,
  img_in_row = TRUE,
  invert = FALSE,
  rotate = 0
)

Arguments

Details

Images in tcl are managed by the tcl interpreter and made accessible to the user via a handle, i.e. a function name of the form image1, image2, etc.

For more information run: l_help("learn_R_display_plot.html#images")

Value

vector of image object names

Examples

## Not run: 
# see
demo("l_ng_images_frey_LLE")

## End(Not run)

Import Image Files as Tk Image Objects

Description

Note that the supported image file formats depend on whether the Img Tk extension is installed.

Usage

l_image_import_files(paths)

Arguments

Details

For more information run: l_help("learn_R_display_plot.html#load-images")

Value

vector of image object names

See Also

l_image_import_array, l_imageviewer

Display Tcl Images in a Simple Image Viewer

Description

Loon provides a simple image viewer to browse through the specified tcl image objects.

The simple GUI supports either the use of the mouse or left and right arrow keys to switch the images to the previous or next image in the specified image vector.

The images are resized to fill the viewer window.

Usage

l_imageviewer(tclimages)

Arguments

Value

the tclimages vector is returned

Examples

if(interactive()){


img2 <- tkimage.create('photo', width=200, height=150)
tcl(img2, 'put', 'yellow', '-to', 0, 0, 199, 149)
tcl(img2, 'put', 'green', '-to', 40, 20, 130, 40)
img3 <- tkimage.create('photo', width=500, height=100)
tcl(img3, 'put', 'orange', '-to', 0, 0, 499, 99)
tcl(img3, 'put', 'green', '-to', 40, 80, 350, 95)

l_imageviewer(c(tclvalue(img2), tclvalue(img3)))

}

Retrieve Information about the States of a Loon Widget

Description

Loon's built-in object documentation. Can be used with every loon object that has plot states including plots, layers, navigators, contexts. This is a generic function.

Usage

l_info_states(target, states = "all")

Arguments

Value

a named nested list with one element per state. The list elements are also named lists with type, dimension, defaultvalue, and description elements containing the respective information.

See Also

Other loon interactive states: l_hist(), l_plot(), l_serialaxes(), l_state_names(), names.loon()

Examples

if(interactive()){

p <- l_plot(iris, linkingGroup="iris")
i <- l_info_states(p)
names(p)
names(i)
i$selectBy

l <- l_layer_rectangle(p, x=range(iris[,1]), y=range(iris[,2]), color="")
l_info_states(l)


h <- l_hist(iris$Sepal.Length, linkingGroup="iris")
l_info_states(h)

}

Check if a widget path is a valid loon widget

Description

This function can be useful to check whether a loon widget is has been closed by the user.

Usage

l_isLoonWidget(widget)

Arguments

Value

boolean, TRUE if the argument is a valid loon widget path, FALSE otherwise

Loon layers

Description

Loon supports layering of visuals and groups of visuals. The l_layer function is a generic method.

Usage

l_layer(widget, x, ...)

Arguments

Details

loon's displays that use the main graphics model (i.e. histogram, scatterplot and graph displays) support layering of visual information. The following table lists the layer types and functions for layering on a display.

Every layer within a display has a unique id. The visuals of the data in a display present the default layer of that display and has the layer id 'model'. For example, the 'model' layer of a scatterplot display visualizes the scatterplot glyphs. Functions useful to query layers are

Layers are arranged in a tree structure with the tree root having the layer id 'root'. The rendering order of the layers is according to a depth-first traversal of the layer tree. This tree also maintains a label and a visibility flag for each layer. The layer tree, layer ids, layer labels and the visibility of each layer are visualized in the layers inspector. If a layer is set to be invisible then it is not rendered on the display. If a group layer is set to be invisible then all its children are not rendered; however, the visibility flag of the children layers remain unchanged. Relevant functions are:

All layers have states that can be queried and modified using the same functions as the ones used for displays (i.e. l_cget, l_configure, `[` and `[<-`). The last group of layer types in the above table have n-dimensional states, where the actual value of n can be different for every layer in a display.

The difference between the model layer and the other layers is that the model layer has a selected state, responds to selection gestures and supports linking.

For more information run: l_help("learn_R_layer")

Value

layer object handle, layer id

See Also

l_info_states, l_scaleto_layer, l_scaleto_world;

some l_layer S3 methods: l_layer.density, l_layer.map, l_layer.SpatialPolygonsDataFrame, l_layer.SpatialPolygons, l_layer.Polygons, l_layer.Polygon, l_layer.SpatialLinesDataFrame, l_layer.SpatialLines, l_layer.Lines, l_layer.Line, l_layer.SpatialPointsDataFrame, l_layer.SpatialPoints

Examples

if(interactive()){

# l_layer is a generic method
newFoo <- function(x, y, ...) {
  r <- list(x=x, y=y, ...)
  class(r) <- 'foo'
  return(r)
}

l_layer.foo <- function(widget, x) {
    x$widget <- widget
    id <- do.call('l_layer_polygon', x)
    return(id)
}

p <- l_plot()

obj <- newFoo(x=c(1:6,6:2), y=c(3,1,0,0,1,3,3,5,6,6,5), color='yellow')

id <- l_layer(p, obj)

l_scaleto_world(p)
}

Layer line in Line object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'Line'
l_layer(widget, x, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer lines in Lines object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'Lines'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer polygon in Polygon object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'Polygon'
l_layer(widget, x, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer polygons in Polygons object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'Polygons'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer lines in SpatialLines object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialLines'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer lines in SpatialLinesDataFrame object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialLinesDataFrame'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer points in SpatialPoints object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialPoints'
l_layer(widget, x, asMainLayer = FALSE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer points in SpatialPointsDataFrame object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialPointsDataFrame'
l_layer(widget, x, asMainLayer = FALSE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer polygons in SpatialPolygons object

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialPolygons'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer polygons in SpatialPolygonDataFrame

Description

Methods to plot map data defined in the sp package

Usage

## S3 method for class 'SpatialPolygonsDataFrame'
l_layer(widget, x, asSingleLayer = TRUE, ...)

Arguments

Details

Note that currently loon does neither support holes and ring directions.

Value

layer id

References

Applied Spatial Data Analysis with R by Bivand, Roger S. and Pebesma, Edzer and Gomez-Rubio and Virgilio

See Also

sp, l_layer

Examples

if (interactive()) {

if (requireNamespace("rworldmap", quietly = TRUE)) {
    world <- rworldmap::getMap(resolution = "coarse")
    p <- l_plot()
    lmap <- l_layer(p, world, asSingleLayer=TRUE)
    l_scaleto_world(p)
    attr(lmap,'hole')
    attr(lmap,'NAME')
}
}

Layer Method for Kernel Density Estimation

Description

Layer a line that represents a kernel density estimate.

Usage

## S3 method for class 'density'
l_layer(widget, x, ...)

Arguments

Value

layer object handle, layer id

See Also

density

Examples

if(interactive()){
  d <- density(faithful$eruptions, bw = "sj")
  h <- l_hist(x = faithful$eruptions, yshows="density")
  l <- l_layer.density(h, d, color="steelblue", linewidth=3)
  # or l <- l_layer(h, d, color="steelblue", linewidth=3)
}

Add a Map of class map as Drawings to Loon plot

Description

The maps library provides some map data in polygon which can be added as drawings (currently with polygons) to Loon plots. This function adds map objects with class map from the maps library as background drawings.

Usage

## S3 method for class 'map'
l_layer(
  widget,
  x,
  color = "",
  linecolor = "black",
  linewidth = 1,
  label,
  parent = "root",
  index = 0,
  asSingleLayer = TRUE,
  ...
)

Arguments

Value

If asSingleLayer=TRUE then returns layer id of polygons layer, otherwise group layer that contains polygon children layers.

Examples

if(interactive()){

if (requireNamespace("maps", quietly = TRUE)) {
  canada <- maps::map("world",  "Canada",
                      fill=TRUE, plot=FALSE)
  p <- l_plot()
  l_map <- l_layer(p, canada,
                   asSingleLayer=TRUE, color = "cornsilk")
  l_map['color'] <- ifelse(grepl("lake", canada$names, TRUE),
                           "lightblue", "cornsilk")
  l_scaleto_layer(p, l_map)
  l_map['active'] <- FALSE
  l_map['active'] <- TRUE
  l_map['tag']
}

}

Get the bounding box of a layer.

Description

The bounding box of a layer returns the coordinates of the smallest rectangle that encloses all the elements of the layer.

Usage

l_layer_bbox(widget, layer = "root")

Arguments

Value

Numeric vector of length 4 with (xmin, ymin, xmax, ymax) of the bounding box

Examples

if(interactive()){

p <- with(iris, l_plot(Sepal.Length ~ Sepal.Width, color=Species))
l_layer_bbox(p, layer='model')

l <- l_layer_rectangle(p, x=0:1, y=30:31)
l_layer_bbox(p, l)

l_layer_bbox(p, 'root')

}

Layer Contour Lines

Description

This function is a wrapper around contourLines that adds the countourlines to a loon plot which is based on the cartesian coordinate system.

Usage

l_layer_contourLines(
  widget,
  x = seq(0, 1, length.out = nrow(z)),
  y = seq(0, 1, length.out = ncol(z)),
  z,
  nlevels = 10,
  levels = pretty(range(z, na.rm = TRUE), nlevels),
  asSingleLayer = TRUE,
  parent = "root",
  index = "end",
  ...
)

Arguments

Details

For more information run: l_help("learn_R_layer.html#countourlines-heatimage-rasterimage")

Value

layer id of group or lines layer

Examples

if(interactive()){

p <- l_plot()
x <- 10*1:nrow(volcano)
y <- 10*1:ncol(volcano)
lcl <- l_layer_contourLines(p, x, y, volcano)
l_scaleto_world(p)

if (requireNamespace("MASS", quietly = TRUE)) {

  p1 <- with(iris, l_plot(Sepal.Length~Sepal.Width, color=Species))
  lcl <- with(iris, l_layer_contourLines(p1, MASS::kde2d(Sepal.Width,Sepal.Length)))

  p2 <- with(iris, l_plot(Sepal.Length~Sepal.Width, color=Species))
  layers <- sapply(split(cbind(iris, color=p2['color']), iris$Species), function(dat) {
       kest <- with(dat, MASS::kde2d(Sepal.Width,Sepal.Length))
       l_layer_contourLines(p2, kest, color=as.character(dat$color[1]), linewidth=2,
            label=paste0(as.character(dat$Species[1]), " contours"))
  })
}

}

Delete a layer

Description

All but the 'model' and the 'root' layer can be dynamically deleted. If a group layer gets deleted with l_layer_delete then all its children layers get moved into their grandparent group layer.

Usage

l_layer_delete(widget, layer)

Arguments

Value

0 if success otherwise the function throws an error

See Also

l_layer, l_info_states

Examples

if(interactive()){

p <- l_plot()
l1 <- l_layer_rectangle(p, x = 0:1, y = 0:1, color='red')
l_layer_delete(l1)

l2 <- l_layer_rectangle(p, x = 0:1, y = 0:1, color='yellow')
l_layer_delete(p,l2)

}

Moves the layer to be a child of its right group layer sibling

Description

Moves the layer up the layer tree (away from the root layer) if there is a sibling group layer to the right of the layer.

Usage

l_layer_demote(widget, layer)

Arguments

Value

0 if success otherwise the function throws an error

Examples

if(interactive()){

p <- l_plot()

g1 <- l_layer_group(p)
g2 <- l_layer_group(p, parent=g1)
l1 <- l_layer_oval(p, x=0:1, y=0:1)

l_layer_printTree(p)
l_layer_demote(p, l1)
l_layer_printTree(p)
l_layer_demote(p, l1)
l_layer_printTree(p)

}

Delete a layer and all its descendants

Description

Delete a group layer and all it's descendants. Note that the 'model' layer cannot be deleted.

Usage

l_layer_expunge(widget, layer)

Arguments

Value

0 if success otherwise the function throws an error

See Also

l_layer, l_layer_delete

Examples

if(interactive()){

p <- l_plot()
g <- l_layer_group(p)
l1 <- l_layer_rectangle(p, x=0:1, y=0:1, parent=g, color="", linecolor="orange", linewidth=2)
l2 <- l_layer_line(p, x=c(0,.5,1), y=c(0,1,0), parent=g, color="blue")

l_layer_expunge(p, g)

# or l_layer_expunge(g)

}

Get children of a group layer

Description

Returns the ids of a group layer's children.

Usage

l_layer_getChildren(widget, layer = "root")

Arguments

Value

Character vector with ids of the childrens. To create layer handles (i.e. objects of class 'l_layer') use the l_create_handle function.

See Also

l_layer, l_layer_getParent

Examples

if(interactive()){

p <- l_plot()

g <- l_layer_group(p)
l1 <- l_layer_rectangle(p, x=0:1, y=0:1, parent=g)
l2 <- l_layer_oval(p, x=0:1, y=0:1, color='thistle', parent=g)

l_layer_getChildren(p, g)

}

Get layer label.

Description

Layer labels are useful to identify layer in the layer inspector. The layer label can be initially set at layer creation with the label argument.

Usage

l_layer_getLabel(widget, layer)

Arguments

Details

Note that the layer label is not a state of the layer itself, instead is information that is part of the layer collection (i.e. its parent widget).

Value

Named vector of length 1 with layer label as value and layer id as name.

See Also

l_layer, l_layer_relabel

Examples

if(interactive()){

p <- l_plot()
l1 <- l_layer_rectangle(p, x=0:1, y=0:1, label="a rectangle")
l_layer_getLabel(p, 'model')
l_layer_getLabel(p, l1)

}

Get parent layer id of a layer

Description

The toplevel parent is the 'root' layer.

Usage

l_layer_getParent(widget, layer)

Arguments

See Also

l_layer, l_layer_getChildren

Examples

if(interactive()){

p <- with(iris, l_plot(Sepal.Length ~ Sepal.Width, color=Species))

l_layer_getParent(p, 'model')

}

Get layer type

Description

To see the manual page of l_layer for all the primitive layer types.

Usage

l_layer_getType(widget, layer)

Arguments

Details

For more information run: l_help("learn_R_layer")

Value

One of: 'group', 'polygon', 'text', 'line', 'rectangle', 'oval', 'points', 'texts', 'polygons', 'rectangles', 'lines' and 'scatterplot', 'histogram', 'serialaxes' and 'graph'.

See Also

l_layer

Examples

if(interactive()){

p <- l_plot()
l <- l_layer_rectangle(p, x=0:1, y=0:1)
l_layer_getType(p, l)
l_layer_getType(p, 'model')

}

layer a group node

Description

Loon's displays that are based on Cartesian coordinates (i.e. scatterplot, histogram and graph display) allow for layering visual information including polygons, text and rectangles.

A group layer can contain other layers. If the group layer is invisible, then so are all its children.

Usage

l_layer_group(widget, label = "group", parent = "root", index = 0)

Arguments

Details

For more information run: l_help("learn_R_layer")

Value

layer object handle, layer id

See Also

l_layer, l_info_states

Examples

if (interactive()){
p <- l_plot(x=c(1,10,1.5,7,4.3,9,5,2,8),
             y=c(1,10,7,3,4,3.3,8,3,4),
             title="Demo Layers")

id.g <- l_layer_group(p, "A Layer Group")
id.pts <- l_layer_points(p, x=c(3,6), y=c(4,7), color="red", parent=id.g)
l_scaleto_layer(p, id.pts)
l_configure(id.pts, x=c(-5,5,12), y=c(-2,-5,18), color="lightgray")

}

Queries visibility status of decendants

Description

Query whether all, part or none of the group layers descendants are visible.

Usage

l_layer_groupVisibility(widget, layer)

Arguments

Details

Visibile layers are rendered, invisible ones are not. If any ancestor of a layer is set to be invisible then the layer is not rendered either. The layer visibility flag can be checked with l_layer_isVisible and the actual visibility (i.e. are all the ancesters visibile too) can be checked with l_layer_layerVisibility.

Note that layer visibility is not a state of the layer itself, instead is information that is part of the layer collection (i.e. its parent widget).

Value

'all', 'part' or 'none' depending on the visibility status of the descendants.

See Also

l_layer, l_layer_show, l_layer_hide, l_layer_isVisible, l_layer_layerVisibility

Examples

if(interactive()){

p <- l_plot()

g <- l_layer_group(p)
l1 <- l_layer_rectangle(p, x=0:1, y=0:1, parent=g)
l2 <- l_layer_oval(p, x=0:1, y=0:1, parent=g)

l_layer_groupVisibility(p, g)
l_layer_hide(p, l2)
l_layer_groupVisibility(p, g)
l_layer_hide(p, l1)
l_layer_groupVisibility(p, g)
l_layer_hide(p, g)
l_layer_groupVisibility(p, g)

}

Display a Heat Image

Description

This function is very similar to the image function. It works with every loon plot which is based on the cartesian coordinate system.

Usage

l_layer_heatImage(
  widget,
  x = seq(0, 1, length.out = nrow(z)),
  y = seq(0, 1, length.out = ncol(z)),
  z,
  zlim = range(z[is.finite(z)]),
  xlim = range(x),
  ylim = range(y),
  col = grDevices::heat.colors(12),
  breaks,
  oldstyle = FALSE,
  useRaster,
  index = "end",
  parent = "root",
  ...
)

Arguments

Details

For more information run: l_help("learn_R_layer.html#countourlines-heatimage-rasterimage")

Value

layer id of group or rectangles layer

Examples

if(interactive()){

if (requireNamespace("MASS", quietly = TRUE)) {
  kest <- with(iris, MASS::kde2d(Sepal.Width,Sepal.Length))
  image(kest)
  contour(kest, add=TRUE)

  p <- l_plot()
  lcl <- l_layer_contourLines(p, kest, label='contour lines')
  limg <- l_layer_heatImage(p, kest, label='heatmap')
  l_scaleto_world(p)
}

# from examples(image)
x <- y <- seq(-4*pi, 4*pi, len = 27)
r <- sqrt(outer(x^2, y^2, "+"))
p1 <- l_plot()
l_layer_heatImage(p1, z = z <- cos(r^2)*exp(-r/6), col  = gray((0:32)/32))
l_scaleto_world(p1)

image(z = z <- cos(r^2)*exp(-r/6), col  = gray((0:32)/32))

}

Hide a Layer

Description

A hidden layer is not rendered. If a group layer is set to be hidden then all its descendants are not rendered either.

Usage

l_layer_hide(widget, layer)

Arguments

Details

Visibile layers are rendered, invisible ones are not. If any ancestor of a layer is set to be invisible then the layer is not rendered either. The layer visibility flag can be checked with l_layer_isVisible and the actual visibility (i.e. are all the ancesters visibile too) can be checked with l_layer_layerVisibility.

Note that layer visibility is not a state of the layer itself, instead is information that is part of the layer collection (i.e. its parent widget).

Value

0 if success otherwise the function throws an error

See Also

l_layer, l_layer_show, l_layer_isVisible, l_layer_layerVisibility, l_layer_groupVisibility

Examples

if(interactive()){

p <- l_plot()

l <- l_layer_rectangle(p, x=0:1, y=0:1, color="steelblue")
l_layer_hide(p, l)

}

List ids of layers in Plot

Description

Every layer within a display has a unique id. This function returns a list of all the layer ids for a widget.

Usage

l_layer_ids(widget)

Arguments

Details

For more information run: l_help("learn_R_layer.html#add-move-delete-layers")

Value

vector with layer ids in rendering order. To create a layer handle object use l_create_handle.

See Also

l_layer, l_info_states

Examples

if (interactive()){
set.seed(500)
x <- rnorm(30)
y <- 4 + 3*x + rnorm(30)
fit <- lm(y~x)
xseq <- seq(min(x)-1, max(x)+1, length.out = 50)
fit_line <- predict(fit, data.frame(x=range(xseq)))
ci <- predict(fit, data.frame(x=xseq),
              interval="confidence", level=0.95)
pi <- predict(fit, data.frame(x=xseq),
              interval="prediction", level=0.95)


p <- l_plot(y~x, color='black', showScales=TRUE, showGuides=TRUE)
gLayer <- l_layer_group(
    p, label="simple linear regression",
    parent="root", index="end"
)
fitLayer <- l_layer_line(
    p, x=range(xseq), y=fit_line, color="#04327F",
    linewidth=4, label="fit", parent=gLayer
)
ciLayer <- l_layer_polygon(
    p,
    x = c(xseq, rev(xseq)),
    y = c(ci[,'lwr'], rev(ci[,'upr'])),
    color = "#96BDFF", linecolor="",
    label = "95 % confidence interval",
    parent = gLayer, index='end'
)
piLayer <- l_layer_polygon(
    p,
    x = c(xseq, rev(xseq)),
    y = c(pi[,'lwr'], rev(pi[,'upr'])),
    color = "#E2EDFF", linecolor="",
    label = "95 % prediction interval",
    parent = gLayer, index='end'
)

l_info_states(piLayer)

}

Get the order index of a layer among its siblings

Description

The index determines the rendering order of the children layers of a parent. The layer with index=0 is rendered first.

Usage

l_layer_index(widget, layer)

Arguments

Details

Note that the index for layers is 0 based.

Value

numeric value

See Also

l_layer, l_layer_move

Return visibility flag of layer

Description

Hidden or invisible layers are not rendered. This function queries whether a layer is visible/rendered or not.

Usage

l_layer_isVisible(widget, layer)

Arguments

Details

Visibile layers are rendered, invisible ones are not. If any ancestor of a layer is set to be invisible then the layer is not rendered either. The layer visibility flag can be checked with l_layer_isVisible and the actual visibility (i.e. are all the ancesters visibile too) can be checked with l_layer_layerVisibility.

Note that layer visibility is not a state of the layer itself, instead is information that is part of the layer collection (i.e. its parent widget).

Value

TRUE or FALSE depending whether the layer is visible or not.

See Also

l_layer, l_layer_show, l_layer_hide, l_layer_layerVisibility, l_layer_groupVisibility

Examples

if(interactive()){

p <- l_plot()
l <- l_layer_rectangle(p, x=0:1, y=0:1)
l_layer_isVisible(p, l)
l_layer_hide(p, l)
l_layer_isVisible(p, l)

}

Returns logical value for whether layer is actually seen

Description

Although the visibility flag for a layer might be set to TRUE it won't be rendered as on of its ancestor group layer is set to be invisible. The l_layer_visibility returns TRUE if the layer and all its ancestor layers have their visibility flag set to true and the layer is actually rendered.

Usage

l_layer_layerVisibility(widget, layer)

Arguments

Details

Visibile layers are rendered, invisible ones are not. If any ancestor of a layer is set to be invisible then the layer is not rendered either. The layer visibility flag can be checked with l_layer_isVisible and the actual visibility (i.e. are all the ancesters visibile too) can be checked with l_layer_layerVisibility.

Note that layer visibility is not a state of the layer itself, instead is information that is part of the layer collection (i.e. its parent widget).

Value

TRUE if the layer and all its ancestor layers have their visibility flag set to true and the layer is actually rendered, otherwise FALSE.

See Also

l_layer, l_layer_show, l_layer_hide, l_layer_isVisible, l_layer_groupVisibility

Layer a line

Description

Loon's displays that are based on Cartesian coordinates (i.e. scatterplot, histogram and graph display) allow for layering visual information including polygons, text and rectangles.

Usage

l_layer_line(
  widget,
  x,
  y = NULL,
  color = "black",
  linewidth = 1,
  dash = "",
  label = "line",
  parent = "root",
  index = 0,
  ...
)

Arguments

Details

For more information run: l_help("learn_R_layer")

Value

layer object handle, layer id

See Also

l_layer, l_info_states

Examples

if(interactive()){

p <- l_plot()
l <- l_layer_line(p, x=c(1,2,3,4), y=c(1,3,2,4), color='red', linewidth=2)
l_scaleto_world(p)

# object
p <- l_plot()
l <- l_layer_line(p, x=nhtemp)
l_scaleto_layer(l)

}

Layer lines

Description

Loon's displays that are based on Cartesian coordinates (i.e. scatterplot, histogram and graph display) allow for layering visual information including polygons, text and rectangles.

Usage

l_layer_lines(
  widget,
  x,
  y,
  color = "black",
  linewidth = 1,
  label = "lines",
  parent = "root",
  index = 0,
  group = NULL,
  active = TRUE,
  ...
)

Arguments

Details

For more information run: l_help("learn_R_layer")

Value

layer object handle, layer id

See Also

l_layer, l_info_states

Examples

if(interactive()){

s <- Filter(function(df)nrow(df) > 1, split(UsAndThem, UsAndThem$Country))
sUaT <- Map(function(country){country[order(country$Year),]} , s)
xcoords <- Map(function(x)x$Year, sUaT)
ycoords <- Map(function(x)x$LifeExpectancy, sUaT)
region <- sapply(sUaT, function(x)as.character(x$Geographic.Region[1]))

p <- l_plot(showItemLabels=TRUE)
l <- l_layer_lines(p, xcoords, ycoords, itemLabel=names(sUaT), color=region)
l_scaleto_layer(l)

# Set groups
p <- l_plot(showItemLabels=TRUE)
l <- l_layer_lines(p,
                   x = c((0:4)/10, rep(.5, 5), (10:6)/10, rep(.5, 5)),
                   y = c(rep(.5, 5), (10:6/10), rep(.5, 5), (0:4)/10),
                   group = rep(1:5, 4),
                   linewidth = 4,
                   col = l_getColorList()[1:5])
l_scaleto_layer(l)

}

Switch the layer place with its sibling to the right

Description

Change the layers position within its parent layer group by increasing the index of the layer by one if possible. This means that the raised layer will be rendered before (or on below) of its sibling layer to the right.

Usage

l_layer_lower(widget, layer)

Arguments

Value

0 if success otherwise the function throws an error

See Also

l_layer, l_layer_raise, l_layer_move

Examples

if(interactive()){

p <- l_plot()

l1 <- l_layer_rectangle(p, x=0:1, y=0:1)
l2 <- l_layer_oval(p, x=0:1, y=0:1, color='thistle')

l_aspect(p) <- 1

l_layer_lower(p, l2)

}

Move a layer

Description

The postition of a layer in the layer tree determines the rendering order. That is, the non-group layers are rendered in order of a Depth-first traversal of the layer tree. The toplevel group layer is called 'root'.

Usage

l_layer_move(widget, layer, parent, index = "0")

Arguments