ELV DiagramTool

From ReactomeWiki
Jump to: navigation, search


The creation of diagrams is closely tied to the process of dividing all of Reactome's content into a set of canonical pathways. The canonical pathways correspond to distinct biological processes with minimal overlap of reactions and proteins, arranged in a hierarchy corresponding to the GO biological process hierarchy. Each entity level view (ELV) layout will display one canonical pathway. A table with the pathways that are being drawn, their status and the curator responsible is housed on the Reactome devwiki site here.


Thus with the new web interface entity level diagrams are needed for each canonical pathway. To facilitate this an entity level view diagram tool has been integrated into the curator tool. The advantage of this approach is that the ELV diagram tool is built directly into the curation tool, facilitating the creation of an ELV pathway diagram as each new module is added. However, it is important to note that using the ELV diagram tool to create diagrams for existing modules it is possible to edit and corrupt the previously made pathway data that is in Reactome. The ELV diagram tool is a curation tool, it is important to be careful to compare your edited diagram with what is in Reactome, and only to save new ELV diagrams into gk_central.

Here we present a basic introduction to the use of the tool, intended to get the curator started. As with all documentation here, this is a developing description of the tool, and any errors that you find or improvements that you can contribute are welcome.


Example 3 - DNA Repair

The ELV Diagram Tool

Figure 4 - Go get a cup of coffee, as this process may take a while. It is important to check out all of the entities and events that are within the diagram that you intend to draw.

The curator is responsible for a Entity Level View (ELV) layout of each new module. This is accomplished with the curator tool, freely available here.

Figure 1 - The "Entity Level View" tab is one of the three data representations that are available along the top edge of the curator tool frame.

The "Entity Level View" tab is one of the three data representations that are available along the top edge of the curator tool frame.

Project Preflight

Before you start there are a couple of considerations. None of these are written in stone and as more of us get involved in generating diagrams it would be good to add comments here.

  • Figure out how many subpathways you want to include based on what will cover 80-100 reactions/entities max.
    • Obviosuly this is a guideline, but by keeping this number down the diagrams stay manageable. If there are too many reactions or entities in a diagram it just becomes to difficult to interpret. The golden rule should be that all diagrams are easy to read and flow in a logical manner.
  • Study the logic of the pathway, get a sense for what order the sub-pathways and reactions occur in. You might even want to go pack to the literature to see if there is a commonly occurring layout.
    • Think about the Krebs cycle here. Many diagrams of the Krebs cycle use the exact same layout, we want to do this if possible.

Creating Pathway Diagrams

For tracking purposes, all pathways being diagrammed by each curator should be entered in the following table:
http://devwiki.reactome.org/index.php/Diagram_Creation_Table When you chose a pathway to diagram, first check this table to make sure that it is not already drawn/being drawn. You can also see all pathways that have diagrams in gk_central using the curator tool. Search on class "Pathwaydiagram" where where attribute "representedpathway" is Not Null. by entering them in Pathway diagrams can be laid out by the curator when the module is first authored or later when the module is complete. Laying out the pathway as one creates the pathway has both an upside and downside, but the concept at least is pretty straight forward. The second method of laying out the diagram post creation requires that you check the entire module out that you will be creating a diagram for. All events and entities must be checked out into the local project for this to work.

Checking Out A Project

Check out Pathway of interest using the event browser. In order to check out all entities and events you will be browsing gk_central through the event view.

Figure 2 - Browse gk_central through the Event View

Finding what you want in the event view hierarchy can be difficult, remember that you can search in this view, so make use of that option if your pathway is not immediately available. once you have it, check it out.

Figure 3 - Select the top level of the module that you will be drawing a diagram for and check out the entire project.

Sit back and let the curator tool do its job.

Figure 4 - Go get a cup of coffee, as this process may take a while. It is important to check out all of the entities and events that are within the diagram that you intend to draw.

A Saving Strategy

Once the project has imported into the local project you are ready to go. One of the intricacies of the ELV Diagram Tool is the lack of an "Undo" feature. You get around this through a judicious use of the "Save" button. Each new step that you will take in generating a diagram should be preceded by saving your work to the local project.

If anything surprising happens as you expand your diagram you can always close the project and reopen your work at the point where all was well.

Opening The Diagram

Having saved your imported data you are ready to begin making the diagram. Begin by switching over to the Entity Level View, Figure 5. You should now see a view similar to Figure 1.

Figure 5 - Switch to the Entity Level View in order to begin.

The ELV Diagram Tool is separated into three distint panes.

  1. The list pane on the upper left is responsive to the items that you select in the primary drawing pane. It will display one of three views:
    1. Event Hierarchy
    2. Complex Hierarchy
    3. Entity List
  2. The Overview pane, which will display a thumbnail representation of the diagram in the primary drawing pane for navigation.
  3. The primary drawing pane dominates the ELV Drawing Tool, and it is here that you will lay out your diagram.

There is a tool bar above the primary drawing pane that contains a number of user buttons for basic tasks. These buttons create/delete/modify entities, events, and compartments. The ELV Diagram tool can be used to curate in a visual way. Sadly most of us have not learned to curate this way, so for now we will only be describing the generation of diagrams.

Using the Event Hierarchy option in the list pane select and right click the top pathway level of the project that you want to diagram. A contextual menu will open, select Open Diagram.

Figure 6 -Select Open Diagram.

There are two ways to create this new diagram, automatically or manually.

Manual Diagram Creation

A message box will open asking if you want to create a diagram automatically; to create it manually, select No.

Figure 7 - Say No to move onto step-by-step manual layout.

Add another figure here for dragging.

Automatic Diagram Creation

A message box will open asking if you want to create a diagram; You do, select Yes.

Figure 7 - Auto-generate you diagram to start.

You should now be able to see your first entities in the primary drawing pane. Before you begin expanding these though, let us look through the creation of compartments. This will open the first level subpathways as “shells” and any individual reactions in that first level.

Creating Compartments

We will be creating a number of items and the primary drawing pane can get cluttered pretty quickly. In order to facilitate the creation of a logical diagram, insert all the compartments that you will need now, before you go any further.

Compartments should be laid out in a nested fashion, see Figure 8.

Figure 8 - Nested compartments.

But before we get to all of these compartments let's make our first one. Start by clicking on the compartment button in the toolbar directly above the primary drawing pane, Figure 9

Figure 9 - Compartment creation button.

A new window will open that will allow you to select compartments from the local project, or alternatively browse gk_central for other compartments.

Our rule for compartments has been the selection of "lumen" compartments. So for the cell, select "cytosol", for the nucleus, select "nucleoplasm", for the endoplasmic reticulum, select "endoplasmic reticulum lumen". Each of these compartments is bordered by a double line. Place entities that are in a membrane compartment on this double line. So a protein placed on the double-line bordering the cytosol compartment would represent an entity inserted into the plasma membrane.

Only make the compartments you need. When done you should have something along the lines of Figure 10.

Figure 10 - Compartments and entities in the primary drawing pane.

Laying out pathway

Creating pathways by Drag and Drop (DnD) individual reactions (method of choice): To start drawing a diagram you can successively "drag and drop" the individual reactions that you want from the event hierarchy into the pathway (this is the method of choice because it allows you to arrange reactions individually and in the order that you find the easiest to layout). When dragging and dropping a reaction from the event hierarchy into the diagram, you must first define the location at which you want to have the reaction placed. To do this, first click in the diagram at the desired location and then drag the reaction over.
Save often, preferably after each subpathway that you layout successfully. This is very important since there is no “undo”.

Creating pathways by Drag and Drop (DnD) and expansion of full subpathways: You can DnD an enitire subpathway from the hierarchy and "expand" it by right clicking on it in the diagram. This creates reactions quickly, and can be useful when you know that there aren't many "interconnections among reactions. However, when there are numerous interconnection this "autolayout" feature tends to create a bit of a tangle requiring some mental gymnastics to sort out. When dragging and dropping a subpathway from the event hierarchy into the diagram, you must first define the location at which you want to have the pathway placed. To do this, first click in the diagram at the desired location and then drag the reaction over.
Save often, preferably after each subpathway that you layout successfully. This is very important since there is no “undo”.

Note: If you chose to DnD and auto layout an entire subpathway, be aware that the moment that you first expand a subpathway, the entire subpathway will be highlighted. This is your only oportunity to move the entire newly expanded pathways to a clear area in your diagram. If you hover over the sub-pathway the cursor will change, indicating that you can move the entire segment. The exact icon you will see differs from platform to platform. In Windows, you see a 4 way arrow, on Mac you will see a hollow arrow. Click and drag the entire newly opened sub-pathway (and all its associated entities) on the canvas. If you choose to move it after it has been deselected, you will have to reselect the pathway (using the dragged selection rectangle or clicking on all the components you want to move individually).

Layout hints

Menu bar buttons and keyboard functions

Menu bar buttons:

Align vertically/horizontally button (figure: icon of button): This button allows you to align selected objects (entities, reaction line segments(?) along the vertical or horizontal axis.

Layout edges button (figure: icon of button): This button allows you to automatically reposition reaction arrows to fit with entities that you have moved around on a diagram.

Keyboard features: Use the up/down/left/right arrow buttons to move selected objects pixel by pixel.

General layout tips

Resizing/moving compartments: Zoom in so that when you select the compartment you can see 4 dots, one at each corner of the compartment. You can resize the compartment by clicking on one of the corner dots and dragging outward. Not that as you resize, entities associated with the boundries of the compartment will not move along with the resized edge...These will have to be moved separately. To move the entire compartment, click anywhere on the compartment (other than the corners) and drag. Note that the entities and reactions will move along with the compartment, but there will be a potentially undesirable “stretching” effect on the lines representing the reactions and this will have to be adjusted (Figure?). Resizing/reorganizing reactions: Zoom in as closely as possible. Click on reaction arrow. If the reaction box is “shaded” then the entire reaction has been selected.. The reaction can then be moved, but the components must also each be selected (holding shift key) for the whole reaction to move as a unit. To select/move only part of the reaction (or some of its components) hover over and click on node of the reaction that you are interested in. Look at the reaction box. If it is not “unshaded” you are still selecting the entire reaction.

Selecting a whole reaction and all associated entities: This is helpful if you want to move an entire reaction and keep its layout. Select reaction of interest. The right click menu now contains "select connected nodes" feature

Deselecting entites and/or nodes within a selected reaction/set of reactions: Within a "selected" reaction/set of reactions, hold the shift or control key down and click on the entit(ies) or node(s) that you want to "deselect".

See all rxns associated with an entity: Clicking on an entity will highlight in green all reactions that are associated with that entity.

Deleting reactions from diagram: Right clicking on a reaction will offer the possibility to delete a reaction from diagram. You will told that you are a about to remove that reaction (and any of its entities that are not used elsewhere in the diagram) and asked if this is ok.

Removing links to small molecules across reactions: Unwanted links between reactions that are created by "shared" small molecules can be removed by creating and using an alias(es) for the small molecules. An alias is a "carbon copy" of the molecule (it has the same DB_ID but is duplicated pictorially in the diagram).
You can create an alias for an entity in two ways:

1. select, copy, paste entity from the diagram
2. drag and drop from entity list/complex hierarchy panel.

To associate the alias with a reaction, click on the alias molecule and drag an arrow from it to the reaction of interest (selecting its desired function ...input, output, etc...). The connection with the original entity will be lost as the connection to the alias is created.

“Selecting specific nodes in a reaction” If you want to move/work with a single node in a reaction, First click on reaction to select it. As you hover over nodes in that reaction the cursor will change from an white arrow to a hand. (mac?) When this happens you can click on and move that node independently of the others.

Assignment of SBGN reaction type:

It is possible to assign one of 5 SBGN reaction types to reactions/ and black box events in the pathway diagram.

Association: Binding, formation of complexes etc...does NOT include creation of covalent bonds (ligation etc).

Dissociation: Dissociation of a complex. This does NOT include breakage of covalent bonds (see transition).

Transition: A standard biochemical transformation. Rule of thumb:If it has a catalyst, it's a transition. This class also includes transport and displacement (a molecule coming into a complex and displacing another). In questionable cases, ask and we can look into it.

Omitted Process: Can be assigned to most classic black box events in which the details of reaction are left out deliberately (as when we lump all of the known steps of mRNA synthesis, processing, translocation to the cytosol, and translation into protein into a single event e.g. “transcription of protein [X] positively regulated by [Y]”. This would include all black box events in which all the inputs and outputs could be fully specified if we chose to enumerate them (but we choose not to). This would also include degradation ( ubiquitinated protein gets degraded in the proteasome, we don’t really know the exact peptides that result but we want to label this case as though we do know, or could know).

Uncertain Process: “uncertain” would correspond to the garbage-collector use of black box event: we know something happens but we don’t know the mechanism. A rough test is that any reaction where we can (or could) specify molecular inputs and outputs but not necessarily stoichiometry would be “omitted”.

Example: Efflux of glucose from the endoplasmic reticulum

“Glucose generated within the endoplasmic reticulum is exported from the cell. Several mechanisms for this transport process have been proposed but experimental data remain incomplete and contradictory (e.g., Hosokawa and Thorens 2002; Fehr et al. 2005; Van Schaftingen and Gerin 2002).”

Exporting a diagram

You can export a diagram as a .png file by right clicking on the diagram and selecting the "export diagram" feature.

Deleting unwanted events from diagram

Occasionally, you will want to hide events from the diagram. For example, a subpathway may be set to dr_false. In this case, you need to select the event in the ELV by right clicking on it.

Figure 11 - Select the events to be deleted.

Select delete.

Figure 11 - Select delete.

Two dialog boxes will popup. The first will ask if you are sure you want to delete this.

Figure 11 - Select yes.

With the final confirmation, the object is deleted from the diagram only. To confirm this pay careful attention when syncing your project with the central database. The only entities that change during the diagram creation or editing process should be items from the Diagram class.

Consolidating reaction groups via sets

In cases where there are groups of reactions (or BlackBox) that could be converted into either a single reaction or black box event it is preferable to do that (deleting old events and pointing toward the new “consolidated” event as a “replacement' instance)

Example: Pathway: Activiation of E2F1 target genes

  • BlackBox1: Activation of Cyclin A by E2F1
    • output= Cyclin A
    • positively regulated by: E2F1:DP1 complex
  • BlackBox2: Activation of Cdc25A by E2F1
    • output= Cdc25A
    • positively regulated by: E2F1:DP1 complex
  • BlackBox 3: Activation of Cdt1 by E2F1
    • output= Cdt1
    • positively regulated by: E2F1:DP1 complex
  • BlackBox 4: Activation of Cyclin E by E2F1
    • output= Cyclin E
    • positively regulated by: E2F1:DP1 complex
  • BlackBox 5: Activation of Dihydrofolate reductase by E2F1
    • output= DHFR
    • positively regulated by: E2F1:DP1 complex
  • BlackBox 6: Activation of Emi1 by E2F1
    • output= Emi1
    • positively regulated by: E2F1:DP1 complex
  • Replaced by BB: Activation of E2F1 target genes
    • output = set (Cyclin A, Cdc25A, Cyclin E, Cdt1, DHFR, Emi1)
    • positively regulated by: E2F1:DP1 complex

BUT to do this you must make sure check if there are :

  1. “referring” instances that will be affected by the deletion
  2. to be continued...

A Script That Checks Whether Reactions Have Been Placed in ELVs

It's important to know that all finished reactions in gk_central have been associated with an ELV and also useful to have a way of finding reactions that have been associated with multiple ELVs. Here is a script written by Guanming Wu that generates that information: Please use this URL to launch this script: http://brie8.cshl.edu:8080/ELVWebApp/ReactomeScripts/ReactomeScripts.html

After click the Launch button, you will be asked to input some information. Please enter as following:

DB Name: e.g. gk_central or other database name you want to check
User: ELV Check
Key: [this string has the same function as a password; ask Guanming Wu for it]

Using the above information is just to avoid unnecessary server side processes initialized by robots or some malicious code. The information input above should not be regarded as secure!

Here are first several lines from the output:

Reaction_DB_ID Reaction_Name _doRelease Number_of_Diagrams Diagram_DB_IDs Diagram_Names
68595 Orc3 associates with Orc2 constitutively bound at origins of replication true 0
68603 Orc5 associates with Orc3:Orc2:origin complexes true 0
68610 Orc4 associates with Orc5:Orc3:Orc2:origin complexes true 0
68611 Orc1 associates with Orc4:Orc5:Orc3:Orc2:origin complexes true 0

It is tab delimited so you can load it into Excel for any sorting you like. Currently it is sorted based on "Number_of_Diagrams".