Learn R Programming

loon

loon is an extendible interactive data visualization system designed for exploratory visualization.

Though primarily for exploratory data analysis, it can also be used to develop new interactive analysis and teaching tools. Some sense of the breadth of application and possible extensions can be seen in the various vignettes, demos, and examples in the documentation.

Some sense of the use of loon can be had from the articles, especially the introduction, available here.

Web Documentation

In addition to the R package documentation we also have both TCL and R documentation here. ß Once in R, these are accessible from loon as

# Combined TCL and R documentation (a learning document)
l_help()

# R only manual
l_web()

l_web(directory = "articles")

# R system documentation
help(package = loon")

vignette(package = "loon")

demo(package = "loon")

Installation

The interactive graphics in loon are written on TCL, accessible to R via the tcltk R package. Be sure to have a version of R that includes Tcl/Tk 8.6.6 (which happens by default but might be missing if you have a custom R build).

# The easiest way to install loon
install.packages("loon")

# You could also install the latest development release directly from GitHub
devtools::install_github("great-northern-diver/loon", subdir = "R")
# Or, to ensure you have the vignettes as well 
# (  also accessible via l_web(directory = "articles")  )
devtools::install_github("great-northern-diver/loon", subdir = "R", 
                         build_opts = c("--no-resave-data") )

Other Usage/Installation notes

  • It is best to use loon in RStudio or within a terminal.

    • The Rgui app on OSX does not work well with loon.

    • The default Windows R GUI will not accept debug messages from Tcl, so for now you need to use RStudio or the terminal.

  • Mac users need to install XQuartz

    • Do not close XQuartz while R is running! Otherwise you end up crashing the active R session (including RStudio).

  • On Ubuntu one should install the libtk-img debian package (e.g. with sudo apt-get install libtk-img) in order to get a wide variety of export formats with the l_export function.

Getting started

Once loon is installed, work your way through the introductory vignette:

library(loon)
#
# from the vignette in R
vignette("introduction", package = "loon")
#
# or via the web
l_web(page = "introduction", directory = "articles")

Demos

The data used in this demo is quakes giving the locations, depth, Richter magnitude of earthquakes of Fiji since 1964.

Histogram

The binsize can be modified by the graphical element at the bottom of this histogram.

h <- l_hist(quakes$depth,
            yshows = "density",
            showBinHandle = TRUE,
            xlabel = "depth",
            title = "Tonga trench earthquakes",
            linkingGroup = "quakes")

Scatterplot

Scrolling the mouse to zoom the plot. To pan the plot, press the right mouse button and move the mouse

p <- l_plot(x = quakes$long, y = quakes$lat,
            xlabel = "longitude", ylabel = "latitude",
            linkingGroup = "quakes",
            title = "Tonga trench earthquakes")

Linking and Brushing

Two plots are linked that the change on one change can affect changes on the other.

3D rotation

with(l_scale3D(quakes),
     l_plot3D(long, lat, depth, linkingGroup = "quakes")
)

Facetting

The plot is splited into three panels by the level of Richter magnitude.

# add a map layer
NZFijiMap <- maps::map("world2", regions = c("New Zealand", "Fiji"), plot = FALSE)
l_layer(p, NZFijiMap,
        label = "New Zealand and Fiji",
        color = "forestgreen",
        index = "end")
# facet `p`
levels <- rep(NA, nrow(quakes))
levels[quakes$mag < 5 & quakes$mag >= 4] <- "Light"
levels[quakes$mag < 6 & quakes$mag >= 5] <- "Moderate"
levels[quakes$mag >= 6] <- "Strong"
l_facet(p, by = levels, 
        linkingGroup = "quakes")

On the name

The software is named after a large aquatic bird known as the common loon (Gavia immer) in Canada and the United States, or the great northern diver in the United Kingdom. (Hence the name of the github organization: https://github.com/great-northern-diver)

The loon is a visual predator, diving deep beneath the surface, there chasing its prey with speed and remarkable maneuvrability. Once apprehended, the prey are either swallowed immediately or, when large, at least brought to the surface to be dealt with there.

This seemed an excellent metaphor for an agile, interactive, and exploratory visualization system; one which empowered an analyst to chase, and perhaps discover, whatever features might be revealed in the data by quickly diving below its surface. The goal is to provide such a system in loon.

As an acronym "loon" does not fare so well (least obvious ostensive name) and perhaps its synonym "diver" would be better (direct interactive visual exploration in R). But, then, "loon" is funnier ... diveR will be the name of a collection of "loon" related packages.

You can find documentation on some of these related packages via l_web()

library(loon)
l_web(package = "loon.data", directory = "reference")
l_web(package = "zenplots")     # become one with your data
l_web(package = "ggmulti")      # high dimensional graphics extending the ggplot2 package
l_web(package = "loon.ggplot")  # interactive grammar of graphics via ggplot2 package
l_web(package = "loon.tourr")   # interactive high dimensional tours via tourr package
# And more coming ..

Enjoy!

Copy Link

Version

Install

install.packages('loon')

Monthly Downloads

519

Version

1.4.1

License

GPL-2

Maintainer

Wayne Oldford

Last Published

June 15th, 2023

Functions in loon (1.4.1)

as_grid_size

Turn a loon size to a grid size
as_hex6color

Return a 6 hexidecimal digit color representations
complement

Create the Complement Graph of a Graph
color_loon

Create a palette with loon's color mapping
as.graph

Convert a loongraph object to an object of class graph
as.loongraph

Convert a graph object to a loongraph object
complement.loongraph

Create the Complement Graph of a loon Graph
L2_distance

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

Data to re-create Hans Rosling's famous "Us and Them" animation
char2num.data.frame

A Character Data Frame to a Numerical Data Frame
facet_wrap_layout

Layout as a wrap
get_font_info_from_tk

Return Font Information
condGrob

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

layout separately
glyph_to_pch

Glyph to Pch
hex12tohex6

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

Query the aspect ratio of a plot
get_model_display_order

Get the Order of the Display
l_after_idle

Evaluate a function on once the processor is idle
get_layer_states

Get Layer States
completegraph

Create a complete graph or digraph with a set of nodes
facet_grid_layout

Layout as a grid
graphreduce

Make each space in a node apprear only once
grid.loon

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

Return the Displayed Color
l_bind_context_reorder

Reorder the context binding evaluation sequence
l_bind_glyph

Add a glyph binding
l_bind_context_get

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

List context binding ids
l_bind_context_delete

Delete a context binding
l_bind_item_ids

List item binding ids
l_bind_item_get

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

List canvas binding ids
l_bind_canvas

Create a Canvas Binding
l_bind_glyph_reorder

Reorder the glyph binding evaluation sequence
l_Rlist2nestedTclList

Convert an R list to a nested Tcl list
l_bind_context

Add a context binding
l_bind_navigator_reorder

Reorder the navigator binding evaluation sequence
l_bind_state

Add a state change binding
l_bind_navigator_delete

Delete a navigator binding
l_aspect<-

Set the aspect ratio of a plot
l_bind_glyph_ids

List glyph binding ids
l_bind_item_reorder

Reorder the item binding evaluation sequence
l_bind_layer_delete

Delete a layer binding
l_bind_layer

Add a layer binding
l_binCut

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

Reorder the canvas binding evaluation sequence
l_bind_item

Create a Canvas Binding
l_bind_item_delete

Delete a item binding
l_basePaths

Get the set of basic path types for loon plots.
l_bind_layer_ids

List layer binding ids
l_bind_navigator

Add a navigator binding
l_bind_state_get

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

Delete a state binding
l_colRemoveAlpha

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

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

Reorder the layer binding evaluation sequence
l_context_delete

Delete a context from a navigator
l_colorName

Get Color Names from the Hex Code
l_export

Export a loon plot as an image
l_data

Convert an R data.frame to a Tcl dictionary
l_context_add_slicing2d

Create a slicind2d navigator context
l_context_relabel

Change the label of a context
l_copyStates

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

Create a context2d navigator context
l_breaks

Gets the boundaries of the histogram bins containing active points.
l_cget

Query a Plot State
l_currentindex

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

Create a geodesic2d navigator context
l_bind_state_ids

List state binding ids
l_bind_state_reorder

Reorder the state binding evaluation sequence
l_bind_canvas_delete

Delete a canvas binding
l_bind_glyph_delete

Delete a glyph binding
l_bind_glyph_get

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

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

Modify one or multiple plot states
l_bind_navigator_ids

List navigator binding ids
l_bind_navigator_get

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

Get the set of basic path types for loon plots.
l_context_getLabel

Query the label of a context
l_getBinIds

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

List context ids of a navigator
l_getBinData

Get information on current bins from a histogram
l_currenttags

Get tags of the item below the mouse cursor
l_getLinkedStates

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

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

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

Get Glyph Label
l_glyph_delete

Delete a Glyph
l_getOption

Get the value of a loon display option
l_createCompoundGrob

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

Add a Polygon Glyph
l_glyph_add_pointrange

Add a Pointrange Glyph
l_create_handle

Create a loon object handle
l_glyph_add.default

Default method for adding non-primitive glyphs
l_glyph_add

Add non-primitive glyphs to a scatterplot or graph display
l_getOptionNames

Get the names of all loon display options
l_glyph_add_image

Add an image glyphs
l_glyphs_inspector_pointrange

Create a Pointrange Glyph Inspector
l_glyphs_inspector_image

Create a Image Glyph Inspector
l_getPlots

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

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.
l_glyph_add_serialaxes

Add a Serialaxes Glyph
l_glyph_add_text

Add a Text Glyph
l_graphswitch_move

Move a Graph in the Graph List
l_glyphs_inspector_text

Create a Text Glyph Inspector
l_glyphs_inspector_serialaxes

Create a Serialaxes Glyph Inspector
l_export_valid_formats

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

Relabel Glyph
l_glyphs_inspector

Create a Glyphs Inspector
l_graph_inspector_analysis

Create a Graph Analysis Inspector
l_graphswitch_ids

List the ids of the graphs in the graphswitch widget
l_facet

Layout Facets across multiple panels
l_getColorList

Get loon's color mapping list
l_graph_inspector_navigators

Create a Graph Navigator Inspector
l_graphswitch_add.loongraph

Add a graph to the graphswitch widget using a loongraph object
l_graphswitch_add.default

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

Change the Graph shown in the Active Graph Widget
l_help

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

Add a graph to the graphswitch widget using a graph object
l_layer.Polygon

Layer polygon in Polygon object
l_hist

Create an interactive histogram
l_hexcolor

Convert color names to their 12 digit hexadecimal color representation
l_layer.Lines

Layer lines in Lines object
l_hist_inspector_analysis

Create a Histogram Analysis Inspector
l_layer.Line

Layer line in Line object
l_hist_inspector

Create a Histogram Inspector
l_isLoonWidget

Check if a widget path is a valid loon widget
l_graphswitch_add

Add a graph to a graphswitch widget
l_graphswitch

Create a graphswitch widget
l_getFromPath

Create loon objects from path name
l_getSavedStates

Retrieve saved plot states from the named file.
l_image_import_array

Import Greyscale Images as Tcl images from an Array
l_layer.SpatialPoints

Layer points in SpatialPoints object
l_getScaledData

Data Scaling
l_glyph_getType

Get Glyph Type
l_glyph_ids

List glyphs ids
l_layer_bbox

Get the bounding box of a layer.
l_image_import_files

Import Image Files as Tk Image Objects
l_layer.map

Add a Map of class map as Drawings to Loon plot
l_layer.Polygons

Layer polygons in Polygons object
l_layer_getLabel

Get layer label.
l_layer

Loon layers
l_layer.density

Layer Method for Kernel Density Estimation
l_layer.SpatialPolygons

Layer polygons in SpatialPolygons object
l_layer_getParent

Get parent layer id of a layer
l_layer_hide

Hide a Layer
l_layer_oval

Layer a oval
l_layer_ids

List ids of layers in Plot
l_graphswitch_relabel

Relabel a Graph in the Graphswitch Widget
l_graphswitch_delete

Delete a graph from the graphswitch widget
l_layer_contourLines

Layer Contour Lines
l_layer_move

Move a layer
l_layer.SpatialPointsDataFrame

Layer points in SpatialPointsDataFrame object
l_layer_getChildren

Get children of a group layer
l_layer_expunge

Delete a layer and all its descendants
l_graphswitch_getLabel

Query Label of a Graph in the Graphswitch Widget
l_graph_inspector

Create a Graph Inspector
l_graphswitch_get

Return a Graph as a loongraph Object
l_graph

Generic funtction to create an interactive graph display
l_layer.SpatialLines

Layer lines in SpatialLines object
l_layer_delete

Delete a layer
l_layer.SpatialLinesDataFrame

Layer lines in SpatialLinesDataFrame object
l_graphswitch_reorder

Reorder the Positions of the Graphs in the Graph List
l_layer_demote

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

Layer lines
l_layer_promote

Moves the layer up to be a left sibling of its parent
l_layer_relabel

Change layer label
l_layer_rectangles

Layer rectangles
l_layer_raise

Switch the layer place with its sibling to the left
l_layer_rectangle

Layer a rectangle
l_layer_isVisible

Return visibility flag of layer
l_layer_groupVisibility

Queries visibility status of decendants
l_layer_rasterImage

Layer a Raster Image
l_layer.SpatialPolygonsDataFrame

Layer polygons in SpatialPolygonDataFrame
l_layer_layerVisibility

Returns logical value for whether layer is actually seen
l_layer_line

Layer a line
l_layer_show

Show or unhide a Layer
l_info_states

Retrieve Information about the States of a Loon Widget
l_layer_getType

Get layer type
l_layer_index

Get the order index of a layer among its siblings
l_layer_heatImage

Display a Heat Image
l_layer_group

layer a group node
l_layer_smooth

Layer a smooth line for loon
l_move_hdist

Horizontally Distribute Points or Nodes
l_layer_text

Layer a text
l_move_jitter

Jitter Points Or Nodes
l_imageviewer

Display Tcl Images in a Simple Image Viewer
l_move_grid

Arrange Points or Nodes on a Grid
l_layer_points

Layer points
l_nestedTclList2Rlist

Convert a Nested Tcl List to an R List
l_navigator_ids

List Navigators
l_navigator_getPath

Get the sequence of nodes of a navigator's current path
l_layer_lower

Switch the layer place with its sibling to the right
l_layer_texts

Layer texts
l_move_vdist

Vertically Distribute Points or Nodes
l_nDimStateNames

N dimensional state names access
l_ng_plots.scagnostics

2d Navigation Graph Setup with dynamic node fitering based on scagnostic measures and by using a scatterplot matrix
l_ng_ranges

2d navigation graph setup with with dynamic node fitering using a slider
l_make_glyphs

Make arbitrary glyphs with R graphic devices
l_loon_inspector

Create a loon inspector
l_ng_plots

2d navigation graph setup with with dynamic node fitering using a scatterplot matrix
l_layer_polygon

Layer a polygon
l_navigator_relabel

Modify the Label of a Navigator
l_navigator_walk_backward

Have the Navigator Walk Backward on the Current Path
l_loonWidgets

Get all active top level loon plots.
l_layer_polygons

Layer polygons
l_layer_printTree

Print the layer tree
l_move_reset

Reset Temporary Point or Node Locations to the x and y states
l_navigator_delete

Delete a Navigator
l_ng_plots.default

Select 2d spaces with variable associated measures displayed in scatterplot matrix
l_navigator_getLabel

Query the Label of a Navigator
l_navigator_add

Add a Navigator to a Graph
l_navgraph

Explore a dataset with the canonical 2d navigation graph setting
l_move_halign

Horizontally Align Points or Nodes
l_move_valign

Vertically Align Points or Nodes
l_layers_inspector

Create a Layers Inspector
l_ng_plots.measures

2d Navigation Graph Setup with dynamic node fitering using a scatterplot matrix
l_plot_arguments

Arguments common to l_plot functions
l_plot_ts

Draw a decomposed time series loon plot
l_plot_inspector_analysis

Create a Scatterplot Analysis Inspector
l_plot_inspector

Create a Scatterplot Inspector
l_plot

Create an interactive loon plot widget
l_plot3D

Create an interactive loon 3d plot widget
l_ng_ranges.default

Select 2d spaces with variable associated measures using a slider
l_ng_ranges.measures

2d Navigation Graph Setup with dynamic node fitering using a slider
l_scaleto_selected

Change Plot Region to Display All Selected Data
l_scaleto_plot

Change Plot Region to Display the All Data of the Model Layer
l_predict

Model Prediction
l_primitiveGlyphs

The primitive glyphs available to a scatterplot or graph display
l_ng_ranges.scagnostics

2d Navigation Graph Setup with dynamic node fitering based on scagnostic measures and using a slider
l_navigator_walk_path

Have the Navigator Walk a Path on the Graph
l_navigator_walk_forward

Have the Navigator Walk Forward on the Current Path
l_pairs

An interactive scatterplot matrix
l_redraw

Force a Content Redraw of a Plot
l_resize

Resize Plot Widget
l_setColorList

Use custom colors for mapping nominal values to distinct colors
l_setColorList_ColorBrewer

Set loon's color mapping list to the colors from ColorBrewer
l_setColorList_hcl

Set loon's color mapping list to the colors from hcl color wheen
l_setColorList_loon

Set loon's color mapping list to the colors from loon defaults
l_saveStates

Save the info states of a loon plot widget in a file
l_scale3D

Scale for 3d plotting
l_scaleto_active

Change Plot Region to Display All Active Data
l_setAspect

Set the aspect ratio of a plot
l_scaleto_layer

Change Plot Region to Display All Elements of a Particular Layer
l_toR

Convert a Tcl Object to some other R object
l_serialaxes_inspector

Create a Serialaxes Inspector
l_setTitleFont

Set the title font of all loon displays
l_size<-

Resize Plot Widget
l_setOption

Set the value of a loon display option
l_setLinkedStates

Modify States of a Plot that are Linked in Loon's Standard Linking Model
l_toplevel

loon tk top level
linegraph.loongraph

Create a linegraph of a graph
linegraph

Create a linegraph
l_scaleto_world

Change Plot Region to Display All Plot Data
l_throwErrorIfNotLoonWidget

Throw an error if string is not associated with a loon widget
l_subwin

Create a child widget path
l_serialaxes

Create an interactive serialaxes (parallel axes or radial axes) plot
l_userOptions

Get the names of all loon display options that can be set by the user.
l_userOptionDefault

Get loon's system default value for the named display option.
loon_palette

Loon's color generator for creating color palettes
loonGrob_layoutType

A generic function used to distinguish whether only the locations of plots will be used to arrange them in a grob, or whether all arguments to `gridExtra::arrangeGrob()` will be used.
l_setColorList_ggplot2

Set loon's color mapping list to the colors from ggplot2
l_state_names

Get State Names of Loon Object
l_size

Query Size of a Plot Display
loon

loon: A Toolkit for Interactive Data Visualization and Exploration
l_setColorList_baseR

Set loon's color mapping list to the colors from base R
plot.loon

Plot the current view of any loon plot in the current device.
oliveLocations

Geographic location of each Italian olive growing area named in the olive data.
tkcolors

List the valid Tk color names
ndtransitiongraph

Create a n-d transition graph
names.loon

Get State Names of Loon Object
print.measures2d

Print function names from measure2d object
print.measures1d

Print function names from measure1d object
l_worldview

Create a Worldview Inspector
measures2d

Closure of Two Dimensional Measures
l_zoom

Zoom from and towards the center
olive

Fatty Acid Composition of Italian Olive Oils
plot.loongraph

Plot a loon graph object with base R graphics
loonGrob

Create a grid grob from a loon widget handle
oliveAcids

Just the Fatty Acid Composition of Italian Olive Oils
scagnostics2d

Closure of Two Dimensional Scagnostic Measures
tcl_img_2_r_raster

A tk Image Object to a Raster Object
minority

Canadian Visible Minority Data 2006
print.l_layer

Print a summary of a loon layer object
l_web

Open a browser with loon's R documentation webpage
l_widget

Dummy function to be used in the Roxygen documentation
loongraph

Create a graph object of class loongraph
measures1d

Closure of One Dimensional Measures