CyGroupis an extention of Cytoscape's model that provides the following additional capabilities:
- Adds explicit hierarchies to the model. Cytoscape's base model
org.cytoscape.model) provides for a single-level hierarchy: a
CyRootNetworkcan contain a set of
CySubNetworks. The base model also provides for the capability where a
CyNodecan contain a pointer to a
CyGroupuses the network pointer to point to a
CySubNetworkwithin the same
CyRootNetworkas the node. This is important for the next two additional capabilities.
- Adds the ability for a group of nodes and edges to be "collapsed" into
a single, representative
CyNode. This representative
CyNodehas as its network pointer a
CySubNetworkthat contains the collapsed nodes and edges.
- Adds the capability to track and restore
CyEdges that link between a
CyNodethat exists within a group and a
CyNodethat is outside of the group or within another group.
Adds the capability to create "meta"-edges that can be used to represent collapsed
- Adds the ability to aggregate columns from all of the nodes within a group onto the
corresponding column of the group node (see
CyGroupis 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
CyGroupManagerservice is provided that tracks which groups apply in which networks and which
CyNodes actually represent
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
For a "simple app" this is available as part of the
CyGroupFactory groupFactory = adapter.getCyGroupFactory();
CyGroupFactoryis available as a service:
CyGroupFactory groupFactory = getService(bc, CyGroupFactory.class);
CyGroupis created either as an empty group ( (
CyGroupFactory.createGroup(CyNetwork network, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, true);
CyGroupFactory.createGroup(CyNetwork network, CyNode node, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, node, true);
CyGroupFactory.createGroup(CyNetwork network, List nodes, List edges, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, nodes, edges, true);
CyGroupFactory.createGroup(CyNetwork network, CyNode node, List nodes, List edges, boolean register)):
CyGroup emptyGroup = groupFactory.createGroup(network, node, nodes, edges, true);
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
methods are available to determine the
CyGroup that corresponds to
CyNode in a particular
CyGroupManager.getGroup(org.cytoscape.model.CyNode, org.cytoscape.model.CyNetwork)), get all of the groups in a given
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
CyGroup also provides some important methods. In particular,
methods to add or remove nodes or edges to the group (
methods to inquire as to group state (
CyGroup.isInNetwork(org.cytoscape.model.CyNetwork)), and methods to change the state of the group
Collapse and ExpandCytoscape 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:
- The base model is changed to add the collapsed group as a
CyNode(the group node) and remove all of the member
- 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.
CyEdges that connect the group
CyNodeitself to other nodes are added to the network.
CyTabledata for the collapsed group is updated to include both the number of children and the number of descendents
CyTabledata for the collapsed group node is (optionally) updated to reflect an aggregation of all of the data in the member nodes.
Group events are provided to inform App implementers of changes in the membership of groups
GroupNodesRemovedListener), when groups are created and destroyed (
GroupAddedListener), and perhaps most usefully when the state of the group changes (
GroupCollapsedListener). The latter two listeners would be used by Apps that are providing their own view-level visualization for groups.
Column Aggregation (
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
Aggregatorinterface. The next step would be to add that interface to the
CyGroupAggregationManageris 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.
Interface Summary Interface Description CyGroupAn object that represents a group of nodes and edges. CyGroupFactoryAn interface describing a factory used for creating
CyGroupManagerThe CyGroupManager maintains information about all of the groups an instance of Cytoscape. CyGroupSettingsManagerThe CyGroupSettingsManager is responsible for providing an interface to all of the possible settings controlling
CyGroups, including the default settings and group specific settings.
Enum Summary Enum Description CyGroupSettingsManager.DoubleClickActionThe
DoubleClickAcitonenum provides the options for what to do when the user double-clicks on either a group node or a node that's a member of a group.
CyGroupSettingsManager.GroupViewTypeenum provides the options for how to visualize a group.