HierarchicalGraph (gephi 0.8.2 API)

All Superinterfaces:

Attributable, Graph

All Known Subinterfaces:

HierarchicalDirectedGraph, HierarchicalMixedGraph, HierarchicalUndirectedGraph
```
public interface HierarchicalGraph
extends Graph
```
Implementation of graphs within graphs concept, by proposing methods to manipulate the hierarchy of nodes.
The hierarchical graph maintains a tree of all nodes, it's the hierarchy and a in-view flag for each. Note that 'view' means something else than for GraphView.
A node in the hierarchy view means it is visible and none of its ancestors or descendants are. If this node is expanded, it's children become 'in-view'. If it is retracted, its parent becomes 'in-view'. The hierarchy view can be modified with expand(), retract(), resetViewToLeaves(), resetViewToTopNodes() and resetViewToLevel(). Note that the nodes and edges returns by getNodes() or getEdges() use only nodes in the current view. To get all nodes in the hierarchy, see getNodesTree().

Author:

Mathieu Bastian

See Also:
GraphModel

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`addNode(Node node, Node parent)` Add `node` as a child of `parent` in the graph.
`void`	`clearMetaEdges(Node node)` Clears all meta edges for `node`.
`boolean`	`expand(Node node)` Expands the graph view from `node` to its children.
`void`	`flatten()` Flatten the hierarchy by keeping only nodes in the view and by transforming meta edges into edges.
`NodeIterable`	`getChildren(Node node)` Returns children of `node`.
`int`	`getChildrenCount(Node node)` Returns the number of children of `node`.
`NodeIterable`	`getDescendant(Node node)` Returns descendants of `node`.
`int`	`getDescendantCount(Node node)` Returns the number of descendant of `node`.
`EdgeIterable`	`getEdgesAndMetaEdges()` Return a unique `EdgeIterable` for edges and meta edges.
`EdgeIterable`	`getEdgesAndMetaEdges(Node node)` Returns edges and meta edges incident to `node`.
`EdgeIterable`	`getEdgesTree()` Similar as `Graph.getEdges()` but all nodes are visited in the hierarchy, so it returns edges for all possible nodes.
`int`	`getHeight()` Returns the height of the tree.
`EdgeIterable`	`getHierarchyEdges()`
`EdgeIterable`	`getInnerEdges(Node nodeGroup)` Returns edges incident to `nodeGroup` and `nodeGroup`'s descendants.
`int`	`getLevel(Node node)` Returns the level of `node` in the hierarchy.
`int`	`getLevelSize(int level)` The number of nodes located at the given `level` int the hierarchy.
`int`	`getMetaDegree(Node node)` Returns the degree for node's meta edges.
`MetaEdge`	`getMetaEdge(Node node1, Node node2)` Finds and returns a directed or undirected meta edge that connects `node1` and `node2`.
`EdgeIterable`	`getMetaEdges()` Returns meta edges for the whole graph.
`EdgeIterable`	`getMetaEdges(Node nodeGroup)` Returns meta edges for `nodeGroup`.
`NodeIterable`	`getNodes(int level)` Returns nodes at the given `level` in the hierarchy.
`NodeIterable`	`getNodesTree()` Similar as `Graph.getNodes()` but all nodes are visited, not only those in the current view.
`EdgeIterable`	`getOuterEdges(Node nodeGroup)` Returns edges not incident to `nodeGroup` or `nodeGroup`'s descendants.
`Node`	`getParent(Node node)` Returns the parent of `node` or `null` if `node`'s parent is (virtual) root.
`NodeIterable`	`getTopNodes()` Returns roots of the hierarchy forest.
`int`	`getTotalDegree(Node node)` Returns the sum of the degree and the meta-edge degree.
`int`	`getTotalEdgeCount()` Returns the number of edges and meta edges in the graph
`Node`	`groupNodes(Node[] nodes)` Group `nodes` into a new node group (i.e.
`boolean`	`isAncestor(Node node, Node ancestor)` Returns `true` if `ancestor` is an ancestor of `node`.
`boolean`	`isDescendant(Node node, Node descendant)` Returns `true` if `descendant` is a descendant of `node`.
`boolean`	`isFollowing(Node node, Node following)` Returns `true` if `following` is after `node`.
`boolean`	`isInView(Node node)` Returns true if `node` is currently in the graph view.
`boolean`	`isParent(Node node, Node parent)` Returns `true` if `parent` is the parent of `node`.
`boolean`	`isPreceding(Node node, Node preceding)` Returns `true` if `preceding` is before `node`.
`void`	`moveToGroup(Node node, Node nodeGroup)` Move `node` and descendants of `node` to `nodeGroup`, as `node` will be a child of `nodeGroup`.
`void`	`removeFromGroup(Node node)` Remove `node` from its parent group and append it to `node`'s parent.
`boolean`	`removeMetaEdge(Edge metaEdge)` Remove `metaEdge` from the graph.
`void`	`resetViewToLeaves()` Reset the current view to leaves of the clustered graph tree.
`void`	`resetViewToLevel(int level)` Reset the current view to nodes located at the specified `level` in the clustered graph hierarchy.
`void`	`resetViewToTopNodes()` Reset the current view to top nodes of the clustered graph tree.
`boolean`	`retract(Node node)` Retracts the graph view from `node`'s children to `node`.
`void`	`ungroupNodes(Node nodeGroup)` Ungroup nodes in `nodeGroup` and destroy `nodeGroup`.
`ImmutableTreeNode`	`wrapToTreeNode()` Returns the hierarchy tree of all nodes in the form of a `TreeNode`.

Methods inherited from interface org.gephi.graph.api.Graph
addEdge, addNode, clear, clearEdges, clearEdges, contains, contains, getDegree, getEdge, getEdge, getEdge, getEdgeCount, getEdges, getEdges, getEdgeVersion, getGraphModel, getNeighbors, getNode, getNode, getNodeCount, getNodes, getNodeVersion, getOpposite, getView, isAdjacent, isAdjacent, isDirected, isSelfLoop, readLock, readUnlock, readUnlockAll, removeEdge, removeNode, setId, setId, writeLock, writeUnlock

Methods inherited from interface org.gephi.graph.api.Attributable
getAttributes

- Method Detail
  - addNode
```
boolean addNode(Node node,
              Node parent)
```
    Add node as a child of parent in the graph. If parent is null, node is added as a child of the (virtual) root node. Fails if the node already exists.
    
    Parameters:
    node - the node to add
    parent - the existing node whose a child is to be added or null
    
    Returns:
    true if add is successful, false otherwise
    
    Throws:
    
    IllegalArgumentException - if node is null, or if parent is not legal in the graph
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - removeMetaEdge
```
boolean removeMetaEdge(Edge metaEdge)
```
    Remove metaEdge from the graph. Fails if the edge doesn't exist.
    
    Parameters:
    metaEdge - the meta edge that is to be removed
    
    Returns:
    true if remove is successful, false otherwise
    
    Throws:
    
    IllegalArgumentException - if edge is null or nodes not legal in the graph
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - getChildrenCount
```
int getChildrenCount(Node node)
```
    Returns the number of children of node. Returns zero if node is a leaf.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    
    Returns:
    the number of node's children
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - getDescendantCount
```
int getDescendantCount(Node node)
```
    Returns the number of descendant of node. Returns zero if node is a leaf.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    
    Returns:
    the number of node's descendant
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - getParent
```
Node getParent(Node node)
```
    Returns the parent of node or null if node's parent is (virtual) root.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node whose parent is to be returned
    
    Returns:
    node's parent
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - getChildren
```
NodeIterable getChildren(Node node)
```
    Returns children of node.
    
    Parameters:
    node - the node whose children are to be returned
    
    Returns:
    a node iterable of node's children
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - getDescendant
```
NodeIterable getDescendant(Node node)
```
    Returns descendants of node. Descendants are nodes which node is an ancestor.
    
    Parameters:
    node - the node whose descendant are to be returned
    
    Returns:
    a node iterable of node's descendant
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - getInnerEdges
```
EdgeIterable getInnerEdges(Node nodeGroup)
```
    Returns edges incident to nodeGroup and nodeGroup's descendants. Edges connected to nodes which are not descendant of nodeGroup are excluded.
    
    Parameters:
    nodeGroup - the node whose inner edges are to be returned
    
    Returns:
    an edge iterable of edges inner nodeGroup
    
    Throws:
    
    IllegalArgumentException - if nodeGroup is null or not legal in the graph
  - getOuterEdges
```
EdgeIterable getOuterEdges(Node nodeGroup)
```
    Returns edges not incident to nodeGroup or nodeGroup's descendants. Edges connected to nodes which are descendant of nodeGroup are excluded.
    
    Parameters:
    nodeGroup - the node whose outer edges are to be returned
    
    Returns:
    an edge iterable of edges outer nodeGroup
    
    Throws:
    
    IllegalArgumentException - if nodeGroup is null or not legal in the graph
  - getTopNodes
```
NodeIterable getTopNodes()
```
    Returns roots of the hierarchy forest. They are children of the tree's (virtual) root an have the level equal zero. If all nodes have the same level (i.e. no hierarchy) this method is similar as getNodes().
    
    Returns:
    a node iterable of nodes at the top of the tree
  - getNodesTree
```
NodeIterable getNodesTree()
```
    Similar as Graph.getNodes() but all nodes are visited, not only those in the current view.
    
    Returns:
    a node iterable of all nodes in the hierarchy
  - getEdgesTree
```
EdgeIterable getEdgesTree()
```
    Similar as Graph.getEdges() but all nodes are visited in the hierarchy, so it returns edges for all possible nodes.
    
    Returns:
    an edge iterable of all edges
  - getTotalEdgeCount
```
int getTotalEdgeCount()
```
    Returns the number of edges and meta edges in the graph
    Special case of interest:
    - Count self-loops once only.
    - For hierarchical graph, count edges incident only to nodes in the current view.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    Returns:
    the number of edges in the graph.
  - getNodes
```
NodeIterable getNodes(int level)
```
    Returns nodes at the given level in the hierarchy. Top nodes have the level zero and leaves' level is the height of the tree.
    
    Parameters:
    level - the level whose nodes are to be returned
    
    Returns:
    a node iterable of nodes located at level in the tree
    
    Throws:
    
    IllegalArgumentException - if level is not between 0 and the height of the tree
  - getLevelSize
```
int getLevelSize(int level)
```
    The number of nodes located at the given level int the hierarchy. Similar as getNodes(level).toArray().length.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    level - the level whose nodes are to be returned
    
    Returns:
    the number of nodes at level
    
    Throws:
    
    IllegalArgumentException - if level is not between 0 and the height of the tree
  - isDescendant
```
boolean isDescendant(Node node,
                   Node descendant)
```
    Returns true if descendant is a descendant of node. True if node is an ancestor of descendant.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    descendant - the descendant node to be queried
    
    Returns:
    true if descendant is a descendant of node
    
    Throws:
    
    IllegalArgumentException - if node or descendant is null or not legal in the graph
  - isAncestor
```
boolean isAncestor(Node node,
                 Node ancestor)
```
    Returns true if ancestor is an ancestor of node. True if node is a descendant of ancestor.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    ancestor - the ancestor to be queried
    
    Returns:
    true if ancestor is an ancestor of node
    
    Throws:
    
    IllegalArgumentException - if node or ancestor is null or not legal in the graph
  - isFollowing
```
boolean isFollowing(Node node,
                  Node following)
```
    Returns true if following is after node. The definition is similar to XML following axis. Is true when following has a greater pre and post order than node.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    following - the following to be queried
    
    Returns:
    true if following is following node
    
    Throws:
    
    IllegalArgumentException - if node or following is null or not legal in the graph
  - isPreceding
```
boolean isPreceding(Node node,
                  Node preceding)
```
    Returns true if preceding is before node. The definition is similar to XML preceding axis. Is true when preceding has a lower pre and post order than node.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    preceding - the preceding to be queried
    
    Returns:
    true if preceding is preceding node
    
    Throws:
    
    IllegalArgumentException - if node or preceding is null or not legal in the graph
  - isParent
```
boolean isParent(Node node,
               Node parent)
```
    Returns true if parent is the parent of node.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    parent - the parent to be queried
    
    Returns:
    true if parent is the parent of node
    
    Throws:
    
    IllegalArgumentException - if node or parent is null or not legal in the graph
  - getHeight
```
int getHeight()
```
    Returns the height of the tree. The height is zero when all nodes have the same level.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Returns:
    the height of the tree
  - getLevel
```
int getLevel(Node node)
```
    Returns the level of node in the hierarchy. Roots have the level zero and it inscreases when going down in the tree.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    
    Returns:
    the level value of node
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
  - moveToGroup
```
void moveToGroup(Node node,
               Node nodeGroup)
```
    Move node and descendants of node to nodeGroup, as node will be a child of nodeGroup. Be aware nodeGroup can't be a descendant of node.
    
    Parameters:
    node - the node to be appened to nodeGroup children
    nodeGroup - the node to receive node as a child
    
    Throws:
    
    IllegalArgumentException - if node or nodeGroup is null or not legal in the graph, or if nodeGroup is a descendant of node
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - removeFromGroup
```
void removeFromGroup(Node node)
```
    Remove node from its parent group and append it to node's parent. In other words node rise one level in the tree and is no more a child of its parent.
    
    Parameters:
    node - the node to be removed from it's group
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph, or if node is already at the top of the tree
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - groupNodes
```
Node groupNodes(Node[] nodes)
```
    Group nodes into a new node group (i.e. cluster). Creates an upper node in the tree and appends nodes to it. Content of nodes can be existing groups. In that case, nodes must only contains roots of groups. Therefore all nodes in nodes must have the same parent. The method returns the newly created group of nodes.
    
    Parameters:
    nodes - the nodes to be grouped in a new group
    
    Returns:
    the newly created group of nodes which contains nodes and descendants of nodes
    
    Throws:
    
    IllegalArgumentException - if nodes is null, or if nodes is empty, or if content nodes are not legal in the graph, or if nodes' parent is not similar between elements
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - ungroupNodes
```
void ungroupNodes(Node nodeGroup)
```
    Ungroup nodes in nodeGroup and destroy nodeGroup. Descendants of nodeGroup are appened to nodeGroup's parent node. This method is the opposite of groupNodes(). If called with the result of groupNodes() the state will be equal to the state before calling groupNodes().
    
    Parameters:
    nodeGroup - the parent node of nodes to be ungrouped
    
    Throws:
    
    IllegalArgumentException - if node is null, empty or not legal in the graph
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - flatten
```
void flatten()
```
    Flatten the hierarchy by keeping only nodes in the view and by transforming meta edges into edges. All nodes not in the view are removed from the graph. New edges are created from meta edges, with same attributes and weight.
  - getHierarchyEdges
```
EdgeIterable getHierarchyEdges()
```
  - wrapToTreeNode
```
ImmutableTreeNode wrapToTreeNode()
```
    Returns the hierarchy tree of all nodes in the form of a TreeNode.
    
    Returns:
    a Java TreeNode wrapper of all nodes in the hierarchy tree
  - expand
```
boolean expand(Node node)
```
    Expands the graph view from node to its children. The children of node are put in the view and node is pulled off. Fails if node is not currently in the view or if node don't have any children.
    Meta edges are automatically updated.
    
    Parameters:
    node - the node to be expanded
    
    Returns:
    true if the expand succeed or false if not
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - retract
```
boolean retract(Node node)
```
    Retracts the graph view from node's children to node. The children of node are pulled off the view and node is added to the view. Fails if node is already in the view of if node don't have any children.
    Meta edges are automatically updated.
    
    Parameters:
    node - the nodes' parent to be retracted
    
    Returns:
    true if the expand succeed or false if not
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - isInView
```
boolean isInView(Node node)
```
    Returns true if node is currently in the graph view.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node to be queried
    
    Returns:
    true if node is in the view, false otherwise
    
    Throws:
    
    IllegalArgumentException - if nodeGroup is null or not legal in the graph
  - resetViewToLeaves
```
void resetViewToLeaves()
```
    Reset the current view to leaves of the clustered graph tree. Therefore the getNodesInView() method returns only these leaves.
    
    Throws:
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - resetViewToTopNodes
```
void resetViewToTopNodes()
```
    Reset the current view to top nodes of the clustered graph tree. Therefore the getNodesInView() method returns only these nodes.
    
    Throws:
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - resetViewToLevel
```
void resetViewToLevel(int level)
```
    Reset the current view to nodes located at the specified level in the clustered graph hierarchy. Therefore the getNodesInView() method returns only these nodes.
    
    Throws:
    
    IllegalArgumentException - if level is not between 0 and the height of the tree
    
    IllegalMonitorStateException - if the current thread is holding a read lock
  - getMetaEdges
```
EdgeIterable getMetaEdges()
```
    Returns meta edges for the whole graph. Meta edges are edges between a group and a leaf or between two groups. They represents proper edges between descendants of groups. Meta edges are always located only on nodes which are in the current view.
    Example: In a clustered graph, let's define group1 and group2, both with two leaves as children. Leaves are named l11, l12, l21 and l22. Then we add an edge between l11 and l22. Then we look at the view of the graph. Let's say the view is set for groups only, that means only groups are visible and leaves are not. At this point we can say a meta edge exist between group1 and group2 and it represents the edge l11-l22.
    Therefore meta edges are useful when a graph is retracted/collapsed into clusters. Relations between clusters can be get with meta edges directly. Note that a meta edge knows which edges it represents and its weight is the sum of content edges' weight.
    
    Returns:
    an edge iterable of all meta edges in the current graph view
  - getEdgesAndMetaEdges
```
EdgeIterable getEdgesAndMetaEdges()
```
    Return a unique EdgeIterable for edges and meta edges. The content is the union of getEdges() and getMetaEdges().
    
    Returns:
    an edge iterable of all edges and meta edges in the current graph view
  - getMetaEdges
```
EdgeIterable getMetaEdges(Node nodeGroup)
```
    Returns meta edges for nodeGroup.
    
    Parameters:
    nodeGroup - the node whose meta edges are queried
    
    Returns:
    an edge iterable of meta edges incident to nodeGroup
    
    Throws:
    
    IllegalArgumentException - if nodeGroup is null or not legal in the graph
  - getEdgesAndMetaEdges
```
EdgeIterable getEdgesAndMetaEdges(Node node)
```
    Returns edges and meta edges incident to node.
    For directed graph, note that self-loops are repeated only once. Undirected graphs repeats edges once by default.
    
    Parameters:
    node - the node whose incident edges and meta edges are to be returned
    
    Returns:
    an edge iterable of edges and meta edges incident to node
    
    Throws:
    
    IllegalArgumentException - if node is null or not legal in the graph.
  - getMetaEdge
```
MetaEdge getMetaEdge(Node node1,
                   Node node2)
```
    Finds and returns a directed or undirected meta edge that connects node1 and node2. Returns null if no such edge is found.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node1 - the first incident node of the queried meta edge
    node2 - thge second incident node of the queried meta edge
    
    Returns:
    a meta edge that connects node1 and node2 or null if no such edge exists
    
    Throws:
    
    IllegalArgumentException - if node1 or node2 are null or not legal nodes in the graph
  - getMetaDegree
```
int getMetaDegree(Node node)
```
    Returns the degree for node's meta edges.
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node whose meta degree is queried
    
    Returns:
    the number of meta edges connected to node
    
    Throws:
    
    IllegalArgumentException - if node is null of not legal in the graph.
  - getTotalDegree
```
int getTotalDegree(Node node)
```
    Returns the sum of the degree and the meta-edge degree. Equavalent to getDegree(Node) + getMetaDegree(Node).
    Warning: This method is not thread safe, be sure to call it in a locked statement.
    
    Parameters:
    node - the node whose total degree is queried
    
    Returns:
    the number of meta edges connected to node
    
    Throws:
    
    IllegalArgumentException - if node is null of not legal in the graph.
  - clearMetaEdges
```
void clearMetaEdges(Node node)
```
    Clears all meta edges for node.
    
    Parameters:
    node - the node whose meta edges will be deleted
    
    Throws:
    
    IllegalArgumentException - if node is null of not legal in the graph.
    
    IllegalMonitorStateException - if the current thread is holding a read lock

Interface HierarchicalGraph

Method Summary

Methods inherited from interface org.gephi.graph.api.Graph

Methods inherited from interface org.gephi.graph.api.Attributable

Method Detail

addNode

removeMetaEdge

getChildrenCount

getDescendantCount

getParent

getChildren

getDescendant

getInnerEdges

getOuterEdges

getTopNodes

getNodesTree

getEdgesTree

getTotalEdgeCount

getNodes

getLevelSize

isDescendant

isAncestor

isFollowing

isPreceding

isParent

getHeight

getLevel

moveToGroup

removeFromGroup

groupNodes

ungroupNodes

flatten

getHierarchyEdges

wrapToTreeNode

expand

retract

isInView

resetViewToLeaves

resetViewToTopNodes

resetViewToLevel

getMetaEdges

getEdgesAndMetaEdges

getMetaEdges

getEdgesAndMetaEdges

getMetaEdge

getMetaDegree

getTotalDegree

clearMetaEdges