RFC Name : Grouping API

Editor(s): ScooterMorris

About this document

This is an official Request for Comment (RFC) for supporting groups in Cytoscape. This RFC encompasses and leverages the MetaNodes RFC (RFC 8) and the SimplifiedMetaNodeDataStructureRFC (RFC 9) by extending the notion of a metanode, to a more general group concept.

For details on RFCs in general, check out the Wikipedia Entry: Request for Comments (RFCs)


Open for public comment

How to Comment

To view/add comments, click on any of 'Comment' links below. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment. Here is an example to get things started: /Comment.

Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the RFC makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.


The goal is to provide a new package, e.g. cytoscape.groups, that suplants all direct calls to the giny metanodes methods, and extends the concept of metanodes in a structured manner. Similar to the MetaNodes implementation, there is a GroupManager class that should be the main interface for most developer. There are also three interfaces to allow a group to have different abstraction models and different visual properties. The three interfaces are:

This package must be in the core to provide direct, consistent access to the grouping API for the XGMML reader/writer, the Cytoscape Editor, and the Metanode Plugin (which will still be provided as one interface to grouping). An Overview of the proposed API is available for comment.

There three significant assumptions that underlie this proposal:

  1. A Group exists in only one CyNetwork. This is really a matter of user expectations. Groups are different than CyNodes and CyEdges in that they have a visual state (grouped or ungrouped). Attempting to maintain different states in different CyNetworks that might have different collections of nodes and edges visible would be difficult. The API explicitly provides a method to perform a shallow copy of a group.

  2. For the subnetwork given to create a group, all Edges and Nodes in this subnetwork are used in creating a Group.

  3. This API will take advantage of events to inform it of the deletion of nodes and edges that it cares about. The groupAPI will also issue events to inform interested listeners of significant changes to the groups. These will be documented as part of the API.

Biological Questions / Use Cases

Each use case should be expanded in a separate page by the person (or group) designated in italics. Please use the Use Case template, which has the following elements:

Due Date: November 15th

1. Clustering - Biomodules Gary

2. Protein Complexes - Pico/GenMAPP (note by Cline/Pasteur) GenMAPP

3. Intragenic Features - Pico/GenMAPP GenMAPP

4. Boxing of groups.

5. Alternate paralogs in pathways. GenMAPP

6. Protein superfamily networks Scooter

7. Named list of genes. Piet & GenMAPP

8. Black-box pathways. Ethan/Ben/Gary

9. States of a protein/generics. For example, grouping together splice variants, PTMs, etc. Ethan/Ben/Gary

10. Groups of graphical elements that are not necessarily nodes or edges. GenMAPP

11. General collapse/expand paradigm for reducing complexity by hiding Piet

12. Topological grouping Piet

13. Quick Find and Group Node Jim

Implementation Plan


MichaelCreech 2006-09-08 08:10:43 Assumptions A few assumptions you might want to explicitly state: 1) A Group exists in only one CyNetwork

2) For the subnetwork given to create a group, all Edges and Nodes in this subnetwork are used in creating a Group.

Issues 1) The current model requires all Cytoscape-based code to explicitly tell GroupUtils when a node and edge is added or deleted (through GroupUtils.deleteEdgeNotify() and deleteNodeNotify()) in order to keep the Group consistent with its underlying Cytoscape structure.

2) Should only CyNode, CyEdge, and CyNetwork be referenced or should their underlying interfaces be referenced, such as Node, Edge, and GraphPerspective? CyNode and CyEdge are also implementation classes, not interfaces.

Suggestions 1) Based on assumption one, add a GroupUtils.getCyNetwork (CyNode group_node).

2) Remove CyNetwork parameter to all operations where it is not needed.

3) Change implementation-specific parameters to more general interfaces.

4) Use only standard java data structures.

5) Clarify mutability of List return values or change to Iterator.

6) Fix inconsistencies in GroupAbstractionModel:

7) Possibly remove duplicate methods that perform the same operation for nodes and edges.

8) Change the name GroupUtils to something less misleading (maybe Group or GroupManager)?

9) Change GroupUtils.getGroupMembers() to return the CyNetwork that is the sub-network representing the Group versus returning a List of Nodes.

10) Allow null network parameter to GroupUtils.getGroupNodes().

11) Add a GroupUtils.getSubGroups (CyNode groupNode)

12) Drop 'Abstraction' from GroupAbstractionModel and GroupAbstractionViewer

13) Add GroupUtils.getGroupModel() and getGroupAttributesHandler()

14) Change setGroupAbstraction() to setGroupAbstractionModel()

15) Add GroupUtils.setGroupAttributesHandler()

MichaelCreech 2006-09-08 08:25:11

16) Need to be able to Add and Delete from a Group

17) Need a way to copy a group

MichaelCreech 2006-09-08 14:56:27 Another suggestion:

18) Change variable references in the API to method references.

MikeSmoot 2006-10-03 16:34:26 Assumptions:

#1 I'm not sure about this. If the nodes in a group exist in more than one network, why wouldn't the group?


#1 I wholly agree. We're going to need decent event handling to support undo as well, so I think this would be time well invested.

#2 Not sure about this one. Some people argue that it's better to use CyNode, CyEdge, etc. because they are specific to cytoscape whereas giny Nodes and Edges are not. If we were to ever move away from giny, the use of Nodes and Edges as opposed to CyNodes and CyEdges would complicate things. That said, I think it's highly unlikely we'd ever do anything other than subsume giny into cytoscape. If others agree, then we should definitely code to the interface.


#1,2 Not sure about assumption 1, so I'm not sure if this is a good idea or not.

#3 Absolutely.

#4 Maybe. It depends on how the structures are being used and what kind of performance is needed. Since all of the core data structures use ints, it might be better to use the non-standard int data structures rather than the standard Integer ones. Even if we change the group api, these int specific data structures are used elsewhere.

#5 Agreed.

#6 Agreed.

#7 Yeah, but see my hesitation on Issue #2. If we agree that we can use giny, then I agree with this change.

#8 Absolutely.

#9 Agreed. I would prefer that we return a CyNetwork rather than a heterogeneous list of Nodes and Edges.

#10 Disagree. In general, I don't like methods that have "hidden" behavior that isn't apparent from the interface. I'd prefer two methods getAllGroups(), and getGroups(CyNetwork).

#11 Ok.

#12 Absolutely.

#13 Ok.

#14 See #12.

#15 Ok.

#16 Ok.

#17 Ok.

#18 Agreed.

MichaelCreech 2006-10-04 06:48:55 Suggestion:

19) Separate user event handling from the GroupAbstractionModel.

AdityaVailaya 2006-10-04 10:49:32 Assumptions #1 It is my understanding that GenMapp group prefers not to have a group automatically created across networks, but have a group be local to a particular network. Further, it was suggested at the mini-retreat (early September in San Francisco) it was suggested that a copy (note no sharing) of a group would be made if it is to be reused in another network. The "copy" allows for different properties to be attached to a group in different networks.

ScooterMorris 2006-10-04 11:44:12 Regarding assumption #1: the issue is one of user expectations. If a user is looking at a network that has been created from another network, and they create a group, would they expect to see the nodes in the other original network group? Our conclusion was that they would not. In addition, since the collection of non-grouped nodes might be different in the two networks, the implementation would be more difficult. That being said, we also talked about the user expectations of creating a new network from a group of nodes in an existing network, when that group of nodes includes a groupNode. In that case, we felt that the right thing would be to make a copy of the group (see Aditya's comment above).

MikeSmoot 2006-11-17 12:12:45 I know we debated this for hours at the retreat, but I don't recall that we ever agreed on Assumption #1.

In discussing this, I also think we need to be careful about distinguishing a group model from a group view.

If the nodes and edges contained in a group are represented by a CyNetwork, then that CyNetwork will be just like any other CyNetwork.

If a group model is represented in a CyNetwork by a CyNode with a pointer to another CyNetwork, then that CyNode is just like any other CyNode. This means there is one representation of that CyNode in the rootgraph and as such, that CyNode can be included in more than one CyNetwork.

That said, we might consider supporting multiple views of networks, something we don't do right now, but is (theoretically) supported by GINY.

Or we might tie a group view to a network view. Even if (normal) nodes are in the same network, their view is different depending on the network view they are in. The same could be accomplished with group views.

Also note that the necessity of copying groups - which seems to motivate this assumption - is not captured in any of the uses cases.

groupAPI (last edited 2009-09-22 02:04:12 by GaryBader)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux