dynamicGraphMain {dynamicGraph}R Documentation

Dynamic Graph

Description

Interactive plot for manipulating graphs.

Usage

dynamicGraphMain(vertexList, visibleVertices = 1:length(vertexList), 
    visibleBlocks = 1:length(blockList), edgeList = NULL, oriented = FALSE, 
    blockList = NULL, blockEdgeList = NULL, blockTree = NULL, 
    factorVertexList = NULL, factorEdgeList = NULL, 
    extraList = NULL, extraEdgeList = NULL, object = NULL, objectName = NULL, 
    vertexClasses = validVertexClasses(), 
    factorClasses = validFactorClasses(), 
    edgeClasses = validEdgeClasses(), 
    viewClasses = validViewClasses(), viewType = "Simple", 
    title = "dynamicGraph", 
    transformation = NULL, width = 400, height = 400, w = 6, 
    vertexColor = "blue", extraVertexColor = "black", edgeColor = "blue", 
    factorVertexColor = "green", 
    factorEdgeColor = "green", blockEdgeColor = "default", 
    blockColors = NULL, extraEdgeColor = "peru", background = "white", 
    closeenough = 2, setVertexLabels = FALSE, drawBlockFrame = TRUE, 
    drawBlockBackground = FALSE, UserMenus = NULL, hasMethods = TRUE, 
    enterLeaveUpdate = TRUE, updateAllViews = TRUE,
    namesOnEdges = TRUE, updateEdgeLabels = TRUE, useNamesForLabels = TRUE, 
    debug.strata = FALSE, debug.edges = FALSE, debug.position = FALSE, 
    debug.update = FALSE, permitZoom = TRUE, margin = 100, 
    returnLink = FALSE, returnNull = FALSE, ...) 

Arguments

vertexList List of vertices (each of class containing the class dg.Vertex) created by returnVertexList or exported from dynamicGraphMain.
visibleVertices Numeric vector of the indices of the vertices of vertexList to plot.
visibleBlocks Numeric vector of the indices of the blocks of blockList to plot.
edgeList List of edges (of class containing dg.Edge) created by returnEdgeList or exported from dynamicGraphMain.
blockList List of blocks (each of class dg.Block) 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 dg.BlockEdge) created by returnBlockEdgeList or exported from dynamicGraphMain.
blockTree Structure with blocks (of class dg.Block) 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 dg.FactorVertex) created by returnFactorVerticesAndEdges or exported from dynamicGraphMain.
factorEdgeList List of bipartite graph edges, called factor edges, (each of class containing dg.FactorEdge) 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 dg.Vertex) created by the functionreturnVertexList or exported from dynamicGraphMain, for, e.g., additional titles in the plot.
extraEdgeList List of edges between extra vertices and vertices.
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 dg.Model-class.
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.
factorClasses Returned value from validFactorClasses, or extension of this matrix. Used when creating new factor vertices in dynamicGraphMain.
edgeClasses Returned value from validEdgeClasses, or extension of this matrix. Used when creating new edges in dynamicGraphMain.
viewClasses Returned value from validViewClasses, or extension of this matrix. Used when creating new views in dynamicGraphMain.
viewType A text string with the type of view.
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.
extraEdgeColor Single text string. extraEdgeColor is similar to edgeColor.
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.
setVertexLabels Logical. If TRUE then the vertices are marked by the label, else the name.
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 redrawView 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.
updateAllViews Logical. If TRUE then all windows are updated when one is changed.
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.
useNamesForLabels Logical. If useNamesForLabels is TRUE then names are sued for labels.
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.
permitZoom Logical. If FALSE then zooming is disabled, and no margin around the canvas is set.
margin Integer, the width of the margin round the canvas.
returnLink Logical, if returnLink is TRUE then a reference to the dynamic graph window is returned, else an object of class DynamicGraph-class is returned (if not returnNull is TRUE).
returnNull Logical, if returnNull is TRUE then NULL is returned.
... 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

An object of class DynamicGraph-class (if not returnNull is TRUE) with the lists of vertices and blocks (block trees) of the dynamicGraph, and list of models, each (of class DynamicGraphModel-class) with the views of the model.
Each view (of class DynamicGraphView-class) of a model will hold the edges (edges between vertices, factors and blocks) and factor- and extra-vertices of the view, together with which vertices and blocks are visible in the view.
If returnLink is TRUE then the returned object will have functions for drawing other models and views associated with the returned DynamicGraph-class object.
The function drawModel of the returned object is used to add and draw other models, in an existing graph window or in a new slave graphs window, see DynamicGraph.
The function redrawView of the models of the returned object is used to draw other views of the model, in an existing graph window or in a new slave graphs window, see DynamicGraph.

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: dg.Vertex, dg.Edge, and dg.Block contains dg.Node, dg.FactorVertex contains dg.Vertex, and dg.VertexEdge, dg.BlockEdge, dg.FactorEdge contains dg.Edge.

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, testEdge, graphComponents, and setGraphComponents. 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 dg.Test-class.

The methods graphComponents and setGraphComponents are used to communicate the graph components between several views of the same model. The method graphComponents of the model object is for returning the objects to draw in the view, depending on the viewType. The methodsetGraphComponents of the model object is called on the model object when the model is modified.

By returnLink set to TRUE the functions drawModel, redrawView, and update, and variables top, canvas, viewLabel, and tags are returned in the object of the returned value. The function update is needed for DynamicGraph to be able to update all views when one view is changed, and the other functions and variables are needed for overwriting a view. When any of these values are present in the objects, R will save some environment of the Tcl/tk windows, and the saved workspace might be large.

Author(s)

Jens Henrik Badsberg

References

CoCo, 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: dg.Model-class and dg.Test-class gives an example of a model object with test object. The pages of drawModel 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 demo demo(Circle.newClass) 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]