graphjs: Interactive 3D Graph Visualization

Description

Make interactive 3D plots of igraph objects.

Usage

graphjs(
  g,
  layout,
  vertex.color,
  vertex.size,
  vertex.shape,
  vertex.label,
  edge.color,
  edge.width,
  edge.alpha,
  main = "",
  bg = "white",
  width = NULL,
  height = NULL,
  elementId = NULL,
  ...
)

Value

An htmlwidget object that is displayed using the object's show or print method. (If you don't see your widget plot, try printing it with the print function.)

Arguments

g: an igraph graph object or a list of igraph objects (see notes)
layout: optional graph layout or list of layouts (see notes)
vertex.color: optional vertex color or vector of colors as long as the number of vertices in g
vertex.size: optional vertex size or vector of sizes
vertex.shape: optional vertex shape or vector of shapes
vertex.label: optional mouse-over vertex label or vector of labels
edge.color: optional edge color or vector of colors as long as the number of edges in g
edge.width: optional edge width (single scalar value, see notes)
edge.alpha: optional single numeric edge transparency value
main: plot title text
bg: plot background color
width: the widget container div width in pixels
height: the widget container div height in pixels
elementId: Use an explicit element ID for the widget (rather than an automatically generated one). Useful if you have other JavaScript that needs to explicitly discover and interact with a specific widget instance.
...: optional additional arguments passed to scatterplot3js

Interacting with the plot

Press and hold the left mouse button, or touch or trackpad equivalent, and move the mouse to rotate the plot. Press and hold the right mouse button to pan. Use the mouse scroll wheel to zoom. If vertex.labels are specified (see below), moving the mouse pointer over a point will display the label. Altenatively use vertex.shape to plot character names as shown in the examples below. Set the optional experimental use.orbitcontrols=TRUE argument to use a more CPU-efficient but somewhat less fluid mouse/touch interface.

Layout options

Use the layout parameter to control the visualization layout by supplying either a three-column matrix of vertex x, y, z coordinates, or a function that returns such a layout. The igraph layout_with_fr force-directed layout is used by default (note that only 3D layouts are supported). Also see the animation section below.

Vertex options

Optional parameters beginning with vertex. represent a subset of the igraph package vertex visualization options and work similarly, see igraph.plotting. Vertex shapes in graphjs act somewhat differently, and are mapped to the pch option in scatterplot3js. In particular, pch character symbols or even short text strings may be specified. The vertex.label option enables a mouse-over label display instead of plotting lables directly near the vertices. (Consider using the text pch options for that instead.)

Edge options

Optional parameters beginning with edge. represent a subset of the igraph edge visualization options and work similarly as the vertex. options above. The current version of the package only supports uniform edge widths specified by a single scalar value. This choice was made for performance reasons to support large visualizations.

Graph animation

Specifying a list of three-column layout matrices in layout displays a linear interpolation from one layout to the next, providing a simple mechanism for graph animation. Each layout must have the same number of rows as the number of vertices in the graph.

Specify the optional fpl (frames per layout) parameter to control the number of interpolating animation frames between layouts. See the examples.

Optionally specify a list of graph objects in g to vary the displayed edges and edge colors from one layout to the next, with the restriction that each graph object must refer to a uniform number of vertices.

The lists of graphs may optionally include varying vertex and edge colors. Alternatively, specify a list of vertex.color vectors (one for each layout) to animate vertex colors. Similarly, optionally specify a list of edge.color vectors to animate edge colors.

Optionally provide a list of main title text strings to vary the title with each animation layout.

None of the other plot parameters may be animated.

Click animation

Specify the option click=list to animate the graph when specified vertices are clicked interactively, where list is a named list of animation entries. Each entry must itself be a list with the following entries

g: optional a single igraph object with the same number of vertices as g above (if specified this must be the first entry)
layout: - optional a single igraph layout, or differential layout if cumulative=TRUE
vertex.color: - optional single vector of vertex colors
edge.color: - optional single vector of edge colors
cumulative: - optional boolean entry, if TRUE then vertex positions are added to current plot, default is FALSE

At least one of g or layout must be specified in each animation list entry. The layouts and colors may be alternatively imbedded in the igraph object itself. Each animation list entry must be named by a number corresponding to the vertex enumeration in g. An animation sequence is triggered when a corresponding vertex is clicked. For instance, to trigger animations when vertices number 1 or 5 are clicked, include list entries labeled "1" and "5". See the demos in demo(package="threejs") for detailed examples.

Other interactions

Specify the argument brush=TRUE to highlight a clicked vertex and its directly connected edges (click off of a vertex to reset the display). Optionally set the highlight=<hex color> and lowlight=<hex color> to manually control the brushing display colors.

Crosstalk

graphjs() works with crosstalk selection (but not filtering yet); see https://rstudio.github.io/crosstalk/. Enable crosstalk by supplying the optional agrument crosstalk=df, where df is a crosstalk-SharedData data.frame-like object with the same number of rows as graph vertices (see the examples).

User-defined JavaScript

Use the optional program argument (see scatterplot3js) to supply JavaScript code as a character string value. The code will be run during plot initialization. See the examples.

References

The three.js project https://threejs.org.

Examples

Run this code

set.seed(1)
g <- sample_islands(3, 10, 5/10, 1)
i <- membership(cluster_louvain(g))
(graphjs(g, vertex.color=c("orange", "green", "blue")[i],
         vertex.shape="sphere"))

# similar example with user-defined directional lighting
l1 <- light_directional(color="red", position=c(0, -0.8, 0.5))
l2 <- light_directional(color="yellow", position=c(0, 0.8, -0.5))
l3 <- light_ambient(color="#555555")
(graphjs(g, vertex.color="gray", vertex.shape="sphere",
         lights=list(l1, l2, l3)))

# Les Miserables Character Co-appearance Data
data("LeMis")
(graphjs(LeMis))

# Use HTML and CSS directly in each vertex label to customize
# and align the legend:
(graphjs(LeMis,
         vertex.label=sprintf("%s",
           V(LeMis)$label)))

# The plot legend 'div' element is of CSS class 'infobox'. Use JavaScript
# to customize labels to hover near the mouse pointer:
program <- "document.addEventListener('mousemove', function(e) {
  e.preventDefault();
  let x = document.getElementsByClassName('infobox')[0];
  x.style['background'] = '#00c9c2';
  x.style['border-radius'] = '5px';
  x.style['color'] = '#222';
  x.style['font-family'] = 'sans-serif';
  x.style['position'] = 'absolute';
  x.style['top'] = e.pageY + 'px';
  x.style['left'] = e.pageX + 'px';
})"
(graphjs(LeMis, program = program))

# ...plot Character names
(graphjs(LeMis, vertex.shape=V(LeMis)$label, vertex.size=0.3))

# SNAP Facebook ego network dataset
data("ego")
(graphjs(ego, bg="black"))

if (FALSE) {
# A shiny example
shiny::runApp(system.file("examples/graph", package="threejs"))

# A graph amination that shows several layouts
data("LeMis")
graphjs(LeMis,
  layout=list(
    layout_randomly(LeMis, dim=3),
    layout_on_sphere(LeMis),
    layout_with_drl(LeMis, dim=3),  # note! somewhat slow...
    layout_with_fr(LeMis, dim=3, niter=30)),
  main=list("random layout", "sphere layout", "drl layout", "fr layout"),
  fpl=300)

# A simple graph animation illustrating edge modification
g <- make_ring(5) - edges(1:5)
graph_list <- list(
 g + edge(1, 2),
 g + edge(1, 2) + edge(2, 3),
 g + edge(1, 2) + edge(2, 3) + edge(3, 4),
 g + edge(1, 2) + edge(2, 3) + edge(3, 4) + edge(4, 5),
 g + edge(1, 2) + edge(2, 3) + edge(3, 4) + edge(4, 5) + edge(5, 1))
 graphjs(graph_list, main=paste(1:5),
   vertex.color=rainbow(5), vertex.shape="sphere", edge.width=3)

# see `demo(package="threejs") for more animation demos.

# A crosstalk example
library(crosstalk)
library(DT)
data(LeMis)
sd = SharedData$new(data.frame(Name = V(LeMis)$label))
print(bscols(
  graphjs(LeMis, brush=TRUE, crosstalk=sd),
  datatable(sd, rownames=FALSE, options=list(dom='tp'))
))
}

Run the code above in your browser using DataLab