Gephi Toolkit Javadoc

org.gephi.graph.api
Interface HierarchicalGraph

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
 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:
java.lang.IllegalArgumentException - if node is null, or if parent is not legal in the graph
java.lang.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:
java.lang.IllegalArgumentException - if edge is null or nodes not legal in the graph
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:

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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException - if node or nodeGroup is null or not legal in the graph, or if nodeGroup is a descendant of node
java.lang.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:
java.lang.IllegalArgumentException - if node is null or not legal in the graph, or if node is already at the top of the tree
java.lang.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:
java.lang.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
java.lang.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:
java.lang.IllegalArgumentException - if node is null, empty or not legal in the graph
java.lang.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:
java.lang.IllegalArgumentException - if node is null or not legal in the graph
java.lang.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:
java.lang.IllegalArgumentException - if node is null or not legal in the graph
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException - if level is not between 0 and the height of the tree
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException - if node is null of not legal in the graph.
java.lang.IllegalMonitorStateException - if the current thread is holding a read lock

Gephi Toolkit Javadoc