vg: Animated graph viewer

Description Usage Arguments Details Value Interactive mouse, key and slide bar controls Author(s) References See Also Examples

View source: R/vg.R

Description

vg creates and starts an animated graphical user interface for positioning the vertices of a graph in 2 dimensions.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
vg(grob, directed, running)

## S3 method for class 'list'
vg(grob, directed = grob$directed, running = grob$running)

## S3 method for class ''NULL''
vg(grob = NULL, directed = FALSE, running = TRUE)

## Default S3 method:
vg(grob = NULL, directed = FALSE, running = TRUE)

Arguments

grob

is a graphical object state saved as a list from a previous run of vg using the save() function. If grob is NULL or not a list, vg starts with an empty graph.

directed

indicates whether or not the graph is directed. By default directed = FALSE. If the graph is directed, the edges have arrows indicating direction, and there are three slide bars to control the repulsion parameters. For an undirected graph there is a single control.

running

indicates whether or not the viewer is started with the animation running. By default running = TRUE.

Details

Creates and starts a 'Java' graphical user interface (GUI) showing a real time animation of a Newton-Raphson optimization of a force function specified between the vertices of an arbitrary graph. There are attractive forces between adjacent vertices and repulsive forces between all vertices. The repulsions go smoothly to zero in a finite distance between vertices so that, unlike some other methods, different components don't send each other off to infinity.

The program is controlled by a slide bar, some buttons, the arrow, home and shift keys, but mostly by mouse operations. All three mouse buttons are used. These operations are described below.

vg will replace rViewGraph, although the latter is still currently available. vg allows for far more control of the graph than rViewGraph, including adding and removing vertices and edges, and changing the appearance of the vertices, all of which can be done while the animation is running. It has a different set of force parameter controls that are useful for directed acyclic graphs (DAGs) specifically, but also, to a lesser extent, for arbitrary directed graphs. It also provides functions for saving and restoring a graphical state including vertices and edges, vertex positions, and vertex appearances.

vg is intended only for interactive use. When used in a non-interactive environment it immediately exits returning the value NULL. Otherwise, it returns a list of functions that specify and query the graph, and control the viewer.

Value

add(i)

If the graph does not contain vertices indexed by i, they are added to it. i may be any integer or integer vector.

remove(i)

If the graph contains vertices indexed by i, they are disconnected from their neighbours and removed from the graph. i may be any integer or integer vector.

connect(i,j)

If the graph does not have edges between vertices indexed by i and j, they are made. If i and j are of different lengths, only the first min(length(i),length(j)) values are used. If the relevant vertices are are not already in the graph, they are first made and added. i and j may be any integers or integer vectors.

disconnect(i,j)

If the graph has edges between vertices indexed by i and j they are removed. If i and j are of different lengths, only the first min(length(i),length(j)) values are used. The vertices themselves are not removed, even if they have no other neighbours. i and j may be any integers or integer vectors.

clear()

All vertices and edges are removed from the graph, however, any customizations made to the appearance of the vertices will persist until clearMap() is called.

isDirected()

Returns TRUE if the graph's edges are directed, FALSE otherwise.

getIds()

Returns a vector of all the vertex indices that the viewer has encountered, whether or not they are currently in the graph.

contains(id)

Returns a vector of booleans indicating whether the vertices corresponding to the given indices are currently in the graph.

connects(i,j)

Returns a vector of booleans indicating whether the vertices with the indices in vector i are connected to the corresponding vertices in j. If i and j are of different lengths, only first min(length(i),length(j)) values are queried.

neighbours(i)

Returns a list of vectors containing the neighbours of the vertices indexed by i. If the graph is directed, both in and out neighbours are included. If a vertex is unconnected, an empty vector is returned. If an index is for a vertex that is not currently in the graph, NULL is returned.

neighbors(i)

Alias for neighbours(i).

inNeighbours(i)

Returns a list of vectors containing the indices of vertices with edges from them to the ones in i. If the graph is undirected, this is the same as neighbours(i).

inNeighbors(i)

Alias for inNeighbours(i).

outNeighbours(i)

Returns a list of vectors containing the indices of vertices with edges to them from the ones in i. If the graph is undirected, this is the same as neighbours(i).

outNeighbors(i)

Alias for outNeighbours(i).

getVertices()

Returns a vector of the indices of all vertices currently in the graph.

getEdges()

Returns a matrix with 2 columns and a row for each edge in the current graph. Each row gives the indices of the vertices that the edge connects. If the edges are directed, the connections are oriented from vertices in the first column to those in the second.

getX(id)

Returns the current horizontal coordinates of the vertices with indices in id. Returns 0 if an index has not previously been seen.

getY(id)

Returns the current vertical coordinates of the vertices with indices in id. Returns 0 if an index has not previously been seen.

setXY(id, x, y)

Sets the horizontal and vertical coordinates for the vertices with indices in id. If x or y are not as long as id their values are repeated cyclically to get vectors of the right length.

label(i,lab=i)

Sets the strings shown on the vertices indexed by i to those specified by lab. If lab is not as long as i, its values are repeated cyclically to get a vector of the right length. An error will occur if lab can't be interpreted as a vector of strings.

colour(i,col="yellow")

Sets the colours of the vertices indexed by i to those specified by col. If col is not as long as i, its values are repeated cyclically to get a vector of the right length. Colours can be specified in the usual R ways.

color(i,col="yellow")

Alias for colours(i,col).

shape(i,shp=0)

Sets the shapes of the vertices indexed by i to those specified by shp. If shp is not as long as i, its values are repeated cyclically to get a vector or the right length. Shapes are specified as integers:

  • 0 = rectangle

  • 1 = oval

  • 2 = diamond

  • any other values are taken as 0.

size(i,width=-1,height=width)

Sets the sizes of the vertices indexed by i to those specified by width and height. If, for a certain index, both width and height are non-negative, the size of the vertex is fixed. If either of width or height is negative, the size of the vertex is chosen adaptively to fit the current label. If width or height are not as long as i, their values are repeated cyclically to get vectors of the right length.

map(i,lab=i,col="yellow",shp=0,width=-1,height=width

Combines label(), colour(), shape() and size() in a single index-to-appearance mapping function. These functions can be called before or after the vertices have been added to the graph, and the representations will persist for vertices removed from, and replaced in, the graph until until they are explicitly changed or clearMap() is called.

clearMap()

Resets all vertices to the default appearance of yellow rectangle labeled with the index.

run()

Starts the GUI running if it's not already doing so.

stop()

Stops the GUI running if it's running.

isRunning()

Returns TRUE if the animation is running, FALSE otherwise.

show()

Shows the GUI. If it was running when hide() was called, it starts running again.

hide()

Stops the GUI and hides it.

showPaper(size = "letter", landscape = TRUE)

Indicates, with a different colour, the portion of the plane corresponding to a choice of paper for printing. size can be any of letter, A4, A3, A2, A1, A0, C1, or C0. landscape can be either TRUE or FALSE, in which case portrait orientation is used. The default is to show the portion of the plane that would be printed on US letter in landscape orientation.

hidePaper()

By default the GUI indicates, with a different colour, the portion of the plane that corresponds to the current choice of paper for printing. This function removes that area.

showAxes()

Shows the axes if they are hidden.

hideAxes()

By default, axes are shown to indicate the origin. This function hides them.

ps()

Starts a Java PostScript print job dialog box that can be used send the current view of the graph to a printer or to write a PostScript file. The plot produced should closely match what is indicated by showPaper.

save()

Returns a list specifying the current state of the graph structure, vertex coordinates, and vertex appearance map.

restore(grob)

Restores a saved graph and map state.

Interactive mouse, key and slide bar controls

Author(s)

Alun Thomas

References

A full description of the force function and algorithm used is given by C Cannings and A Thomas, Inference, simulation and enumeration of genealogies. In D J Balding, M Bishop, and C Cannings, editors, The Handbook of Statistical Genetics. Third Edition, pages 781-805. John Wiley & Sons, Ltd, 2007.

See Also

rViewGraph

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# Start the viewer.
require(rviewgraph)
v = vg()

# Check that the viewer was made. 
# Not usually necessary in interactive mode.
if (!is.null(v))
{
	# Generate some random vertices to connect with edges.
	from = sample(1:20,15,TRUE)
	to = sample(1:20,15,TRUE)

	# Connect these edges in the viewer.
	v$connect(from,to)

	# Negative vertex indices are also allowed.
	v$connect(-from,-to)

	# Add some new vertices, unconnected to any others.
	v$add(30:35)

	# Remove some vertices.
	v$rem((-5:5)*2)

	# Query some of the structure of the graph.
	v$contains(1)
	v$contains(-1)
	v$connects(1,-1)
	v$contains(1:50)
	v$connects(from,to)
	v$connects(from,-to+2)
v$neighbours(from)

	# Change what some of the vertices look like.
	v$map(-10:10, lab = "", col=1, shp=1, width=1:15)
	v$label(10:36, lab=LETTERS)
	v$colour((-1000:-1),"cyan")
	v$shape((-1000:-1)*2,2)

	# Hide the axes.
	v$hideAxes()

	# Stop the animation. 
	# Not necessary for outputting but sometimes helpful.
	v$stop()

	# Change the paper size and orientation to A4 portrait.
	v$showPaper("A4",F)

	# Start the print dialog box.
	v$ps()

	# Restart the animation, and check that it's running.
	v$run()
	v$isRunning()

	# Save the application.
	s = v$save()

	# Change the graph and appearance.
	v$colour(-1000:1000,"red")
	v$connect(rep(1,100),1:100)

	# Then decide you didn't like the changes so restore 
	# the saved state.
	v$restore(s)

	# Can also restore a state in a new GUI.
	v2 = vg(s)

	# Get a vector of all the indices that the viewer has seen.
	ids = v$getIds()

	# Get a vector of the indices of the vertices currently 
	# in the graph.
	verts = v$getVertices()

	# Get a matrix with 2 columns specifying the current edges 
	# of the graph.
	edges = v$getEdges()

	# Get the current coordinates of the specified vertices. 
	x = v$getX(verts)
	y = v$getY(verts)

	# Change the current coordinates of the vertices.
	v$setXY(verts,2*x,0.5*y+2)

}

rviewgraph documentation built on March 21, 2021, 1:09 a.m.