about projects people publications resources resources visit us visit us search search

Quick Links

Current Apps (3.x)

Typographic Conventions

Mouse button
Dialog button
Keyboard button
Menu item
Dialog label
UCSF RBVI Cytoscape Plugins

Cytoscape Group Support

Cytoscape internally supports a concept of "grouping", but does not provide any user interfaces to take advantage of that concept. This was done intentionally to allow developers to provide a variety of different viewers to allow for future needs and flexibility to meet current needs without forcing any particular semantics on the group concepts. Developers can write new group viewers and register them as potential mechanisms to visualize groups. The RBVI has written three useful plugins to provide user interfaces to the group mechanism:
GroupTool Plugin
A generic interface to Cytoscape's groups, including the ability to create groups based on node attribute values.
NamedSelection Plugin
A group viewer that provides a list of groups in the Groups tab in the Cytoscape Control Panel. Selecting a group in the Groups tab will select all of the members of that group in the network.
MetaNode Plugin
A group viewer that provides a collapse/expand abstraction to groups, which allows a group to be represented in the network by a single node.
These three plugins together provide a variety of tools to create and manipulate groups. Each of these plugins is discussed in detail below.

Figure 1. The Group Tool.. menu and dialog. In this image, the Group Dialog is showing a list of groups representing the protein subgroups in a protein similarity network showing the Amidohydrolase enzyme superfamily.

GroupTool Plugin

The Group Tool is a simple tool that can be used to display information about groups, create new groups, and delete groups. It is not a group viewer itself, but the tool provides an interface to all of the currently defined groups, the nodes and internal and external edges of those groups and which viewer (if any) is being used to view that group. The Group Tool can be installed from the Cytoscape PluginManager under Other. Once installed, the Group Dialog may be started by selecting Group Tool... from the Cytoscape Plugins menu (see Figure 1). The dialog, shown at the right, has a table with columns for the Group Name, number of Nodes, Network, number of Internal Edges, number of External Edges, and the Viewer that is being used to view the group (if any). The table may be sorted by selecting the column header of any of the columns. One additional function of the table is to change the viewer associated with a group. Each of the cells in the Viewer column is a popup menu with all of the currently registered viewers available. You can use this to change from the namedSelection viewer to the metaNode group viewer for example.

In addition to the function of the table, there are several dialog buttons that provide valuable features:

Create
The Create button will allow the creation of a new group. If there are any nodes selected in the network, they will be included as part of the group (a group with no nodes or edges can be created, although it is of dubious value). Selecting the Create button will popup a small dialog for inputing the name of the group. Clicking OK on this dialog will create the group with the currently selected nodes with the internal (within the group) and external (between nodes in this group and any other nodes) edges and with no viewer. To assign a viewer to the group, go to the Viewer entry in the table and assign one from the current list of registered viewers.
Delete
The Delete button will be available whenever any cell or cells are selected in the table. Pressing this button will cause the group or groups corresponding to the rows containing the selected cells to be deleted. This can be a fast way to delete a large number of groups.

Figure 2. Create Groups By Attributes dialog.

Create By Attributes
The Create By Attributes button brings up the Create Groups By Attributes dialog, which can be used to create groups based on node attributes in the network. To create the groups, select the node attribute to use for the group creation and the viewer. Finally, select the Create Groups button and one group will be created for each distinct value of the selected node attribute and all of the nodes with that attribute value will be assigned as part of the group.
Select
The Select button is used to select the network objects represented by the currently selected cells in the table. For example, in Figure 1, consider the AMP deaminase like group (selecting the image will bring up a larger version of it). Selecting the 101 in the Nodes column and clicking the Select button will select all 101 nodes belonging to that group in the network. Similarly, selecting the 4954 in the Internal Edges column or the 4793 in the External Edges column and clicking Select will select those edges. Selecting the group name itself and clicking Select will select all of the nodes, internal edges, and external edges for that group. Group Dialog selections are cumulative, so selecting the nodes in one group and the nodes in a second group will result in the nodes from both groups being selected in the network.
Clear
Since Group Dialog selections are cumulative the Clear button provides a mechanism to "unselect" or clear the selection of individual items. As with Select, the Clear button is available whenever a cell in the table is selected. If the network objects corresponding to the selected cells are selected in the network, they will be unselected.
Clear All
The Clear All button will clear all of the selections in the network, regardless of how they were selected.
Done
Closes the dialog

Figure 3. A Cytoscape network showing the Groups tab of the Cytoscape Control Panel. In the example, the AMP deaminiase like group is selected and opened up, showing all of the nodes that are members of the group. Selection of the group has also selected all of the member nodes in the network.

Named Selection Plugin

The Named Selection is a simple group viewer that allows users to put a name to a group of nodes and then select those nodes by selecting the group. The plugin can be installed from the Cytoscape Plugin Manager under the Other category. Once the plugin is installed, there will be a new Named Selection Tool menu under the Plugins menu. There will also be a new Groups tab in the Cytoscape Control Panel. There are four sub-menus under the Named Selection Tool menu:
Create new named selection
This menu item will be active when there are nodes selected in the network. Selecting this menu item will bring up a dialog to enter the name of the group and create a group with the selected nodes as its members and namedSelection as its viewer. The created group will appear in the Groups tab.
Remove named selection
If there are currently defined groups that are being managed by the namedSelection viewer, the will appear as submenus under this menu item. Selecting one of these will result in that group being deleted.
Select
If there are currently defined groups that are being managed by the namedSelection viewer, the will appear as submenus under this menu item. Selecting one of these will result in the nodes that are part of that group being selected in the network.
Unselect
If there are currently defined groups that are being managed by the namedSelection viewer, the will appear as submenus under this menu item. Selecting one of these will result in that group being unselected if it is selected.

The other way to use the Named Selection Tool is more direct interface provided by the Groups tab in the Cytoscape Control Panel. This panel (shown in Figure 3) shows a list of all of the currently defined groups that are being managed by the namedSelection viewer or any viewer that registers itself with the the metaNode viewers three buttons:

Clear Selection
This will clear any selected groups and nodes, both in the Groups tab and in the network.
New Group
Creates a new group from the selected nodes in the network. This will bring up a dialog that allows the user to select the name of the group to be selected and the viewer to use, if more than one viewer has been registered.
Delete Group
Deletes any groups that are currently selected in the Groups tab.
Expansion Depth radial buttons
Groups can be hierarchically defined, so a group might have groups as well as nodes as members. The list of groups in the Groups tab can be opened in a tree-like fashion to reveal the membership of each group. Groups within groups can similarly be opened. The radial buttons provide a way to open all groups to a specific depth. In the simplest case, when groups only have nodes as members, there will be two buttons: 1 and 2. Selecting 2 will open up all groups to reveal the member nodes. Selecting 1 will close them up again. If some groups have a group as a member, a new button, 3 will appear that will allow users to open up everything to the maximum depth. Currently, the number of expansion radial buttons is limited to a depth of 8.

Named Selection Plugin CyCommands

namedselection add viewer
Add a new viewer to the Groups tab and direct the Named Selection Plugin to monitor it's state.
Arguments:
  • viewer=viewer name: The name of the viewer to add to the list of viewers monitored by the Named SelectionPlugin.
namedselection deselect
Arguments:
  • group=group name: The name of the group to deselect.
namedselection select
Arguments:
  • group=group name: The name of the group to select.
namedselection update
Update the Groups tab.


Figure 4. In this screenshot the various representations of metanodes are shown. The upper node in the network has been collapsed and uses the nodeCharts plugin to show all of the species represented in the selected node. The left and lower metanodes have been collapsed and the child networks have been displayed as embedded networks. The group in the middle his being shown with the group and both of the member nodes.

Metanode Plugin

metaNodePlugin2 is a Cytoscape plugin that implements a collapse/expand abstraction for hierarchical groups of nodes. When used with the namedSelection plugin, these groups are shown in the Groups tab in the Cytoscape Control Panel. metaNodePlugin2 can aggregate the attributes of the members of a group into a single node that represents the group (the meta node). There are a variety of aggregation mechanisms depending on the attribute type, from concatenation for Strings and Lists to average and sum for Integer and Double attributes. A collapsed meta node can be visualized in three different ways: as a nodeChart, as an embedded network, as a normal node. An expanded meta node can be visualized in two different ways: either hidden or as a node with member edges to each of its children. Meta nodes may also have independent attributes and edges in addition to aggregated attributes and edges that reflect their children. The plugin can be installed from the Cytoscape Plugin Manager under the Other category. Once the plugin is installed, there will be a new MetaNode Operations menu under the Plugins menu. There will also be a new Metanode operations node context menu.

Collapse/expand abstraction

The collapse/expand abstraction allows a single node (the metanode) to replace a group of nodes in the network in the collapsed state and restore the nodes in the expanded state. When a group is collapsed, all of the nodes that are part of that group are hidden and the metanode is shown. All of the edges that connected members of the group to nodes outside of the group are also hidden and new meta-edges are created that connect the external nodes to the metanode. When a metanode is collapsed, it is placed at the center of the member nodes and the positions of the member nodes relative to the metanode are recorded. If the metanode is moved and then restored, the member nodes are restored relative to the new location of the metanode. This allows large groups of nodes to be moved and repositioned. It also means that layout algorithms can operate on metanodes and then the metanodes can be expanded, placing all of the member nodes in the correct relative locations. A collapsed metanode will have two attributes that can be used to control the visual properties of that metanode. The NumChildren node attribute contains the number of members of this metanode. The NumDescendents node attribute contains the number of non-metanode members of this metanode added to the value of the NumDescendents attribute of all metanode members of this metanode.

Figure 5. The Metanode Settings Dialog showing all three subpanels opened.

Metanode Menu

Both MetaNode menus are sensitive to the current context. Initially, if there are no selected nodes and no groups using the metaNode viewer, then only the Metanode Settings... menu is selectable. In the main (Plugins) menu all of the other menu items will be greyed out. In the node context menu only the Expand all metanodes and Collapse all metanodes are shown greyed out and all of the other menu items will not be present if there are no metaNode viewer groups. Note, however, that bringing up a node context menu implicitly selects the node, so the Create new metanode menu is always available.
Metanode Settings...
The Metanode Settings Dialog, shown at the right, controls the appearance of metanodes and the attribute aggregation values. When a metanode is created, the current settings of the dialog are used to set the values for the appearance and attribute aggregation behavior of this metanode. If there is a desire to change the settings for a particular metanode once it has been created, you may either select that metanode, bring up the Metanode Settings Dialog, change the settings as desired, and then click the Apply to selected button; or use the Metanode Settings for node context menu. The settings details are described below.
Metanode Appearance
The Metanode Appearance settings control the appearance of the metanode if it is not hidden on expansion. The default is to show the group in the collapsed state as a normal node. By checking Create a nested network for collapsed metanodes a nested network will be created containing all of the children of the metanode and that nested network will be shown in the collapsed node. Also by default, the group will be shown in the expanded state by hiding the metanode. This can be changed by unchecking the Hide metanodes on expansion checkbox. When this is unchecked and applied to a metanode, the metanode will not be hidden when the group is expanded. By default, the metanode will be shown as a normal node and edges will added between the metanode and the members of its group to represent the parent-child relationship. The opacity of the collapsed metanode can be set by adjusting the Metanode Opacity slider. An opacity of 0.0 is completely transparent and an opacity of 100.0 is opaque.
Enable Attribute Aggregation
Attribute aggregation is a process that collects all the values from member node and edge attributes and combines them into a single attribute with the same name and type. For example, the value of a Score attribute of type Double for a metanode could be the average of all of the values of the Score attributes for it's member nodes. One of the important properties of this feature is that visual mappings that were defined to apply to the member nodes will now apply to the metanode as well.
Attribute Aggregation Defaults
Attribute aggregation currently supports the aggregation of String, Integer, Double, List, and Boolean attributes. At this point, Map and Complex attributes are not supported. Each of these types has options as to how they can be aggregated into the metanode (bold options are the default):
String Attributes
  • None: do not aggregate string attributes
  • Comma-separated Values: concatenate all values into a comma-separated list
  • Tab-separated Values: concatenate all values into a tab-separated list
  • Most Common Value: use the most common string value
Integer Attributes
  • None: do not aggregate integer attributes
  • Average: average of all of the values
  • Sum: the sum of all of the values
  • Minimum value: the mimumum value
  • Maximum value: the maximum value
  • Median value: the median valie
Double Attributes
  • None: do not aggregate double attributes
  • Average: average of all of the values
  • Sum: the sum of all of the values
  • Minimum value: the mimumum value
  • Maximum value: the maximum value
  • Median value: the median valie
  • List Attributes
    • None: do not aggregate list attributes
    • Concatenate: concatenate the lists together
    Boolean Attributes
    • None: do not aggregate boolean attributes
    • Logical AND: the AND of all of the member values
    • Logical OR: the OR of all of the member values
Overrides for Specific Attributes
On occaision, there might be cause to aggregate all attributes of a particular type except for a small set of attributes for which it might make no sense. For example, in the Amidohydrolate protein-protein similarity network shown in Figure 1, one of the node attributes is the protein sequence of the protein represented by the node. It probably doesn't make sense to concatenate these together. This section provides a mechanism to override the default for specific attributes. To set the aggregation type for a specific attribute, select the attribute from the Attributes selection menu. The Attribute Type will show the type of that attribute (this is for information only and can not be changed), and in most cases, the Aggregation Type selection menu will say "(no override)". To override the aggregation for this specific attribute, select the desired aggregation mechanism from the Aggregation Type selection menu, which will only list the aggregation types appropriate for this attribute type. The above procedure can be repeated for as many attributes as necessary. Note that as soon as this value is changed the override is set and any new metanodes will respect that override.
Node Chart Options
If the nodeChartPlugin is loaded, the metanode plugin will optionally add node charts to the metanode when it is collapsed (see Figure 4). This is independent of attribute aggregation. The nodeCharts option will gather the data from the attribute of each of the child nodes.
Attribute to use for node chart
The attribute to use to gather the data for the node chart.
Chart type
The type of node chart to paint on the node.
Save Settings
Save all of the current settings as Cytoscape properties. If the session is saved after this, these settings will be saved with the session.
Clear Settings
Clear all of the dialog settings.
Make default
This button is only available when the user has brought up the dialog though a node context menu. In this case, the current settings will replace the default settings for all new metanodes.
Apply to selected
This button is only available when the user has brought up the dialog through the top-level (Plugins) menu. It will cause the plugin to apply the settings to the currently selected metanode(s).
Apply to all
This button is only available when the user has brought up the dialog through the top-level (Plugins) menu. It will cause the plugin to apply the current settings to all of the currently defined metanodes.
Cancel
Cancel any settings changed after the dialog was intialized and dismiss the dialog.
Done
Apply the current settings and dismiss the dialog (only present in the top-level dialog).
Apply
Apply the current settings to the node and dismiss the dialog (only present in the context dialog).
Create new metanode
The Create new metanode menu is active whenever one or more nodes are selected in the network or in the node context menu. When this menu item is selected, a dialog comes up asking for the name of the group which is created with all of the currently selected nodes as its initial members and the metaNode viewer as a viewer. This also causes the group to collapse.
Expand metanode
This menu item differs slightly depending on whether it is called from the node context menu or the Plugins menu. In the case of the node context menu, the menu item will only be shown if the context node is a metanode and it will be shown with the name of the metanode. For example, if the context menu for the collapsed metanode metaTest is poped up, one of the menu items will be Expand metanode metaTest. In the case of the main (Plugins→MetaNode Operations) menu, the list of all currently defined metanodes will be listed as submenus under the Expand metanode menu. Given he example above, if metaTest were the only metanode, it would be added as a submenu: Plugins→MetaNode Operations→Expand metanet→metaTest. The results of selecting either of these menus is the same, however: the metanode is expanded.
Collapse metanode
This menu item behaves in exactly the same manner as the one above except that the result is to collapse the metanode, hiding all of the member nodes and showing only the metanode.
Expand metanode(s) into new network
This menu item will only be shown in the node context menu if the context node is a metanode. This menu will create a new network that contains only the members of the chosen or context metanode. The relative locations of the members are preserved.
Remove metanode
This menu item is only available from the main menu. As with other main menu elements, the list of available metanodes will be added to this menu item as sub-menus. Selecting one of these will result in the deletion of the designated group. If the group is collapsed, it is expanded before removal.
Add node(s) to metanode
This is available from both menus, although the behavior is slightly different between the two contexts. In both cases, the list of available metanodes are added as submenus. In the case of a node context only the context node will be added. In the case of the main menu all selected nodes will be added.
Remove node(s) from metanode
This is available from both menus, although the behavior is slightly different between the two contexts. In the case of a node context only the context node will be removed, and the only metanodes shown as submenus are those that this node is a member of. In the case of the main menu all metanodes are shown and all selected nodes will be removed from the indicated metanode (assuming they are members).
Expand all metanodes
This menu item will iteratively go through and expand all unexpanded metanodes in the network. This can be somewhat time-consuming if the number of metanodes is large.
Collapse all metanodes
This menu item will iteratively go through and collapse all expanded metanodes in the network. This can be somewhat time-consuming if the number of metanodes is large.

Metanode Plugin CyCommands

metanode add node
Add a node to an existing metanode.
Arguments:
  • metanode=metanode: The name of the metanode to add the node to.
  • node=nodeName: The name of the node to add.
  • nodelist=nodelist: A list of nodes to add to the metanode
metanode collapse
Collapse a metanode.
Arguments:
  • metanode=metanode: The name of the metanode to collapse.
  • networkview=[current]: The network view this applies to.
metanode collapse all
Collapse all metanodes.
Arguments:
  • networkview=[current]: The network view this applies to.
metanode create
Create a new metanode.
Arguments:
  • metanode=metanode: The name of the metanode to create.
  • network=[current]: The network this metanode is in.
  • nodelist=[selected]: The list of nodes to add to this metanode.
metanode delete
Delete a new metanode.
Arguments:
  • metanode=metanode: The name of the metanode to delete.
metanode expand
Expand a metanode.
Arguments:
  • metanode=metanode: The name of the metanode to expand.
  • networkview=[current]: The network view this applies to.
metanode expand all
Expand all metanodes.
Arguments:
  • networkview=[current]: The network view this applies to.
metanode list edges
List the edges that are part of this metanode.
Arguments:
  • metanode=metanode: The name of the metanode to list.
metanode list metanodes
List all metanodes in a given (or all) network.
Arguments:
  • network=[all]: The network to restrict the list to.
metanode list nodes
List the nodes that are part of this metanode.
Arguments:
  • metanode=metanode: The name of the metanode to list.
metanode modify aggregation
Modify the aggregation behavior of a metanode.
Arguments:
  • metanode=metanode: The name of the metanode this applies to.
  • enabled=[true]: Whether to enable attribute aggregation or not.
  • boolean=[or]: How to aggregate boolean attributes.
  • double=[sum]: How to aggregate double attributes.
  • integer=[sum]: How to aggregate integer attributes.
  • list=[none]: How to aggregate list attributes.
  • string=[csv]: How to aggregate string attributes.
metanode modify appearance
Modify the appearance of a metanode (may need to recollapse the metanode to take effect).
Arguments:
  • metanode=metanode: The name of the metanode this applies to.
  • opacity=[100]: The opacity of the metanode.
  • usenestednetworks=[false]: Whether to use nested networks with collapsed metanodes.
  • chartattribute=[none]: The attribute to use for node charts (if loaded).
  • nodechart=[none]: The chart type to use for node charts (if loaded).
metanode modify overrides
Modify aggregation overrides for specific attributes in a metanode.
Arguments:
  • metanode=metanode: The name of the metanode this applies to.
  • attribute=attribute: The attribute to override the aggregation type.
  • aggregation=aggregation type: The aggregation type to use for this attribute.
metanode remove node
Remove a node or group of nodes from a metanode.
Arguments:
  • metanode=metanode: The name of the metanode this applies to.
  • node=nodeName: The name of the node to remove.
  • nodelist=nodelist: A list of nodes to remove from the metanode
metanode set default aggregation
Modify the default aggregation of new metanodes.
Arguments:
  • enabled=[true]: Whether to enable attribute aggregation or not.
  • boolean=[or]: How to aggregate boolean attributes.
  • double=[sum]: How to aggregate double attributes.
  • integer=[sum]: How to aggregate integer attributes.
  • list=[none]: How to aggregate list attributes.
  • string=[csv]: How to aggregate string attributes.
metanode set default appearance
Modify the default appearance of new metanodes.
Arguments:
  • opacity=[100]: The opacity of the metanode.
  • usenestednetworks=[false]: Whether to use nested networks with collapsed metanodes.
  • chartattribute=[none]: The attribute to use for node charts (if loaded).
  • nodechart=[none]: The chart type to use for node charts (if loaded).
metanode set default overrides
Modify default aggregation overrides new metanodes.
Arguments:
  • attribute=attribute: The attribute to override the aggregation type.
  • aggregation=aggregation type: The aggregation type to use for this attribute.

Programmer's Notes

A number of questions have come up about how to use groups in general and metanodes in particular from another plugin. All of the necessary methods are available as part of the cytoscape.groups.CyGroup, and cytoscape.groups,CyGroupManager interfaces. Create the group with the string metaNode as the viewer:
import cytoscape.groups.CyGroupManager;
import cytoscape.groups.CyGroup;

	String name = "test";
	List<String>nodes = new ArrayList();
	CyGroup group = CyGroupManager.createGroup(name, nodes, "metaNode");
To collapse a group, change the group's state:
	group.setState(2); // collapse the group
and to expand the group:
	group.setState(1); // expand the group
Note that there is no need to attempt to interface directly with the metaNodePlugin2 classes, but make sure not to create the group as part of plugin initialization as the metaNodePlugin2 plugin might not be loaded yet and it will fail to initialize the group properly.


Laboratory Overview | Research | Outreach & Training | Available Resources | Visitors Center | Search