dynamicGraphMain {dynamicGraph}R Documentation

Dynamic Graph

Description

Interactive plot for manipulating graphs.

Usage

dynamicGraphMain(vertexList, visibleVertices = 1:length(vertexList),
                 edgeList = NULL, blockList = NULL, blockEdgeList = NULL,
                 blockTree = NULL, oriented = FALSE,
                 factorVertexList = NULL, factorEdgeList = NULL, 
                 extraList = NULL,
                 object = NULL, objectName = "", 
                 vertexClasses = validVertexClasses(),
                 title = "dynamicGraph", transformation = NULL, 
                 width = 400, height = 400, w = 6, 
                 vertexColor = "blue", extraVertexColor = "black", 
                 edgeColor = "blue",
                 factorVertexColor = "green", factorEdgeColor = "green",
                 blockEdgeColor = "default", blockColors = NULL,
                 background = "white", closeenough = 2,
                 drawBlockFrame = TRUE, drawBlockBackground = TRUE,
                 UserMenus = NULL, 
                 hasMethods = TRUE, enterLeaveUpdate = TRUE,
                 namesOnEdges = TRUE, updateEdgeLabels = TRUE,
                 debug.strata = FALSE, debug.edges = FALSE,
                 debug.position = FALSE, debug.update = FALSE, ...)

Arguments

vertexList List of vertices (each of class containing the class VertexProto) created by returnVertexList or exported from dynamicGraphMain.
visibleVertices Numeric vector of the indices of the vertices of vertexList to plot.
edgeList List of edges (of class containing EdgeProto) created by returnEdgeList or exported from dynamicGraphMain.
blockList List of blocks (each of class BlockProto) created by setBlocks or exported from dynamicGraphMain. If the blockTree argument is given, then the argument blockList should not also be given.
blockEdgeList List of blockedges (of class containing the class BlockEdgeProto) created by returnBlockEdgeList or exported from dynamicGraphMain.
blockTree Structure with blocks (of class BlockProto) created by setTreeBlocks or exported from dynamicGraphMain.
oriented Logical. If TRUE then edges are oriented, also when blocks are missing.
factorVertexList List of secondary vertices, called factor vertices, for, e.g., the generators of the model, (each of class containing FactorVertexProto) created by returnFactorVerticesAndEdges or exported from dynamicGraphMain.
factorEdgeList List of bipartite graph edges, called factor edges, (each of class containing FactorEdgeProto) created by returnFactorEdgeList or exported from dynamicGraphMain. Factor edges are edges between vertices and factor vertices.
extraList List of vertices (of class containing the class VertexProto) created by returnVertexList or exported from dynamicGraphMain, for, e.g., additional titles in the plot.
object NULL, or object with the methods modifyModel and testEdge - for respectively updating the object when the graph is updated, and for computing the test statistic when an edge is labeled. The returned object from testEdge should have the methods label and width for extracting the label of a test for putting the label on the edge and for extracting the width for the edge. See newDefaultModelObject.
objectName If set to a text string then the object is assigned with this name in .Global.Env when the object is updated.
vertexClasses Returned value from validVertexClasses, or extension of this matrix. Used when creating new vertices in dynamicGraphMain.
title Text string with the title set on the graph window.
transformation NULL, or rotation matrix for projecting the positions of the vertices, blocks, etc. onto the canvas.
width Integer with the width of the plot canvas.
height Integer with the height of the plot canvas.
w The radius of the vertices. Send as argument to the draw method for vertices, and edges are shortened by the quantity in each end.
vertexColor Single text string. Colors of new vertices created in dynamicGraphMain (by newVertex). The colors of the vertices of vertexList are given in this list. vertexColor is given as argument to the draw method of vertices, but this argument are by default not used in the draw method.
extraVertexColor Single text string. As vertexColor, but for the vertices of extraList.
edgeColor Single text string. edgeColor is similar to vertexColor.
factorVertexColor Single text string. factorVertexColor is similar to vertexColor. If factorVertexColor is "default" then the color of a factor vertex will depend on the type of the generator of the factor.
factorEdgeColor Single text string. factorEdgeColor is similar to edgeColor.
blockEdgeColor "default", or list with two text strings for colors. blockEdgeColor is similar to edgeColor. The two colors are used for respectively edges between two blocks and for edges between blocks and vertices.
blockColors List of colors of blocks. Similar to vertexColor: Only used when creating new blocks, else the colors set in blockList and blockTree are used.
background The color of the canvas of the graph window, default: "white".
closeenough Parameter for whether the mouse is close enough when clicking an object of the graph window, see tkcanvas.
drawBlockFrame Logical. If TRUE then frames are drawn around blocks.
drawBlockBackground Logical. If TRUE then a block canvas is drawn, with color set by blockColors.
UserMenus List with user defined menu items for main menu and pop up menus. See redrawGraphWindow for an example of a user specified menu.
hasMethods Logical. If TRUE then the object should have the methods modifyModel and testEdge. (I do not know why the R-function hasMethod does not work on objects (defined outside the package dynamicGraph) inside dynamicGraphMain).
enterLeaveUpdate Logical. If FALSE then the graph window is not redrawn when the mouse enters and leaves the graph window.
namesOnEdges Logical. If FALSE then the names of the vertices are not set on the edge as label.
updateEdgeLabels Logical. If FALSE then the edge labels are not cleared when the model is updated.
debug.strata Logical for tracing strata of vertices (also in plot).
debug.edges Logical for tracing edges (also by labels in plot).
debug.position Logical for tracing positions of vertices.
debug.update Logical for tracing redraw of graph window.
... Additional arguments.

Details

This is a dynamic plotting tool for handling graphs. The lay out of the graph can be edited by moving the vertices of the graph by the mouse, and edges can be added by clicking vertices and dropping by clicking the edges.

The function is incremental in the sense that the user can add a method for updating the model object of the window when the graph is updated, and a method for computing the test of an edge when the edge is clicked by the mouse.

Edges can be oriented, drawn by arrows.

Blocks can be used to define a causal structure of the variables represented by vertices, and edges between blocks are then oriented. Blocks can be given in a structure such that descendant blocks of a blocks also are closed when a block is closed.

A secondary set of vertices, factor vertices, can be used to represent hypergraphs.

"Slave graph windows" can be created: The windows will share vertices and blocks, thus when a vertex is moved in one window, the position of the vertex will also change in all slave windows. The edges are not shared among windows, since the individual windows will typical represent different models. Thus factors (vertices and edges) are not shared between graph windows.

Value

Object of class GraphLatticeProto. Might, beside the list of canvases of the graph window and slave windows, also hold lists of vertices and blocks (block trees).

...@graphs Slot 'graphs': List of class CanvasProto. Might, beside slots for accessing the graph window, also hold slots for edges, factors, factor edges, block edges, etc.
...@graphs[[i]]@top Slot 'top' of each object in the list of the 'graphs' slot of the returned object: The 'top' of the canvas of the i-the graph window.

All object in the graph window:

Vertices (vertices and factor vertices):

Right click the vertex to get the pop up menu of the vertex:

The main menu "Variables":

Edges (edges to/from vertices, blocks and factors):

Right click the edge to get the pop up menu of the edge:

The main menu "Edges":

Blocks, opened:

Right click the block label (or colored block canvas if drawBlockBackground is set to TRUE) to get the pop up menu of opened block:

Blocks, closed:

Right click the block to get the pop up menu of the closed block:

The main menu "Blocks":

Factor vertices:

Right click the factor vertex to get the pop up menu of the factor: Actions as for vertices. The main menu "Generators":

Factor edges:

Right click the factor edge to get the pop up menu of the factor edge: Actions are as for edges.

The graph:

Rotation:

Acknowledgments

Many thanks to the gR-group for useful discussions, especially to Claus Dethlefsen for testing early versions of this package on DEAL.

Note

Vertices, edges, blocks, block edges, factors, and factor edges are objects of the following classes: VertexProto, EdgeProto, and BlockProto contains NodeProto, FactorVertexProto contains VertexProto, and VertexEdgeProto, BlockEdgeProto, FactorEdgeProto contains EdgeProto.

The methods draw, color, color<-, label, label<-, labelPosition, labelPosition<-, name, name<-, index, index<-, position, position<-, stratum, stratum<-, visible, visible<-, addToPopups, oriented, oriented<-, width, width<-, nodeIndicesOfEdge, nodeIndicesOfEdge<-, nodeTypesOfEdge, ancestors, ancestors<-, descendants, and descendants<-, are implemented for objects of these classes.

For lists of vertices, edges, blocks, block edges, factors, and factor edges the methods Names, Names<-, Colors, Colors<-, Labels, Labels<-, LabelPositions, LabelPositions<-, Positions, Positions<-, Strata, Strata<-, Indices, NodeAncestors, NodeAncestors<-, NodeDescendants, and NodeDescendants<- are available.

The block tree created by setTreeBlocks is unlisted by blockTreeToList such that the above methods can be applied.

The model object of the call of dynamicGraphMain should have the methods modifyModel and testEdge. When the graph is modified, by adding or dropping vertices or edge, the method modifyModel is called on the argument object of dynamicGraphMain. If an object is returned in the list of the returned value from modifyModel then object in dynamicGraphMain is replaced by this object, and the object is also assigned in the top level environment, if objectName was given to dynamicGraphMain.

The method testEdge of object should return an object with the methods label and width for labeling edges, see newDefaultTestObject.

Author(s)

Jens Henrik Badsberg

References

CoCo, avaliable form http://www.math.auc.dk/gr/material/CoCo and http://www.jbs.agrsci.dk/ Biometry/Software-Datasets/CoCo/CoCo.1.6/ with a guide at http://www.jstatsoft.org/v06/i04/, has an interface to dynamicGraph.

See Also

See also DynamicGraph and all the other functions of this package.

An example has been divided on the following 4 manual pages: newDefaultModelObject and newDefaultTestObject gives an example of a model object with test object. The pages of redrawGraphWindow show how the user can add menu items with actions that redraws the graph after modification of edges. Finally, validVertexClasses show how to create a new vertex class with a new symbol for drawing the vertex and an item added to the pop up menu of the new vertex class. The files ".../dynamicGraph/Tests/Circle.newClass.R" of the example catalog of dynamicGraph will do this example collected from these 4 pages.

Examples


require(tcltk)
require(dynamicGraph)

V.Names <- paste(c("Sex", "Age", "Eye", "FEV", "Hair", "Shosize"),
                 1:6, sep ="/")

V.Types <- c("Discrete", "Ordinal", "Discrete",
             "Continuous", "Discrete", "Continuous")

Vertices <- returnVertexList(V.Names, types = V.Types, color = "red")

From <- c(1, 2, 3, 4, 5, 6)
To   <- c(2, 3, 4, 5, 6, 1)

EdgeList <- vector("list", length(To))
for (j in seq(along = To)) EdgeList[[j]] <- c(From[j], To[j])
Edges <- returnEdgeList(EdgeList, Vertices, color = "black")

Z <- dynamicGraphMain(Vertices, edgeList = Edges, w = 4)


[Package Contents]