setTreeBlocks          package:dynamicGraph          R Documentation

_T_h_e _b_l_o_c_k _t_r_e_e

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

     Create a block tree with positioning the vertices in to blocks.

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

     setTreeBlocks(block.tree, vertices, root.label = "", N = 3,
                   delta = ifelse(overlaying, 1, 0), 
                   Delta = ifelse(overlaying, 0, 1.5),
                   d = 5, f = 1/4, blockColors = NULL, overlaying = FALSE)

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

block.tree: A structure with the blocks in a 'block.tree'. See below. 

vertices: The list of 'vertices', each containing the class
          'dg.Vertex'. Returned with positions set in the interval of
          the blocks. 

root.label: A text string with the 'root.label' of the root block. 

       N: Integer, 'N' is the number of coordinates of the vertices and
          block corners. 

   delta: Numeric. Decrement of block size for nested blocks, and space
          between blocks when 'overlaying' is TRUE. The decrement is 
          'delta' divided by 100, times the the size of the window
          canvas, width or height. 

   Delta: Numeric. Decrement of block size for nested blocks, and space
          between blocks when 'overlaying' is FALSE.  The decrement is
          'Delta' divided by 100, times the the size of the window
          canvas, width or height. 

       d: Numeric. If not 'd' is given in 'block.tree', see below: The
          heading bar (with the label) has a height of ('d' + 2)
          divided by 100, times height of the window canvas. 

       f: Numeric. If not 'f' or 'g' is given in 'block.tree', see
          below: The the vertices of the block are placed in an array
          with a height (width if 'horizontal' is set to FALSE) of 'f'
          divided by 100, times height (width) of the block.  Thus this
          size is relative to the block size. 

blockColors: Vector of text string with the 'blockColors' of the
          blocks. 

overlaying: Logical. If 'overlaying' is set to FALSE then children
          blocks of a block are not drawn inside the block. 

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

     A recursive definition: 'Block.tree' is a list with the vertices
     of the "current" blocks, some parameters for controlling the
     layout, and possible some 'block.trees':

   '...$_V_e_r_t_i_c_e_s' The 'vertices' of the block. 

   '...$_l_a_b_e_l' A text string for the 'label' of the block.  Will
        overwrite '"block-name"' and  'root.label'. 

   '...$_d' Numeric. The heading bar (with the label) has a height of
        ('d' + 2) divided by 100, times the height of the window
        canvas. 

   '...$_g' Numeric. The vertices of the block are placed in an array
        with a height  (width if 'horizontal' is set to FALSE) of 'g'
        divided by 100, times the height (width) of the window canvas. 
        Thus this size will not decrease with the block size.

   '...$_f' Numeric. If not 'g' is given: The the vertices of the block
        are placed in an array with a height (width if 'horizontal' is
        set to FALSE) of 'f' divided by 100, times the height (width)
        of the block.  Thus this size is relative to the block size. 

   '...$_G' Numeric. (If the height of the block is 100 we are now left
        with  '100 - 2 * delta - d - 2 - g' for the blocks. ) The sub
        blocks (apart from 'common.children') then have a of height 
        (width, if 'horizontal' is set to FALSE) of 'G' divided by 100,
        times the height (width) of the window canvas.  Thus the sub
        block size will not decrease with the block size. (If the
        height of the block is 100 we are now left with  '100 - 2 *
        delta - d - 2 - g - G' for the 'common.children'. )

   '...$_F' Numeric. If not 'G' is given: The proportion 'G' of the
        remaining space  are used for sub blocks (apart from
        'common.children') and the proportion 'G' of the space for
        blocks are used for 'common.children'.

   '...$_h_o_r_i_z_o_n_t_a_l' Logical. If 'horizontal' is set to TRUE, then the
        sub blocks, but 'common.children', are placed side by side,
        else the blocks are placed vertically. 

   '...$_c_l_o_s_e_d' Logical. If 'closed' is set to TRUE, then the block is
        initially drawn "closed", and the vertices and sub blocks of
        the block are not visible. 

   '...$_v_e_r_t_i_c_e_s._l_a_s_t' Logical. If 'vertices.last' then the vertices of
        the block are placed after the sub blocks. 

   '...$"_b_l_o_c_k-_n_a_m_e"' '= list(...)' Repeated zero, one or more times
        for sub blocks. '"block-name"' is the label of the block, and
        'list(...)' is a 'Block.tree'. 

   '...$_c_o_m_m_o_n._c_h_i_l_d_r_e_n' '= list(...)' Omitted, or a list with common
        children of the other sub blocks of the block.  The list is
        again a 'Block.tree'. 

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

     A list with components 

BlockTree: A tree of blocks, each of class 'dg.Block'. 

Vertices: The list of vertices, with the positions updated such the
          vertices has positions within the blocks. 

_N_o_t_e:

     Ancestors and descendants are set in 'setTreeBlocks'. Ancestors
     are used in the function 'returnBlockEdgeList' to find the edges
     between blocks and between blocks and vertices.

     Descendants are used in 'dynamicGraphMain' when closing, opening
     and moving blocks, and when adding or dropping edges from and to
     blocks.

     The methods 'NodeAncestors', 'NodeAncestors<-' 'NodeDescendants'
     and 'NodeDescendants<-' can be used on the block list resulting of
      'blockTreeToList' on the block tree.

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

     Jens Henrik Badsberg

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

     # Example 1:

     Block.tree <- list(label = "W", Vertices = c("country"),
                        X = list(Vertices = c("race", "sex"),
                                 A = list(Vertices = c("hair", "eye"),
                                          horizontal = FALSE),
                                 B = list(Vertices = c("education"),
                                          C = list(Vertices = c("age")))))
     V.Names <- unlist(Block.tree)
     vertices <- returnVertexList(V.Names[grep("Vertices", names(V.Names))])
     blocktree <- setTreeBlocks(Block.tree, vertices)

     Positions(blockTreeToList(blocktree$BlockTree))
     Positions(blocktree$Vertices)
     NodeAncestors(blockTreeToList(blocktree$BlockTree))
     NodeDescendants(blockTreeToList(blocktree$BlockTree))

     vertexStrata <- Strata(blocktree$Vertices)
     vertexStrata
     vertexNames <- Names(blocktree$Vertices)
     names(vertexNames) <- NULL
     vertexNames

     # Indices of the vertices in blocks:

     indicesInBlock <- vector("list", max(vertexStrata))
     for (i in seq(along = vertexStrata))
       indicesInBlock[[vertexStrata[i]]] <- 
         append(indicesInBlock[[vertexStrata[i]]], i) 
     str(indicesInBlock)

     # Names of the vertices in blocks:

     vertexNamesInblock <- vector("list", max(vertexStrata))
     for (i in seq(along = vertexStrata))
       vertexNamesInblock[[vertexStrata[i]]] <- 
         append(vertexNamesInblock[[vertexStrata[i]]], vertexNames[i]) 
     str(vertexNamesInblock)

     # A useful function, replace "k" (block index k) 
     # in block "i" by "x[k]", the content "x[k]" of block "k":

     f <- function(A, x) {
       result <- vector("list", length(A))
       names(result) <- names(A)
       for (i in seq(along = A))
         if ((length(A[[i]]) > 0) && (A[[i]] != 0))
           for (k in A[[i]])
             result[[i]] <- append(result[[i]], x[k])
       return(result)
     }

     # For each block, names of vertices in ancestor blocks:

     vertexAncOfBlock <- f(NodeAncestors(blockTreeToList(blocktree$BlockTree)), 
                           vertexNamesInblock)
     str(vertexAncOfBlock)

     for (i in seq(along = vertexAncOfBlock))
       if (length(vertexAncOfBlock[[i]]) > 0)
         vertexAncOfBlock[[i]] <- unlist(vertexAncOfBlock[[i]])
     str(vertexAncOfBlock)

     # For each block, names of vertices in descendant blocks:

     vertexDesOfBlock <- f(NodeDescendants(blockTreeToList(blocktree$BlockTree)),
                           vertexNamesInblock)
     str(vertexDesOfBlock)

     for (i in seq(along = vertexDesOfBlock))
       if (length(vertexDesOfBlock[[i]]) > 0)
         vertexDesOfBlock[[i]] <- unlist(vertexDesOfBlock[[i]])
     str(vertexDesOfBlock)

     # Example 2:

     Block.tree <-
       list(g = 0, G = 54, label = "Pedegree.G",
            Male.Side = 
            list(g = 0, G = 33,
                 Father = 
                 list(g = 0, G = 12,
                      P.G.Father = list(Vertices = c("P.G.Father.1")),
                      P.G.Mother = list(Vertices = c("P.G.Mother.1")),
                      common.children = list(g = 0, label = "Father.1",
                                             Vertices = c("Father.1"))),
                 Mother = 
                 list(g = 0, G = 12,
                      M.G.Father = list(Vertices = c("M.G.Father.1")),
                      M.G.Mother = list(Vertices = c("M.G.Mother.1")),
                      common.children = list(g = 0, label = "Mother.1",
                                             Vertices = c("Mother.1"))),
                 common.children = list(g = 2, Vertices = c("Male"))),
       Female.Side = list(g = 0, G = 12,
         P.G.Father = list(Vertices = c("P.G.Father.2")),
         P.G.Mother = list(Vertices = c("P.G.Mother.2")),
         M.G.Father = list(Vertices = c("M.G.Father.2")),
         M.G.Mother = list(Vertices = c("M.G.Mother.2")),
         common.children = list(g = 0, G = 12, label = "Female",
           Father = list(Vertices = c("Father.2")),
           Mother = list(Vertices = c("Mother.2")),
           common.children = list(g = 2, Vertices = c("Female")))),
       common.children = list(Vertices = c("Marriage"), g = 3, label = "Children",
         Son = list(Vertices = c("Son"), g = 3, 
            P.G.Son = list(Vertices = c("P.G.Son"), g = 2),
            P.G.Dat = list(Vertices = c("P.G.Dat"), g = 1)),
         Dat = list(Vertices = c("Dat"), g = 2,
            M.G.Son = list(Vertices = c("M.G.Son")),
            M.G.Dat = list(Vertices = c("M.G.Dat")))
         )
     )

     v <- unlist(Block.tree)
     V.Names <- v[grep("Vertices", names(v))]
     rm(v)

     FromTo <- matrix(c("P.G.Father.1", "Father.1", "P.G.Father.2", "Father.2", 
                        "P.G.Mother.1", "Father.1", "P.G.Mother.2", "Father.2", 
                        "M.G.Father.1", "Mother.1", "M.G.Father.2", "Mother.2", 
                        "M.G.Mother.1", "Mother.1", "M.G.Mother.2", "Mother.2", 
                        "Father.1",     "Male",     "Father.2",     "Female",   
                        "Mother.1",     "Male",     "Mother.2",     "Female",   
                        "Male",         "Marriage", "Female",       "Marriage",
                        "Marriage",     "Son",      "Marriage",     "Dat",
                        "Son",          "P.G.Son",  "Dat",          "M.G.Son", 
                        "Son",          "P.G.Dat",  "Dat",          "M.G.Dat"), 
                        byrow = TRUE, ncol = 2)

     From <- match(FromTo[,1], V.Names)
     To   <- match(FromTo[,2], V.Names)

     V.Types <- rep("Discrete", length(V.Names))

     Object <- NULL

     graph <- new("dg.simple.graph", vertex.names = V.Names, types = V.Types,
                  from = From, to = To, block.tree = Block.tree)

     W <- dg(graph,
             control = dg.control(width = 600, height = 600, 
                                  drawblocks = TRUE, drawBlockFrame = TRUE, 
                                  overlaying = TRUE, title = "Pedegree.G"))

