## page was renamed from RFC Template ## This template should be used for creating new RFC's (Request for comments) for Cytoscape development || '''RFC''' : Nested Networks || '''Editor(s)''': Mike Smoot|| '''Date''': Jan 25, 2010 ||'''Status''': pending review || == Proposal == Add two methods to the !CyNode object allowing nodes to hold a reference to another network. === Background === The Network Panel provides a simple hierarchical list of networks created in Cytoscape. A hierarchy, however, is not sufficient to capture all of the relationships found between networks. Generalizing a hierarchy, it becomes clear that the relationships between networks form networks themselves. The nested network capability allows networks to be represented in Cytoscape as nodes and therefore included in networks themselves. This structure allows us to capture any relationship between networks that can be described by a network. This approach is closely related to the concept of a [[http://lmgtfy.com/?q=hypernode|hypernode]]. == Use Cases == * Several module (subnetwork) search algorithms return modules that are themselves related (e.g. [[http://chianti.ucsd.edu/idekerlab/pages/pdfs/bandyopadhyayPLoS2008.pdf|Bandyopadhyay 2008]]). With the nested network structure it is possible to create an overview network that displays the modules found and the relationships between the modules in a simple visualization. == Implementation Plan == * Add a setNestedNetwork and getNestedNetwork method to the giny.model.Node interface and provide implementations throughout our stack. * Add a showNestedNetwork and setNestedNetworkVisible method to giny.view.!NodeView and provide a nested network visualization that can be controlled using the !VizMapper. * Add node context menu options that allow users to set, jump to, and delete nested networks. {{attachment:context1.png}} * Add an icon to the Editor allowing users set nested networks via drag-n-drop. * Define a nested network file format (NNF) and provide a Reader for the format. === Sample Visualizations === {{attachment:10NestedNetworks.png}} {{attachment:10NestedNetworks2.png}} {{attachment:overview1.png}} == Project Management == === Project Timeline === Finished December 16, 2009. === Project Dependencies === * While this RFC will touch many parts of the core code, it will not create any dependencies. No external (plugin or otherwise) code should be impacted by these changes. == Issues == == Comments == Gary - Jan.28: * Looks very cool! How is I/O handled? Is NNF just for users to define these for import and then subsequent I/O uses XGMML in the session file? * (MikeSmoot) This is exactly right. * Might any addition to XGMML break compatibility with other software that reads XGMML (e.g. cytoscape web)? * (MikeSmoot) Actually, no changes to XGMML were necessary. The nesting information is stored in attributes (which XGMML already handles) and then the session handler creates the nestings once all networks have been loaded based on those attributes. AllanK - Jan. 30: * Are nested networks copied or shared? If network A contains nodes A1 and A2 and is contained in networks N1 and N2, then what happens if an attribute value is assigned to N1.A.A1, then is that assignment made to N2.A.A1, as well? If shared, then what about attributes like X, Y, positions? * (MikeSmoot) Nested networks are just normal CyNetworks and nodes just have references to these networks. There is no copying and any sharing is simply a matter of two nodes having a reference to the same network. The node holding the reference to the network has no control or impact on that network. * Is it possible for the user to 'promote' a nested network to a higher level in the hierarchy? If so, then would all nested networks of the same identifier be promoted? * (MikeSmoot) Any hierarchy created is something the user creates and can therefore be rearranged as desired. There is no concept of "promotion" since nested networks are just CyNetworks. The only thing that makes a CyNetwork a nested network is that a node has a reference to it. * I like the conceptual simplicity of hypernodes. What are the contrasts with the Network/Subnetwork model of Cytoscape 3.0? With CyGroups? * (MikeSmoot) The nested network framework, which really just means adding setNestedNetwork/getNestedNetwork methods to CyNode could exist alongside the Network/SubNetwork framework in 3.0. So, from one perspective the features are independent. On the other hand if we have nested networks, do we need the SubNetwork framework? SubNetworks are very useful for some things (undo comes to mind), but maybe that should be a hidden implementation detail? The best approach still requires some thought and discussion. * (MikeSmoot) The nested network framework also exists independently of CyGroups. CyGroups did not meet our needs because groups are not networks themselves (i.e. no edges) and all of our module finding algorithms find subnetworks. I don't see any reason why nested networks and groups can't exist side-by-side. * In the editor changes, should the event handler been subclassed, rather than edited in place? * (MikeSmoot) Umm, yes? We weren't familiar with the editor code so if you have advice on how to improve things we're more than willing to make the changes. * In Example 1 for NNF format, is it necessary to list C as a node in Example 1 network, or is it sufficient to just list B->C? If not sufficient to just list the interaction, then why isn't B listed as a node in Example 1 network? Likewise in Example 5, why is (M4 D) necessary? * (MikeSmoot) Correct, in Example 1, the line "Example_1 C" is unnecessary. An edge induces its nodes. However the line isn't actually wrong, just redundant. The same holds for the "M4 D" line in Example 5. We'll update the examples to clarify. * in Example 4, where is 'root' in the diagram * (MikeSmoot) root is not represented in this diagram. We'll fix the example to either include a root network or omit the line. !SamadLotia - 4 Feb: * Code level remarks: * I really like the simplicity of the implementation, specifically relying on attributes to store a network as a subnetwork. It might be worthy to consider removing the nestedNetwork member of !CyNode, and changing getNestedNetwork() to looking up the nested network by exclusively looking at the attribute value. This would eliminate the situation where the attribute value is changed, but getNestedNetwork() would not reflect it. * (MikeSmoot) We thought about this, but then the nested network structure would have been bound to the !CyAttributes data type. As things stand now the entire network and nesting structure is contained within the !CyNetwork/!CyNode combination. * It might be prudent to have a more thorough checking of cyclic network dependencies, as a cyclic dependency would probably result in a stack overflow exception. For example, let A.X be the node X in network A, and let A.X -> B to mean B is a nested network for A.X. If A.X -> B, and B.Y -> A, a cyclic dependency would arise. I'm not sure to what degree nested networks will be used, but this could be important if people are using this to create a pretty complicated hierarchy of nested networks. If a more thorough cyclic dependency check is implemented, it would perhaps be best to have setNestedNetwork() throw an exception that specifies the path of the cyclic dependency. I don't think this point is legitimate if people don't intend to create crazy hierarchies. * (MikeSmoot) We actually allow the situation you describe. We do have checks in place so that rendering doesn't recurse infinitely, but we've deliberately decided not to impose too many restrictions on how nestings can be structured. At this point I believe the only restriction we have is that a node can't contain a reference to the network is in, but given the !RootGraph, it's easy to work around even that restriction. So far, we haven't noticed any big problems. If you can come up with a degenerate scenario that breaks things, then try and write an NNF file that we can use in a unit test. * (!JohannesRuscheinski) As of 2/4/2010 self-referential nested networks are allowed. The rendering problem has been fixed by displaying a special icon for nodes with nested networks that reside in the network they are referencing. * Cytoscape 3: I think having the [set|get]!NestedNetwork() methods for !CyNode is perfectly sufficient. I was considering for a while some kind of !CyNetworkFactory that takes a !CyNode as a parameter and returns a !CyNetwork that is a nested network, but this would just be "API sugar" and is not terribly necessary. * UI level remarks: * Instead of creating an extra button in the Editor for nested networks, why not have the ability to drag a network from the Network panel right onto a node itself? This might be beneficial because: * It reduces the need of going through a dialog to choose a nested network. This reduces the number of clicks a user has to go through to set up a nested network. * The user can have a better sense of what network is going to become a nested network if he or she is still in the Network control panel. * (MikeSmoot) This was our first thought as well, however to get this working we would have to break the Network Panel. The problem is that when you click on a network in the Network Panel it gives that network focus in the Network View Panel. This means you can't drop the network on a different view since that view will never have focus. * It could be useful to add an attribute to nodes with a nested network, like "hasNestedNetwork" that is a boolean. This is useful for setting up the !VizMapper where the node label can be designed to be placed above the node if the node has a nested network. * (MikeSmoot) This attribute already exists and it's called has_nested_network. * If a network cannot be a nested network, the UI should explain thoroughly ''why'' it cannot be a nested network. This would help the user in troubleshooting. * (!JohannesRuscheinski) ''Every'' network can be a nested network!