Cytoscape Group Support

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

Named SelectionPlugin ManagerOtherNamed Selection ToolPluginsGroupsControl PanelNamed Selection Tool

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

metaNodePlugin2namedSelectionGroupsControl PanelmetaNodePlugin2Plugin ManagerOtherMetaNode OperationsPluginsMetanode operations

Collapse/expand abstraction

metametaNumChildrenNumDescendentsNumDescendents

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

Metanode Menu

metaNodeMetanode Settings...PluginsExpand all metanodesCollapse all metanodesmetaNodeCreate new metanode

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
Integer Attributes
Double Attributes
List Attributes
Boolean Attributes

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.

RBVI Apps Home

Single Cell RNA-Seq Analysis

scNetViz

Structure Integration

structureViz2

Chem Informatics

chemViz2

Cluster Analysis

clusterMaker2

Network Access

cddApp

stringApp

Animation

CyAnimator

Layouts

boundaryLayout

Utility Apps

Adjacency Matric Reader

CDT (Cluster) Reader

Enhanced Graphics

Layout Saver (Mapper)

Sets App

CyBrowser