Package org.cytoscape.group

package org.cytoscape.group
This package provides an API for creating and managing groups in Cytoscape. A CyGroup is an extention of Cytoscape's model that provides the following additional capabilities:
  1. Adds explicit hierarchies to the model. Cytoscape's base model (see org.cytoscape.model) provides for a single-level hierarchy: a CyRootNetwork can contain a set of CySubNetworks. The base model also provides for the capability where a CyNode can contain a pointer to a CyNetwork (see CyNode.getNetworkPointer(). A CyGroup uses the network pointer to point to a CySubNetwork within the same CyRootNetwork as the node. This is important for the next two additional capabilities.
  2. Adds the ability for a group of nodes and edges to be "collapsed" into a single, representative CyNode. This representative CyNode has as its network pointer a CySubNetwork that contains the collapsed nodes and edges.
  3. Adds the capability to track and restore CyEdges that link between a CyNode that exists within a group and a CyNode that is outside of the group or within another group.
    4. Adds the capability to create "meta"-edges that can be used to represent collapsed edges
  4. Adds the ability to aggregate columns from all of the nodes within a group onto the corresponding column of the group node (see org.cytoscape.group.data).
A CyGroup is stored internally as a network and a list of external edges (edges that connect from nodes within the group to nodes outside of the group. Groups may contain nodes which represent groups, which allows for the creation of explicit hierarchies of groups. To create a group, use one of the CyGroupFactory methods. A CyGroupManager service is provided that tracks which groups apply in which networks and which CyNodes actually represent CyGroups.

Creating and Managing Groups

As with other core capabilities, there are two ways to create groups depending on whether the App developers is creating an OSGi bundle or a "Simple App". In either case, the App developer must get a reference to a CyGroupFactory. For a "simple app" this is available as part of the CyAppAdapter:

CyGroupFactory groupFactory = adapter.getCyGroupFactory();
For an OSGi bundle, the CyGroupFactory is available as a service:
CyGroupFactory groupFactory = getService(bc, CyGroupFactory.class);
A CyGroup is created either as an empty group ( (CyGroupFactory.createGroup(CyNetwork network, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, true);
or by turning an existing node into an empty group (CyGroupFactory.createGroup(CyNetwork network, CyNode node, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, node, true);
or by providing lists of nodes and edges to be the initial membership of the group (CyGroupFactory.createGroup(CyNetwork network, List nodes, List edges, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, nodes, edges, true);
or by adding a list of nodes and edges to an existing node to make it a group (CyGroupFactory.createGroup(CyNetwork network, CyNode node, List nodes, List edges, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, node, nodes, edges, true);
In any of these cases, the last argument is a flag to tell the group factory code whether this group should be registered with the CyGroupManager. This should almost always be set to "true". For group factory methods that take a list of nodes and edges, the edge list may be null. In this case, the initial edge list will be the edges that connect all of the provided nodes and the initial external edge list will be the edges that connect the provided nodes to nodes outside of the list. So, the easiest way to create a group is to collect the list of nodes to be members and call:
CyGroup emptyGroup = groupFactory.createGroup(network, nodes, null, true);

Once a group has been created and registered with the CyGroupManager methods are available to determine the CyGroup that corresponds to a given CyNode in a particular CyNetwork (CyGroupManager.getGroup(org.cytoscape.model.CyNode, org.cytoscape.model.CyNetwork)), get all of the groups in a given CyNetwork (CyGroupManager.getGroupSet(org.cytoscape.model.CyNetwork)) and get all of the groups a particular CyNode is a member of (CyGroupManager.getGroupsForNode(CyNode node)). A couple of other useful methods are also provided.

In addition to the CyGroupManager methods, CyGroup also provides some important methods. In particular, methods to add or remove nodes or edges to the group (CyGroup.addNodes(java.util.List<org.cytoscape.model.CyNode>), CyGroup.addEdges(java.util.List<org.cytoscape.model.CyEdge>), CyGroup.removeNodes(java.util.List<org.cytoscape.model.CyNode>), CyGroup.removeEdges(java.util.List<org.cytoscape.model.CyEdge>)), methods to inquire as to group state (CyGroup.isCollapsed(org.cytoscape.model.CyNetwork), CyGroup.isInNetwork(org.cytoscape.model.CyNetwork)), and methods to change the state of the group (CyGroup.collapse(org.cytoscape.model.CyNetwork), CyGroup.expand(org.cytoscape.model.CyNetwork)).

Collapse and Expand

Cytoscape groups are primarily a model-level concept. Some terms like "collapse" and "expand" might suggest a visual representation, and indeed there is a default core implementation bundle that handles view-level changes. However, at this level, its probably best to think of "collapse" and "expand" as creating and destroying hierarchical networks. When a group is "collapsed" it triggers several actions:
  1. The base model is changed to add the collapsed group as a CyNode (the group node) and remove all of the member CyNodes.
  2. Any external CyEdges (edges between group members and nodes outside of the group) are replaced by meta-edges between the group node and the corresponding external node. This process can be somewhat complicated by the fact that the external node of the edge might itself be a collapsed member of a group.
  3. CyEdges that connect the group CyNode itself to other nodes are added to the network.
  4. The CyTable data for the collapsed group is updated to include both the number of children and the number of descendents
  5. The CyTable data for the collapsed group node is (optionally) updated to reflect an aggregation of all of the data in the member nodes.
A group expansion involves the removal of the group node, its edges, and any meta-edges; and the addition to the network of the member nodes and internal edges.

Events (org.cytoscape.group.events)

Group events are provided to inform App implementers of changes in the membership of groups (GroupEdgesAddedListener, GroupNodesAddedListener, GroupEdgesRemovedListener, and GroupNodesRemovedListener), when groups are created and destroyed (GroupAboutToBeDestroyedListener, GroupAddedListener), and perhaps most usefully when the state of the group changes (GroupAboutToCollapseListener, GroupCollapsedListener). The latter two listeners would be used by Apps that are providing their own view-level visualization for groups.

Column Aggregation (org.cytoscape.group.data)

One of the options provided by the group package is the ability to aggregate the columns of member nodes into the corresponding column of the group node. For example, if nodes have an affinity column, it could be useful to have the group node contain the average affinity of all of its members. Since there is clearly no "right" way to aggregate columns of various types, the groups package provides for multiple ways to aggregate each data type. In order to provide a new aggregation, the App writer would first provide a new aggregation class that implements the Aggregator interface. The next step would be to add that interface to the CyGroupAggregationManager. CyGroupAggregationManager is a service that provides all of the aggregators for a given type to the underlying group code. When a group node is collapsed, the aggregator for each column is called to aggregate all of the values of the member nodes onto the column of the group node.