org.isb.metanodes
Class MetaNodeUtils

java.lang.Object
  org.isb.metanodes.MetaNodeUtils

public class MetaNodeUtils
extends Object

Class with easy to use static methods for metanode operations.

A metanode is a normal Cytoscape node (CyNode) that represents a network (we call it child-network of the metanode) within another network. After metanodes are created (using create methods in this class), they can be "collapsed" or "expanded". The "collapse" operation consists on replacing the child-network by its parent metanode. The "expand" operation consists on the opposite, that is, replacing the metanode by its child-network. When collapsing a metanode, edges between its children nodes and other nodes are transfered to the metanode. These operations modify the model of a network. Since network views are synchronized to the network model, the existing views of a network will automatically reflect the model modifications made by methods in this class.

Most classes using the MetaNodeViewer plugin programatically will call methods in this class.
Advanced uses of the plugin require more familiarity with the rest of the classes in this package.
Order of calls to use this class go something like this:

 // create the metanode
 CyNode metaNode = MetaNodeUtils.createMetaNode(network,childNetwork);
 // collapse the metanode, creating multiple edges
 MetaNodeUtils.collapseMetaNode(network,metaNode,true);
 // expand the metanode, not recursive
 MetaNodeUtils.expandMetaNode(network, metaNode, false);
 // when I am sure that I will no longer use the metaNode, remove it
 MetaNodeUtils.removeMetaNode(network,metaNode,false);
 

Additionally, meta-nodes can optionally have "meta-relationship edges". These edges can be of two types:

• "Shared child" edges: if two metaNodes share a child node, there will be an edge between them
• "Child of" edges: if a child node has two metaNode parents, and one of them is collapsed, and the other one expanded, the child node will be visible and have an edge to the collapsed parent metaNode

This option can be given as an argument when calling the collapsing method in this class.

Since:

2.3

Author:

Iliana Avila-Campillo iavila@systemsbiology.org, iliana.avila@gmail.com

Field Summary

static AbstractMetaNodeModeler

abstractModeler The object that modifies the network model to collapse and expand metanodes, not recommended to use unless you know what you are doing

Constructor Summary

MetaNodeUtils()

Method Summary

static boolean	collapseMetaNode(CyNetwork network, CyNode meta_node, boolean create_multiple_edges, boolean create_meta_relationship_edges) Collapses the given metanode in the given network
static CyNode	createMetaNode(CyNetwork network, CyNetwork child_network) Creates a metanode that represents the given child-network in the given network
static CyNode	createMetaNode(CyNetwork network, CyNetwork child_network, MetaNodeAttributesHandler attributes_handler) Creates a metanode that represents the given child-network in the given network
static boolean	expandMetaNode(CyNetwork network, CyNode meta_node, boolean recursive) Expands the metanode in the given network
static List	getAllMetaNodeIDs(CyNetwork network) Returns indices of nodes that are metanodes in the given network, whether they are collapsed or expanded
static List	getAllMetaNodes(CyNetwork network) Returns all CyNodes that are metanodes in the given network, whether they are collapsed or expanded
static CyNetwork	getChildNetwork(CyNode meta_node) Returns the child-network of the given metanode, or null if the node is not a metanode
static List	getChildren(CyNode meta_node) Finds the immediate children nodes of the meta-node and returns them
static List	getLeafChildren(CyNode meta_node) Returns the descendant nodes of the given metanode that are not meta-nodes themselves
static List	getParents(CyNetwork network, CyNode child) Finds and returns the immediate parents of the given child node
static List	getRootParents(CyNetwork network, CyNode child) Finds and returns the top level parents of the given child node
static boolean	hasParents(CyNetwork network, CyNode node) Returns true if the given node has parent metanodes in the given network, false otherwise
static boolean	isCollapsed(CyNetwork network, CyNode meta_node) Returns true if the given metanode is collapsed in the given network, false if it is expanded, or if it is not a metanode at all
static boolean	isMetaNode(CyNode meta_node) Returns true if the given node is a metanode, false otherwise
static boolean	removeMetaNode(CyNetwork network, CyNode meta_node, boolean recursive) Expands and then permanently removes the given metanode from the network
static void	setChildNetwork(CyNode node, CyNetwork network, CyNetwork child_network) Sets a network as a child-network for an existing CyNode that after this call becomes a metanode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

abstractModeler

public static final AbstractMetaNodeModeler abstractModeler

The object that modifies the network model to collapse and expand metanodes, not recommended to use unless you know what you are doing

Constructor Detail

MetaNodeUtils

public MetaNodeUtils()

Method Detail

createMetaNode

public static CyNode createMetaNode(CyNetwork network,
                                    CyNetwork child_network,
                                    MetaNodeAttributesHandler attributes_handler)

Creates a metanode that represents the given child-network in the given network

This method does not collapse the created metanode. It only internally stores the given information in data-structures.
Note that all connecting edges between nodes in the child-network that are not in the child-network, but are in the network paremeter, are also considered child edges of the metanode and addded to its child-network automatically. This means you don't have to find connecting edges between the children nodes in network to create the metanode.

Parameters:

network - the CyNetwork in which the metanode will represent the child-network

child_network - the CyNetwork that the metanode will represent

attributes_handler - the object that transfers chhild-network node and edge attributes to the metanode's attributes

Returns:

a CyNode that represents the given child-network, or null if there was an error

createMetaNode

public static CyNode createMetaNode(CyNetwork network,
                                    CyNetwork child_network)

Creates a metanode that represents the given child-network in the given network

This method does not collapse the created metanode. It only internally stores the given information in data-structures.
Note that all connecting edges between nodes in the child-network that are not in the child-network, but are in the network paremeter, are also considered child edges of the metanode and addded to its child-network automatically. This means you don't have to find connecting edges between the children nodes in network to create the metanode.

Parameters:

network - the CyNetwork in which the metanode will represent the child-network

child_network - the CyNetwork that the metanode will represent

attributes_handler - the object that transfers chhild-network node and edge attributes to the metanode's attributes

Returns:

a CyNode that represents the given child-network, or null if there was an error

setChildNetwork

public static void setChildNetwork(CyNode node,
                                   CyNetwork network,
                                   CyNetwork child_network)
                            throws IllegalArgumentException

Sets a network as a child-network for an existing CyNode that after this call becomes a metanode

If the CyNode is already a metanode, it will be first removed from the given network
Note that all connecting edges between nodes in the child-network that are not in the child-network, but are in the network paremeter, are also considered child edges of the metanode and addded to its child-network automatically. This means you don't have to find connecting edges between the children nodes in network to create the metanode.
Important note: child_network should not contain the node given as a parameter.

Parameters:

node - the CyNode for which to set the child-network

network - the CyNetwork in which the metanode will represent the child-network

child_network - the CyNetwork that the metanode will represent

Throws:

IllegalArgumentException - if child_network contains the input node that will become a metanode (a metanode cannot be its own parent)

getChildNetwork

public static CyNetwork getChildNetwork(CyNode meta_node)

Returns the child-network of the given metanode, or null if the node is not a metanode

Parameters:

meta_node - the metaNode for which to return the child-network

Returns:

a CyNetwork that is the child-network of the CyNode, null if the CyNode is not a meta-noded

removeMetaNode

public static boolean removeMetaNode(CyNetwork network,
                                     CyNode meta_node,
                                     boolean recursive)

Expands and then permanently removes the given metanode from the network

Call this method if you are sure that the given metanode will not be collapsed in the future
Note that this method DOES NOT remove the metanode's child-network from the given network.

Parameters:

network - the CyNetwork from which the metanode will be removed

meta_node - the metanode to remove (must have been created through methods in this class)

recursive - if there are > 1 levels of metanode hierarchy within the metanode to remove, whether or not to remove all the levels (if it is known that there is only 1 level, setting this to false significantly improves performance)

Returns:

true if the metanode was successfully removed, false otherwise

expandMetaNode

public static boolean expandMetaNode(CyNetwork network,
                                     CyNode meta_node,
                                     boolean recursive)

Expands the metanode in the given network

If the given network has a network view, then the children nodes are layed out in a stack after the metanode is expanded

Parameters:

network - the CyNetwork in which the metanode is contained and in which it will be expanded

meta_node - the CyNode to expand

recursive - whether metanodes inside the given metanode should be expanded recursively

Returns:

true if the metanode was successfully expanded, false otherwise

collapseMetaNode

public static boolean collapseMetaNode(CyNetwork network,
                                       CyNode meta_node,
                                       boolean create_multiple_edges,
                                       boolean create_meta_relationship_edges)

Collapses the given metanode in the given network

The create_multiple_edges parameter only takes effect the FIRST TIME this method is called for a metanode.
Subsequent collapse operations on the metanode will ignore the value of this parameter, and use the value that was given the first time.

Parameters:

network - the CyNetwork in which the given metanode should be collapsed in

meta_node - the metanode to collapse

create_multiple_edges - if true, then multiple edges between the metanode and another node are created to represent the metanode's child-network connections to that node, if false, only one edge is created to represent these connections

create_meta_relationship_edges - if true, then edges between meta-nodes that share a child ("sharedChild" edges) and edges between meta-nodes and their children ("childOf" edges) are created

Returns:

true if successfully collapsed, false otherwise

getParents

public static List getParents(CyNetwork network,
                              CyNode child)

Finds and returns the immediate parents of the given child node

Parameters:

network - the CyNetwork within which to look for parent metanodes

child - the CyNode to look for

Returns:

an array of CyNode parent nodes

hasParents

public static boolean hasParents(CyNetwork network,
                                 CyNode node)

Returns true if the given node has parent metanodes in the given network, false otherwise

Parameters:

network - the network in which to look for parent nodes

node - the CyNode for which to look for parents

Returns:

true if the node has at least one parent metanode in the network, false otherwise

getRootParents

public static List getRootParents(CyNetwork network,
                                  CyNode child)

Finds and returns the top level parents of the given child node

Parameters:

network - the network in which to look for parent nodes

child - the CyNode for which to look for parents

Returns:

a List of parent CyNodes

getChildren

public static List getChildren(CyNode meta_node)

Finds the immediate children nodes of the meta-node and returns them

Parameters:

metaNode - the CyNode that represents a subnetwork

Returns:

an ArrayList of children CyNodes

getLeafChildren

public static List getLeafChildren(CyNode meta_node)

Returns the descendant nodes of the given metanode that are not meta-nodes themselves

Parameters:

meta_node - the CyNode for which to return bottom level descendant nodes

Returns:

a List of CyNodes

isMetaNode

public static boolean isMetaNode(CyNode meta_node)

Returns true if the given node is a metanode, false otherwise

Parameters:

meta_node - the CyNode to test

Returns:

true if the given node has children nodes, false otherwise

isCollapsed

public static boolean isCollapsed(CyNetwork network,
                                  CyNode meta_node)

Returns true if the given metanode is collapsed in the given network, false if it is expanded, or if it is not a metanode at all

Parameters:

network - the CyNetwork in which the metanode is collapsed

meta_node - the CyNode to test

Returns:

true if the node is a metanodes and is collapsed, false otherwise

getAllMetaNodes

public static List getAllMetaNodes(CyNetwork network)

Returns all CyNodes that are metanodes in the given network, whether they are collapsed or expanded

Parameters:

network - the CyNetwork in which to look for metanodes

Returns:

a List of CyNodes that are metanodes in the given network

getAllMetaNodeIDs

public static List getAllMetaNodeIDs(CyNetwork network)

Returns indices of nodes that are metanodes in the given network, whether they are collapsed or expanded

Parameters:

network - the CyNetwork in which to look for metanodes

Returns:

a List of indices for CyNodes that are metanodes in the given network