Package org.cytoscape.group
CyGroup
is an
extention of Cytoscape's model that provides the following
additional capabilities:
- Adds explicit hierarchies to the model. Cytoscape's base model
(see
org.cytoscape.model
) provides for a single-level hierarchy: aCyRootNetwork
can contain a set ofCySubNetwork
s. The base model also provides for the capability where aCyNode
can contain a pointer to aCyNetwork
(seeCyNode.getNetworkPointer()
. ACyGroup
uses the network pointer to point to aCySubNetwork
within the sameCyRootNetwork
as 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 representativeCyNode
has as its network pointer aCySubNetwork
that contains the collapsed nodes and edges. - Adds the capability to track and restore
CyEdge
s that link between aCyNode
that exists within a group and aCyNode
that is outside of the group or within another group.
Adds the capability to create "meta"-edges that can be used to represent collapsed
edges
- 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
).
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 CyNode
s
actually represent CyGroup
s.
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();
CyGroupFactory
is available as a service:
CyGroupFactory groupFactory = getService(bc, CyGroupFactory.class);
CyGroup
is 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 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:- The base model is changed to add the collapsed group as a
CyNode
(the group node) and remove all of the memberCyNode
s. - Any external
CyEdge
s (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. CyEdge
s that connect the groupCyNode
itself to other nodes are added to the network.- The
CyTable
data for the collapsed group is updated to include both the number of children and the number of descendents - The
CyTable
data for the collapsed group node is (optionally) updated to reflect an aggregation of all of the data in the member nodes.
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.-
ClassDescriptionAn object that represents a group of nodes and edges.An interface describing a factory used for creating
CyGroup
objects.The CyGroupManager maintains information about all of the groups an instance of Cytoscape.The CyGroupSettingsManager is responsible for providing an interface to all of the possible settings controllingCyGroup
s, including the default settings and group specific settings.TheDoubleClickAciton
enum 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.TheCyGroupSettingsManager.GroupViewType
enum provides the options for how to visualize a group.