Diff for "API"

Please review the Java-Docs at http://db.systemsbiology.net/cytoscape/grouping/doc/ and comment.

To give you a better idea of how the interfaces work together, here is an example:

// Example 1. Algorithm calculated groups:

CyNetwork [] groups = someAlgorithm.calculateGroups(someArgs);
groupManager.addGroupsToNetwork(myNetwork);
GroupingStrategy collapsingStrategy = 
     GroupingStrategyFactory.createGroupingStrategy(GroupingStrategyFactory.COLLAPSING_STRATEGY);
GroupingStrategy stackingStrategy =
     GroupingStrategyFactory.createGroupingStrategy(GroupingStrategyFactory.STACKING_STRATEGY);
for(int i = 0; i < groups.length; i++){

   // Layout the nodes in a column
   stackingStrategy.group(myNetwork,groups[i]);

   if(groups[i].nodeCount() > SOME_LIMIT)
        // collapse groups that are too large
        collapsingStrategy.group(myNetwork,groups[i]); 

}

Notes:

1. I decided to name the interfaces in this API using the group word instead of the MetaNode word. A MetaNode is a way of grouping nodes/edges in a graph. The more general concept is grouping.

2. The GroupingManager is an interface to the data structure that stores groups for Cytoscape networks. We have not decided what data structure will do this. Alternatives that have been mentioned in the past are:

   • CyAttributes

   • CyNodes (as it is done currently)

   • A new data structure

Here is my opinion on each:

• CyAttributes Requires that a node (if we use node CyAttributes) or an edge (if we use edge CyAttributes) be created per group. Only in one case (COLLAPSING_STRATEGY) is a node per group needed. The other grouping strategies do not need new nodes or edges. Additionally, there is no safe way of storing information that tells us to which network a group belongs, since the node that functions as a key in CyAttributes can be manipulated very easily by users (removing it, adding it to a new network, etc).

• CyNode Also requires a node per group. This was originally done because when we were designing the GINY API, we were not thinking of the more general grouping problem. We were thinking of MetaNodes only.

• A new data structure. This could be a data-structure that resembles CyAttributes (some sort of map structure) but that does not require the creation of a node per group. Also, this data structure would be hidden, so that the only way of interacting with it is GroupingManager. I vote for this.

Comments:

• AllanK: Does the GroupingStrategy, as it is currently defined, conflate the model and the view? Should model-oriented strategies be orthogonal to view-oriented strategy? It seems to me that COLLAPSING_STRATEGY should be applicable to STACKING_STRATEGY and the other view-oriented strategies. That is, wouldn't one want to be able to collapse and expand a stacked group in the same manner in which you'd want to collapse and expand a non-stacked group?

• Iliana: Yes, you should be able to collapse a stack. See the sample code above.

• AllanK: This is related to the issue above. Should groups be inherently hierarchical? Would that simplify the object model? Are there any situations where you would not want to be able to nest groups? I can certainly see that in the STACKING_STRATEGY people will likely want the ability to hierarchically compose these stacks and have the ability to alternative vertical and horizontal partitioning.

• Iliana: Nested grouping could be done like this:

// Example 2. Creating nested groups

CyNetwork subgroup = methodThatGetsASubgroup();
CyNetwork [] groups = groupManager.getGroupsInNetwork(myNet);
Map args = new Hashtable();

for(int i = 0; i < groups.length; i++){
  
   if(groups[i].getIdentifier().equals(SOME_NET_ID)){
    
    groupManager.addGroupToNetwork(groups[i], subgroup); // nest a group
    
    // recursive collapse:
    args.put(CollapsingStrategy.IS_RECURSIVE, Boolean.TRUE);
    collapsingStrategy.group(myNet,groups[i],args); // collapses the nested group
    
    // OR, stack subsubgroup, collapse subgroup:
    args.put(CollapsingStrategy.IS_RECURSIVE, Boolean.FALSE);
    stackingStrategy.group(groups[i],subgroup); // stack nested group
    collapsingStrategy.group(myNet,groups[i],); // collapse top level group
  }

}

// This is code in a GroupingStrategy:
public boolean group (CyNetwork network, CyNetwork subnetwork, Map args){
 
 if(args.containsKey(IS_RECURSIVE) && args.get(IS_RECURSIVE).equals(Boolean.TRUE)){
  // recursive grouping, use GroupManager.getGroupsInNetwork to get groups within groups...
  CyNetwork [] subsubgroups = groupManager.getGroupsInNetwork(subnetwork);
  // .. do stuff
 }else{
  // non-recursive, do stuff...
 }

}

• AllanK: I wonder if the spelling of the method getGroupedInNetworks() may be a little awkward? Should we use an alternative spelling such as getContainingNetworks()?

• Iliana: I changed it to getContainingNetworks(). Thanks.

BR

• AlexP: The thorough documentation makes this all much more transparent. Thanks, Iliana. I like the more generic "grouping" terminology. It fits well with the limited goals of metanodes in 2.3. Concerning the GroupingManager and the issue of data structure, I am not expert enough to have a full vote, but your reasoning seems sound (e.g., hidden is safer).