groupAPI Implementation Plan

These are some musings resulting from the conversations after the Cytoscape Retreat on group implementations. This plan is two-fold: first, a proposed implementation of groups using CyAttributes; and second, a description of a user interface that has some intriguing properties.

CyAttributes Implementation

Assumptions

1. It is assumed that there is a CyNode created for every group.

2. It is assumed that groups can be hierarchical.

3. It is assumed that there is no support for groups underneath the cytoscape (CyNode, CyEdge, CyNetwork) layer.

4. It is assumed that groups must be able to be saved and restored.

Issues

1. At this point, there are complexities with shared membership of groups -- that is, having a node be a member of two different groups might lead to some complexities in terms of handling of edges. While the lower-level model will support shared membership, the complexities in the view layer (particularly for collapse/expand) might preclude shared membership.
2. Visually identifying a "locked" group (see user model discussion below). When a group is "locked" -- that is, made immutable, it would be useful to designate the group as a whole. Not clear how to do this at this point.

Model

At the model level, CyNodes will have a hidden attribute: "__Parents", which is a list of integers reflecting the node ID's of the parents of this node. At this point, this is most likely to only have a single value. A CyNode that represents a group will have two hidden attributes assigned: "__Members", which is a list of integers reflecting the node ID's of the members of this group; and "__State", which is an integer value that represents the logical setting of the following flags: "LOCKED=1", "COLLAPSED=2". A group with "__State" 0 is not locked and not collapsed.

One addition aspect of the model is that there is a Network attribute: "__Groups" which is a list of integers reflecting the node ID's of the CyNodes that represent groups in this CyNetwork.

The model provides API's to add nodes to groups, remove nodes from groups, setting the state, creating groups, and deleting groups. At the model level, creating a group results in creating a CyNode to represent that group, and setting all appropriate CyAttributes. The CyNode is not added to the network by the model, and no changes are made to the nodes.

User Model

Cytoscape has a particular user model that in some ways runs counter to some of our use cases for groups. This has led to long conversations about how to manage the apparent conflict between the two. Assume that we add a new tab to Cytopanel 1 called "groups". If the user selects a collection of nodes and requests that a "group" be created -- an entry is added to the "groups" Cytopanel called "Group 1". The user can rename this to anything they desire. This results in the group getting created as discussed above, but has no other impact on the network view. In essence, this concept of a "group" is essentially a named selection. When they click on the named group in the Cytopanel, all of the member nodes are selected. A node can be removed from a group or added to a group. This is the simplest concept of a group. This approach could be used to "remember" the results of searches easily. New groups could be created "Search 1", "Search 2", etc. Overlap between groups is actually not a problem in this scenario. Because these groups are really nothing more than named selections, they are completely mutable.

Under many circumstances, users might not want groups to be mutable for a period of time. Thus we can provide users to "lock" groups. A locked group is similar to a "group" in powerpoint. Selection is now at the group level, and you can only select a single node by "unlocking" the group. We need to figure out a mechanism of preventing layout algorithms and other tools from moving the nodes relative to each other, but that should be possible through the existing mechanisms in AbstractLayout. One interesting aspect of this is that attributes and visual properties could still be modified and be seen immediately, and it might be possible to allow certain context menu actions that would not require node selection. We would need to have some way to designate locked groups -- one thought is to put a translucent mask over each node that has been locked.

In the locked case, overlap between groups begins to raise some issues, but they are relatively easy to resolve. If I lock a group that contains a node with multiple parents, this is certainly allowable if none of the other parents of the node are locked. If one of the other parents of the node are locked, the user would be "warned" and asked if they want to create a larger group out of the two groups. This creates a new locked group that contains both of the groups that contain the shared node. Note that the group that the user originally wanted to lock is left unlocked. In this manner, if the user unlocks the combined group, they return to the exact state that existed before combining the groups. I think this is exactly what we want.

Finally, we still want to have the capability of collapsing and expanding a group to allow a "drill-down" capability. This is pretty easy given the above description, but in this case, we have the added challenge of managing edges. The major complexity here is shared membership, and I think that if we follow the trick discussed above of creating a larger, shared group, we completely avoid any of the complexities in the current implementation, and expansion results in a reversal of collapsing.