Diff for "EditingBiochemicalReactions"

A Cytoscape Edge typically connects two Nodes, which we commonly refer to as Source and Target Nodes. While this is sufficient for most cases, there are cases, such as for biochemical reactions, where you may want to have Edges that connect more than two Nodes. The HyperEdgeEditor plugin for Cytoscape enables you to do this.

The figure below shows an example of a biochemical reaction, where an Edge represents a reaction that may have multiple substrates, products, and mediators.

attachment:biochemcial_reaction_eg.png

Here L-glutamine and 2-oxoglutarate are substrates for the reaction, the catalyst glutamate substrate is a mediator for the reaction, 2 L-glutamate is a product of the reaction, the co-factor NADPH is a substrate for the reaction, and the co-factor NADP is a product of the reaction.

There may also be cases in which you may want to connect one edge with another edge, for example to represent the activity of a molecular species that modulates the action of a catalyst. This is illustrated in the figure below

attachment:edge_connect_edge.png

where molecular species S_643 inhibits the action of catalyst M_643.

If you look closely at these two figures, you will see some small squares at the intersections of the edges. In Cytoscape, we refer to this small square as a ConnectorNode. We also refer to the collection of edges and ConnectorNode as a HyperEdge.

To edit biochemical reactions in this manner, you need to first install the HyperEdgeEditor plugin for Cytoscape. Then, using Cytoscape's Editor and the BioChemicalReaction visual style, you can build and modify reactions by dragging and dropping shapes from the editor palette onto the main network view window. You can add products, substrates, and mediators, to a reaction.

The figure below shows the Editor palette for the BioChemicalReaction visual style and the result of dragging/dropping the AddReaction shape from the palette onto the canvas.

attachment:hyperEdgeEditor.png

The AddReaction palette shape serves as a template that enables you to add a connected set of nodes and edges to a network. You can change the names of the substrates, products, and mediators by editing them in Cytoscape's Attribute Browser.

You can connect additional products, substrates, and products to a reaction by dragging their associated shapes from the palette and dropping them on the reaction's ConnectorNode. An example of a reaction with two products is shown in the figure below.

attachment:hyperedge_two_products.png

An example of a reaction with two products and two substrates is shown in the figure below.

attachment:hyperedge_two_products_two_substrates.png

You can connect a conventional Cytoscape node to a reaction by creating an edge from the conventional Cytoscape node to a ConnectorNode (via drag/dropping an edge from the editor palette onto the node). Conversely, you can connect a reaction to a conventional Cytoscape node by creating an edge from the ConnectorNode to the conventional Cytoscape node (via drag/dropping an edge from the editor palette onto the ConnectorNode).

HyperEdges can also be created by first dropping an edge palette item onto a Node (source) and then dropping again (with the rubberband edge) on another Edge (target). If the source node is a regular node and the target is a regular edge--the target edge is removed and a HyperEdge is created that connects source node, target edge's source and target edge's target. This was shown in the example on catalyst action at the top of this section (shown again below).

attachment:edge_connect_edge.png

If the source node is a ConnectorNode or the target edge is a HyperEdge edge, then a HyperEdge-HyperEdge connection will be created (need example).

The popup menu presented when right-clicking on a ConnectorNode will bring up an additional HyperEdgeEditor submenu that allows selection and deletion of HyperEdges. Since HyperEdges can must have a minimum of 2 edges, deleting a HyperEdge may lead to a cascade of deletions if the deleted HyperEdge has shared edges with other HyperEdges.

Deletion of Nodes and Edges using Select-->Delete Selected Nodes and Edges will update the corresponding HyperEdges.

HyperEdges can be saved and exported along with any Cytoscape Network, with attributes as XGMML. This assumes the HyperEdge plugin is loaded before you open or import your sessions and networks.

The following two figures show examples of BiochemicalReactions that you can build up using Cytoscape's editor. Once the HyperEdgeEditor plugin is loaded, you can perform File->Import->HyperEdge Sample Networks. There are two sample networks--Krebs Cycle and Glycolysis Reaction.

The first figure below illustrates Glycolosis Reaction. Note the use of shared edges and multiple connections to the same Node within a HyperEdge.

attachment:glycolosis.png

The second example below uses a Circle Graph Layout to illustrate the Krebs Cycle.

attachment:krebs_cycle.png

A Closer Look

As was stated earlier, a BiochemicalReaction is composed of a set of substrates, products, and mediators, and a HyperEdge that connects them. Here are some basic definitions, plus some rules and constraints for working with HyperEdges:

A HyperEdge is an Edge that connects two or more Nodes. A HyperEdge consists of a set of Edges and a special Node referred to as a ConnectorNode. The ConnectorNode is a generated Node that serves as one endpoint for all Edges contained by a HyperEdge.

Some definitions for HyperEdges are:

1. HyperEdges are mutable. You can add and remove nodes and edges to and from them.

2. A HyperEdge may have more than one CyNode with the same CyEdge interaction type.

3. A HyperEdge may have more than one CyEdge to the same CyNode.

4. A HyperEdge has exactly one ConnectorNode.

5. A HyperEdge ConnectorNode may be used as a regular CyNode within another HyperEdge.

6. A HyperEdge is associated with one or more CyNetworks.

7. The only shared CyEdges in a HyperEdge are those connecting two ConnectorNodes (HyperEdges) that must exist in the same CyNetwork.

8. If HyperEdge A connects to HyperEdge B via a shared edge, both A and B can only exist in one (and the same) CyNetwork.

9. A regular Cytoscape Edge may directly connect to a HyperEdge ConnectorNode, but it will not be considered part of the HyperEdge.

10. HyperEdges are shared, in that any change to a HyperEdge existing in more than one CyNetwork is reflected in all CyNetworks to which the HyperEdge belongs.

BEGIN comments from Mike Creech '

Allan, here are some suggestions and missing info:

1. You copy some of the JavaDoc comments about HyperEdges in A Closer Look, at the end of this document. You might want to use such definitions as ConnectorNode and shared edges where you have your definition of Connector Node.

2. The second diagram doesn't seem to be a BiochemicalReaction visual style, or the Node's shape has been changed.

3. Once the HyperEdgeEditor plugin is loaded, you can perform File->Import->HyperEdge Sample Networks to play with two sample networks--Krebs Cycle and Glycolysis Reaction. Glycolysis Reaction shows use of shared edges and multiple connections to the same Node within a HyperEdge.

4. The popup menu presented when right-clicking on a ConnectorNode will bring up an additional HyperEdgeEditor submenu that allows selection and deletion of HyperEdges. Selection selects the connector node and all edges. Deletion allows deletion from just the existing Network, or from all Networks, if the HyperEdge is shared. Since HyperEdges can only have a minimum of 2 edges, deleting a HyperEdge may lead to a cascade of deletions if the deleted HyperEdge has shared edges with other HyperEdges.

5. HyperEdges can be create by first dropping an edge palette item onto a Node (source) and then dropping again (with the rubberband edge) on another Edge (target). This leads to a few different cases:

   • If the source node is a regular node and the target is a regular edge--the target edge is removed and a HyperEdge is created that connects source node, target edge's source and target edge's target (obviously need example).

   • If the source node is a ConnectorNode or the target edge is a HyperEdge edge--will end up with a HyperEdge-HyperEdge connection (need example).

   • If the source node is a connector node and the target is a shared edge--displays an error dialog--we can't currently create this with the current HyperEdge API.

7. HyperEdges are persistent thru normal saving and exporting Networks with attributes as XGMML. This assumes the HyperEdge plugin is loaded before you open or import your sessions and networks. Since HyperEdges with shared edges cannot be in more than one Network, reloading a Network containing HyperEdges with shared edges will result in these HyperEdges being copied within the reloaded Network.

8. The Krebs Cycle you display is not the one a user will see when they import the HyperEdge Sample Networks. The node coloring and direction of the arrows will be different. You might want to display the real sample network (layed out with circle layout) instead.

END COMMENTS FROM MIKE CREECH