dynamicGraphMain        package:dynamicGraph        R Documentation

_D_y_n_a_m_i_c _G_r_a_p_h

_D_e_s_c_r_i_p_t_i_o_n:

     Interactive plot for manipulating graphs.

_U_s_a_g_e:

     dynamicGraphMain(vertexList = NULL, blockList = NULL, 
                      dg = NULL, object = NULL, objectName = NULL, 
                      control = dg.control(...), ...)

_A_r_g_u_m_e_n_t_s:

vertexList: List of vertices (each of class containing the class
          'dg.Vertex') created by 'returnVertexList' or exported from
          'dynamicGraphMain'. 

blockList: List of blocks (each of class 'dg.Block') created by
          'setBlocks' or exported from 'dynamicGraphMain'. 

      dg: 'dg' is an object of class 'dg.graphedges-class'. 

  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. 

 control: Options for 'dynamicGraphMain', see 'dg.control'. 

     ...: Additional arguments. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_A_l_l _o_b_j_e_c_t _i_n _t_h_e _g_r_a_p_h _w_i_n_d_o_w::

   _L_e_f_t _c_l_i_c_k, _h_o_l_d _a_n_d _d_r_a_g: The object will move.

   _L_e_f_t _c_l_i_c_k: Action to the object: Vertices, edges, and blocks will
        highlight,  at vertices and blocks edges are added after
        highlighting, tests are computed for edge labels.

   _L_e_f_t _o_r _r_i_g_h_t _c_l_i_c_k, _w_i_t_h _S_H_I_F_T _o_r/_a_n_d _C_O_N_T_R_O_L: The object will be
        marked.

   _D_o_u_b_l_e _l_e_f_t _c_l_i_c_k: Action to object: Vertices and edges are deleted,
        blocks will close, closed blocks will open.

   _R_i_g_h_t _c_l_i_c_k: The pop up menu of the object will appear.

_V_e_r_t_i_c_e_s (_v_e_r_t_i_c_e_s _a_n_d _f_a_c_t_o_r _v_e_r_t_i_c_e_s)::

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

   _H_i_g_h_l_i_g_h_t _a _v_e_r_t_e_x: For adding an edge - Left click the vertex.

   _H_i_g_h_l_i_g_h_t _a _v_e_r_t_e_x: For adding to "selectedNodes" - Left or right
        click the vertex while holding SHIFT or/and CONTROL down.

   _M_a_r_k _a _v_e_r_t_e_x: For adding edges, etc. -  Left or right click the
        vertex while holding SHIFT or/and CONTROL down.

   _C_a_n_c_e_l _h_i_g_h_l_i_g_h_t_i_n_g: Left click (or drag) the vertex.

   _A_d_d _a_n _e_d_g_e: After first highlighting a vertex -  Left click the
        other vertex.

   _M_o_v_e _a _v_e_r_t_e_x: Left click and drag the vertex.

   _M_o_v_e _a _v_e_r_t_e_x _l_a_b_e_l: Left click and drag the label of the vertex.

   _D_e_l_e_t_e _a _v_e_r_t_e_x: Double left click the vertex.

   _C_r_e_a_t_e _n_e_w _g_r_a_p_h: A slave window with the vertex delete - Select
        "Drop vertex" from pop up menu at the vertex.

   _C_h_a_n_g_e _a _v_e_r_t_e_x _l_a_b_e_l: Double left click the label, and enter the
        new label in the appearing dialog window.

   _D_e_l_e_t_e _a _v_e_r_t_e_x _l_a_b_e_l: Select "Delete vertex label" from the pop up
        menu at the vertex or at the vertex label.

   _C_r_e_a_t_e _n_e_w _v_e_r_t_e_x: At mouse position - Middle click the canvas.

   _C_r_e_a_t_e _n_e_w _v_e_r_t_e_x: At mouse position with the edge to last vertex -
        Double middle click the canvas.

     The main menu "Variables":

   _C_r_e_a_t_e _n_e_w _v_a_r_i_a_b_l_e: With setting the class of the new vertex and
        defining an expression for updating the 'object' - Select
        "Create new variable". 

   _D_i_s_p_l_a_y, _a_d_d, _a _v_e_r_t_e_x: In the current window - Select "Select
        vertex among variables not displayed (here)". 

   _D_i_s_p_l_a_y, _a_d_d, _a _v_e_r_t_e_x: In a slave window - Select "Select vertex
        among variables not displayed (slave)". 

   _E_x_p_o_r_t _t_h_e _v_e_r_t_e_x _l_i_s_t: Select "Assign 'vertexList' in .GlobalEnv". 

   _E_x_p_o_r_t _t_h_e _l_a_b_e_l_s: Select "Assign 'extraList' in .GlobalEnv". 

_E_d_g_e_s (_e_d_g_e_s _t_o/_f_r_o_m _v_e_r_t_i_c_e_s, _b_l_o_c_k_s _a_n_d _f_a_c_t_o_r_s)::

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

   _H_i_g_h_l_i_g_h_t _a _e_d_g_e: Left click the edge.

   _H_i_g_h_l_i_g_h_t _a _e_d_g_e: For adding to "selectedEdges" - Left or right
        click the edge while holding SHIFT or/and CONTROL down.

   _A_d_d _a_n _e_d_g_e: Left click first the vertex (or block) to highlight,
        and then left click other vertex (or block).

   _D_e_l_e_t_e _a_n _e_d_g_e: And update in the current window - Double left click
        the edge.

   _D_e_l_e_t_e _a_n _e_d_g_e: And create a slave graph with the resulting graph -
        Select "Drop edge" from the pop up menu at the edge.

   _M_o_v_e _a_n _e_d_g_e (_2 _v_e_r_t_i_c_e_s): Left click the edge and drag the edge.

   _M_o_v_e _a_n _e_d_g_e _l_a_b_e_l: Left click the edge label and drag the label.

   _S_e_t _a_n _e_d_g_e _l_a_b_e_l: Select "Set edge label" from the edge pop up
        menu.

   _C_o_m_p_u_t_e _a_n _e_d_g_e _l_a_b_e_l: Left click the edge label, or select "Compute
        edge label" from pop up menu at the edge.

   _C_o_m_p_u_t_e _a_n _e_d_g_e _l_a_b_e_l: Force computation for "harder models" -
        Double left  click the edge label, or select "Force compute
        edge label" from pop up menu of the edge.

   _D_e_l_e_t_e _a_n _e_d_g_e _l_a_b_e_l: Triple left click the edge label, or select
        "Delete label of edge" from the pop up menu at the edge.

     The main menu "Edges":

   _D_e_l_e_t_e _a_l_l _e_d_g_e _l_a_b_e_l_s: Select "Delete all edge labels". 

   _E_x_p_o_r_t _t_h_e _e_d_g_e _l_i_s_t: Select "Assign 'edgeList' in .GlobalEnv". 

_B_l_o_c_k_s, _o_p_e_n_e_d::

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

   _M_o_v_e _a _b_l_o_c_k: With its sub blocks and vertices -  Left click the
        block label or colored block canvas and drag the block. [ Slow
        !!!]  

   _R_e_s_i_z_e _a _b_l_o_c_k: Left click a block corner or a block edge and drag. 

   _M_i_n_i_m_i_z_e _a _b_l_o_c_k: With its sub blocks and vertices -  Double left
        click the block label or the colored block canvas.

   _M_a_x_i_m_i_z_e _a _b_l_o_c_k: Zoom to the block - Right click the block label or
        colored the block canvas and select "Maximize" in the appering
        popup menu. 

   _Z_o_o_m _o_u_t _t_o _t_h_e _f_u_l_l _g_r_a_p_h: Right click the block label or colored
        block canvas and select "Redraw (Zoom to) full graph" in the
        appearing block pop up menu. 

_B_l_o_c_k_s, _c_l_o_s_e_d::

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

   _H_i_g_h_l_i_g_h_t _a _b_l_o_c_k: For adding edges from all vertices of the block
        to a vertex or a block - Left click the block.

   _H_i_g_h_l_i_g_h_t _a _b_l_o_c_k: For adding to "selectedNodes" - Left or right
        click the block while holding SHIFT or/and CONTROL down.

   _M_a_r_k _a _b_l_o_c_k: For adding edges, etc. -  Left or right click the
        block while holding SHIFT or/and CONTROL down.

   _C_a_n_c_e_l _h_i_g_h_l_i_g_h_t_i_n_g: Of a block - Left click (or drag) the block.

   _A_d_d _e_d_g_e_s: To all vertices of block after highlighting first a block
        or a vertex - Click the other block.

   _M_o_v_e _a _c_l_o_s_e_d _b_l_o_c_k: Left click and drag the block.

   _M_o_v_e _a _b_l_o_c_k _l_a_b_e_l: Left click and drag the label of the block.

   _O_p_e_n _a _c_l_o_s_e_d _b_l_o_c_k: Double left click the block.

   _C_h_a_n_g_e _a _b_l_o_c_k _l_a_b_e_l: Double left click the label of the closed
        block,  and enter the new label in the appearing dialog window.

   _D_e_l_e_t_e _a _b_l_o_c_k _l_a_b_e_l: Select "Delete label of block" from the pop up
        menu at the block or the block label.

     The main menu "Blocks":

   _E_x_p_o_r_t _t_h_e _b_l_o_c_k _l_i_s_t: Select "Assign 'blockList' in .GlobalEnv". 

   _E_x_p_o_r_t _t_h_e _b_l_o_c_k _e_d_g_e_s: Select "Assign 'blockEdgeList' in
        .GlobalEnv". 

_F_a_c_t_o_r _v_e_r_t_i_c_e_s::

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

   _E_x_p_o_r_t _t_h_e _f_a_c_t_o_r _v_e_r_t_i_c_e_s: Select "Assign 'factorVertexList' in
        .GlobalEnv". 

   _E_x_p_o_r_t _t_h_e _f_a_c_t_o_r _e_d_g_e_s: Select "Assign 'factorEdgeList' in
        .GlobalEnv". 

_F_a_c_t_o_r _e_d_g_e_s::

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

_T_h_e _p_a_n_e_l _f_o_r _v_e_r_t_i_c_e_s::

   _H_i_g_h_l_i_g_h_t _v_e_r_t_e_x _n_a_m_e _f_o_r _a_d_d_i_n_g _o_r _d_e_l_e_t_i_n_g _v_e_r_t_e_x: Left click the
        vertex name.

   _D_e_l_e_t_e _o_r _a_d_d _v_e_r_t_i_c_e_s: Double left click a vertex name.

   _P_o_p_u_p _m_e_n_u _f_o_r _s_e_l_e_c_t_e_d _v_e_r_t_e_x: Click "Popup selected in panel" in
        "File Menu".

   _D_i_a_l_o_g _w_i_n_d_o_w _f_o_r _p_r_o_p_e_r_t_i_e_s: Middle click vertex name.

_T_h_e _p_a_n_e_l _f_o_r _b_l_o_c_k_s _i_n _t_r_e_e _a_n_d _v_e_r_t_i_c_e_s::

   _M_o_v_e _v_e_r_t_e_x _t_o _o_t_h_e_r _b_l_o_c_k: Left click the vertex name and drag to
        the other block.

   _M_o_v_e _b_l_o_c_k _t_o _o_t_h_e_r _b_l_o_c_k: Left click the block name and drag to the
        other block.

   _P_o_p_u_p _m_e_n_u _f_o_r _s_e_l_e_c_t_e_d _v_e_r_t_e_x _o_r _b_l_o_c_k : Click "Popup selected in
        panel" in "File Menu".

_T_h_e _g_r_a_p_h::

   _C_r_e_a_t_e _a _s_l_a_v_e _w_i_n_d_o_w: Select "Make slave window: Same model".

   _C_r_e_a_t_e _a _s_l_a_v_e _w_i_n_d_o_w: Select "Make slave window: Copy model".

   _S_w_i_t_c_h _c_l_a_s_s _o_f _v_i_e_w: Select "Set class of graph window".

   _R_e_f_r_e_s_h: Faster fix of "corrupted" window: Select "Refresh view (set
        positions as 'stored')".

   _R_e_d_r_a_w _t_h_e _v_i_e_w (_z_o_o_m _o_u_t): Select "Redraw graph window (more
        refreshing)".

   _U_p_d_a_t_e _m_o_d_e_l: Select "Update model and redraw (total refreshing)".

   _E_n_a_b_l_e _r_o_t_a_t_i_o_n: Select "Rest (enable) rotation".

   _D_i_s_a_b_l_e _r_o_t_a_t_i_o_n: Select "Disable rotation".

   _Z_o_o_m _i_n: Select "Zoom in" from main menu, or hit <F1> in canvas. 

   _Z_o_o_m _o_u_t: Select "Zoom out" from main menu, or hit <F2> in canvas.

   _E_x_p_o_r_t _c_u_r_r_e_n_t _a_r_g_u_m_e_n_t_s: Select "Assign 'Args' in .GlobalEnv".

   _E_x_p_o_r_t _t_h_e _m_o_d_e_l _l_a_t_t_i_c_e: Select "Assign 'frameModels' in
        .GlobalEnv".

   _E_x_p_o_r_t _t_h_e _g_r_a_p_h _l_a_t_t_i_c_e: Select "Assign 'frameViews' in
        .GlobalEnv".

   _E_x_p_o_r_t _t_h_e _g_r_a_p_h _w_i_n_d_o_w: Select "Assign 'graphWindow' in
        .GlobalEnv".

   _E_x_p_o_r_t _t_h_e _o_b_j_e_c_t: Select "Assign 'object' in .GlobalEnv".

_R_o_t_a_t_i_o_n::

   _E_n_a_b_l_e _r_o_t_a_t_i_o_n: Select "Enable (reset) transformation" from the
        main menu "Graph".

   _R_o_t_a_t_e _t_h_e _g_r_a_p_h: Middle click the canvas, and drag.

   _D_i_s_a_b_l_e _r_o_t_a_t_i_o_n: Select "Disable transformation" from the main menu
        "Graph".

   _E_x_p_o_r_t _t_r_a_n_s_f_o_r_m_a_t_i_o_n: Export the projection matrix - Select "Assign
        'transformation' in .GlobalEnv" from the main menu "Graph".

_A_c_k_n_o_w_l_e_d_g_m_e_n_t_s:

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

_N_o_t_e:

     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 model object of the call of 'dynamicGraphMain' should have the
     methods 'modifyModel', 'testEdge', 'graphEdges', and
     'setGraphEdges'. 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 'graphEdges' and 'setGraphEdges' are used to
     communicate the graph components between several views of the same
     model. The method 'graphEdges' of the model object is for
     returning an object of class 'dg.graphedges-class' to draw in the
     view, depending on the viewType. The method code{setGraphEdges} of
     the model object is called on the model object when the model is
     modified.

_A_u_t_h_o_r(_s):

     Jens Henrik Badsberg

_R_e_f_e_r_e_n_c_e_s:

     CoCo, with a guide at <URL: http://www.jstatsoft.org/v06/i04/>,
     has an interface to 'dynamicGraph'.

_S_e_e _A_l_s_o:

     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 'dg.graphedges-class' 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.

_E_x_a_m_p_l_e_s:

     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, control = dg.control(w = 4))

     graph <- new("dg.graph", vertexList = Vertices, edgeList = Edges)
     W <- dg(graph, control = dg.control(w = 4))

