The Pathway Editor is a program for managing, visualizing, and editing signaling and metabolic pathways. In addition to the default Pathway Editor (.path) format, the Pathway Editor can read, edit, and write files in SBML (.sbml), and BioPAX (.owl, .xml) formats. This tutorial provides an overview of Pathway Editor features, including how to start the Pathway Editor, access LIPID MAPS pathways and display LIPID MAPS and user-provided experimental data, create pathways from scratch, and edit and save pathway files and images. Instructions for working with SBML and BioPAX formats are also provided.System Requirements
- created using the Pathway Editor acting on downloaded path files from our Pathway database
Click on "yes" each time you are asked if you trust our downloads (we assume you do). The Editor asks if you want to associate files ending in “.path” with this program. If you do, click "yes" on the PC, or check the box next to "Do this automatically for files like this from now on" on the Mac. This allows Pathway Editor to be placed on a list of programs that opens this file type.
When the download completes, the editor will start up and look like this:
The 3 leftmost buttons in the toolbar at the top allow entry into node select mode, node creation mode, and node connect mode. The next two buttons allow you to zoom in and out, repectively, with the current zoom level shown in the 'Current' button. The 'Fit to screen' button fits the current pathway to the canvas. The last two buttons, 'Tilt up' and 'Tilt down', allow you to tilt the pathway plane. The scrollbars on the right and bottom of the drawing canvas allow you to move the viewing area vertically and horizontally over the drawing plane. The mouse scroll wheel allows fine-grained zooming in and zooming out in small increments.
Dialogs were designed using screen dimensions of 1920 x 1200 pixels on Windows and Macs. If you have difficulty with dialog sizes, you may wish to change your screen resolution to pixel dimensions that match these in relative proportion
Go to the "File" menu and select "Open a Workbench pathway file..." to get a file-opening window. Select a file, click "Open" and the pathway will load.
Pathway files must end with ".path". If you do not already have a .path file saved to your local environment, you can download the .path file for Arachodonic Acid metabolism: AApathway9genes.path
A .path file contains descriptions of the components of a pathway and their appearance in the Editor display. It contains database IDs (identifiers) and other material that identify specific molecules. This information is checked when the Editor opens the file and is updated from the database automatically. The file may also contain experiment IDs that reference experiment data in the LIPID MAPS database. The presence of experiment IDs instructs the Pathway Editor to download experimental data. All of the data for a time course (lipidomics) experiment is downloaded. For a microarray or protein array experiment, only the data for the microarray or protein array molecule identifiers currently being used in the file and in the currently displayed pathway are downloaded.
Additional .path files may be downloaded from http://www.lipidmaps.org/pathways/pathwayeditor.html, or accessed from within the Pathway Editor application, as described below in "Open a LIPID MAPS pathway from the database".
Go to the "File" menu and select "Show pathway info" to get a Pathway information window.
The window contains information that may be edited and saved to a .path file. This includes pathway title, type of pathway, comments, authors, and history.
The KEGG pathway download dialog contains controls for setting viewing preferences that allow for fitting large numbers of nodes within the viewing panel. These include the zoom, size on the screen, font and node sizes, and label placement. After downloading, if you wish to perform other tasks, you might reset node and pathway preferences using dialogs from the Edit menu.
Go to the "File" menu and select "New pathway " to create a new empty pathway.
On the toolbar, select the box-shaped icon (2nd from left) to enter node creation mode, then click in the drawing area to drop a new node at the cursor. Nodes are always box-shaped icons.
The blue outline shows that the node is selected.
You can show information about a selected node by doing any of the following (they are all equivalent):
All of these bring up a window about the node. From this window you can change the node's label, compound, and other attributes.
To assign a compound to the node, select the "Compound" tab and press the "Select compound..." button. This shows a compound search window.
Constrain the search by selecting the compound type and category and/or entering a keyword. Radio buttons provide further constraints on the text that is searched. Then press "Search" to get a list of results.
Select one of the compounds from the list and press the "Select" button. The compound is loaded from the database and assigned to the node. You can view the compound's details by pressing the "Show info..." button on the node's information window.
Change the node's label to anything you want by typing a new value in the "Label:" box in the node's information window. Up to 3 lines may be entered. Additional lines will not be saved. To set line indents, see "Change the appearance of an individual node"
This changes the label on the node's box in the drawing area.
Continue using the "box" icon. Drop more nodes into the pathway and assign compoundes to them.
Click on the dot-and-arrows icon on the toolbar (third from the left) and click-and-drag to draw connections between nodes.
A process or interaction is a connection between two or more nodes. The process is drawn as a square withe arrows connecting the square to nodes. Nodes with arrows into the square are reactants. Nodes with arrows from the square are products.
The first time you connect two nodes, you create the process. After that, you can drag a connection from a node to the dot, or from the dot to a node to add the node to the process.
You can show information about a process by selecting the process square and then performing one of the following:
All of these show an information window about the process.
From this window you can enter information on the process in the "Label" field, change its process type, and see a list of the nodes connected to the process. For each of these nodes, you can change their role in the process and their stoichiometry. A node's role can be a reactant, a product, a catalyst, an inhibitor, and so on. Inhibitor nodes are drawn with a "bar" on their connection line. The rest are shown with arrows.
Click on the arrow icon on the toolbar (the left-most button) to enter selection mode. Click and drag to move any node. Process arrows stay attached. Click and drag a process square to move the square.
Shift-click to select multiple nodes. Or click on the background and drag open a selection box around nodes and processes to select a group, then move them as a group.
Right-click on a node. Select "Node preferences..". The "Edit viewing preferences" window appears, with the tab for the type of node selected. The tab contains current viewing preferences for the node. Change any of the settings and press "Apply". Then press "Done" or exit the window.
"Automatically resize" means to let the application change node size when typing in a label. If the setting is No, the Node height and Node width may be changed using the drop-down lists. In addition, the handles on the sides of the node are then activated, allowing the user to drag out the sides to a desired position.
Until experience is gained with the Editor, it may be best to limit use of this feature to the very first step in creating a pathway.
Select a region of the drawing area by clicking in the drawing panel and dragging to create a rectangle enclosing the nodes to be changed. Then right-click on any node. The "Edit viewing preferences" window appears. The window contains current viewing preferences for the first of each kind of node in the selection. Changes made to any of the tabs in this window will affect all the nodes in the selection (not just the first node).
Alternatively, select all nodes by accessing the Edit | Node preferences menu. An "Edit viewing preferences" window appears. Changes made on this window will affect all current and new future nodes in the pathway.
Make the desired changes and press "Apply" followed by exiting the window or by clicking "Done". The changes should appear in the drawing panel.
Until experience is gained with the Editor, it may be best to limit use of this feature to the very first step in creating a pathway.
Make sure that no processes are selected and go to the Edit menu and select "Interaction preferences...". Alternatively, select a region of the drawing area by clicking in the drawing panel and dragging to create a rectangle enclosing the processes to be changed. Then right-click on any process and select "Interaction preferences". The "InteractionEdit viewing preferences" window appears. The window contains current default viewing preferences for the program, or for the first interaction in the selection. Changes made to any of settings in the window will affect all the interactions in the selection and all interactions that are added later.
Make the desired changes and press "Apply" followed by exiting the window or by clicking "Done". The changes should appear in the drawing panel.
Right-click on a process square. Select "Interaction preferences..". The "Edit interaction preferences" window appears. Change any of the settings and press "Apply". Then press "Done"
The Editor uses different sets of settings for displaying pathways, depending upon the type of file. Both sets can be inspected by selecting "Pathway preferences" on the Edit menu.
Changes to pathway settings must be made before reading a file or downloading a pathway.
For .path files, the Editor automatically fits the pathway to the screen dimensions. It automatically uses the zoom setting that was set when the file was saved. Alternatively, the file zoom may be ignored, or a different zoom may be applied, using the Pathway preferences window.
For KEGG file downloads, the same features are available, with the exception of using a file zoom setting. KEGG pathways files do not contain zoom levels.
By default, node labels are written in Arial 18 point Plain font as contained within the Java language. Font attributes can be changed using the Node preferences dialog.
Labels written in "JOGL fonts", available by way of the Node preferences dialog, appear garbled on some monitors. Java fonts are recommended. However, please be aware that there may be slight differences in the font layout on Windows and Macs.
Construct a pathway and load one or more experiments that contain data to be displayed. Go to the Tools menu and select "Manage data display".
The window that appears contains controls that allow changes to default display settings for data. Make the desired changes on each tab and press "Apply". The changes should appear instantly.
Data may be displayed in the form of heat maps or line charts, separately for each type of node. If heat maps are selected on the first tab of the window, the treatment ratio may then be selected. The default treatment ratio is Kdo/Control.
Alternatively, line charts may be set on the first tab, and line chart settings may be set on the "Chart settings" and "Series colors" tabs.
The changes apply both to data displays in the drawing panel as well as in node information windows.
On the drawing panel, double-click a chart. In the window that appears, select the "Plot" tab and double-click the chart. Yet another window containing a chart appears, that may be resized. Right-click on the chart and select one of the menu items. "Save as" leads to a window that permits saving a chart in a .png image file. "Print" leads to a window that allows access to the local printing network.
The Pathway Editor provides for animation by changes to node colors, bar charts, heat maps, and xy line charts. Animation is started, stopped, paused, stepped forward, or stepped backward using the toolbar or by selecting options on the View menu. Animation settings are set on the "Manage data display" tool available from the Tools menu. The tabs on this tool that apply to animation are the Basic settings tab and the Animation tab. Animated gifs may be incorporated in PowerPoint presentations.
Animated gif images that show changing experimental data are produced using a combination of dialogs. A number of static images, one for each time point, are generated and combined into an animated gif image.
Videos may be created using the "Create avi videos" tool from the Tools menu. This tool operates much the same as the Animated gif dialog. The end result is a file named "anim.avi." The output has been tested using QuickTime and Windows Media Player. Avi videos may be inserted into Power Point presentations as well.
The default settings for a video of 13 frames at 96 dpi image resolution generate a file that is 27 Mb in size. A very high video resolution is possible by selecting tif images and setting the resolution to a large dpi, such as 300. However, considerable RAM is necessary for processing. In addition, the video size may be on the order of several hundred megabytes!
Go to the "File" menu and select "Save pathway as..." to get a save window. Enter a file name, select the "PATH" file type and click "Save." The PATH format is our own file format that supports saving display parameters for the pathway and its assigned compounds.
Experiments are also referenced in the .path file if experiments were previously downloaded from the database. The data for these referenced analyte (lipidomic), microarray, and protein array experiments are automatically downloaded from the LIPID MAPS database when the file is read back into the program.
Go to the "File" menu and select "Save image as..." and select any of 'bmp', 'jpg', 'jpeg', 'png'. Please note that on the Mac, before saving your pathway as an image, you must first select any node in the pathway. If you do not first select a node, the image will be saved, but if experimental data is shown in the pathway, some of this data may be missing from the saved image.
Go to the "Tools" menu and select "Manage time course experiments..." to get a list of loaded experimental data (initially empty).
Click on the "Add" button to add an experiment from the database.
In the window that opens, optionally enter a keyword or keyword fragment and press the "Search" button to search descriptions and lab titles in the database.
Select an experiment from the list and press the "Add" button to load it into the program. Relevant experimental data is automatically shown in heat maps or line charts under each node in the pathway.
To view an experiment's data, select the experiment and press the "Show info..." button.
Select any of the compounds in the Manage time course experiments window to show their heat map or line chart and raw data to the right.
You can add more experiments to the Manage time course experiments window by clicking the "Add" button and searching the database again. Click the "Remove" button to remove an experiment. Click on the checkbox beside an experiment to show it in the pathway (checked) or hide it (unchecked).
Check the "Average experiments" checkbox to average the data in the list of experiments for purposes of display.
If the "Average experiments" checkbox is not checked, then only the data of the first checked experiment in the list is displayed. The rest of the experiments are ignored.
Go to the "Tools" menu and select "Manage microarray experiments..." or "Manage protein array experiments..." to get a list of experimental data.
The next steps are nearly identical to those in "Search for experimental lipidomics data". The exception is that data is downloaded only for these gene symbols that are currently assigned to existing nodes.
The database is checked for data assigned to gene symbols when an array experiment is selected and the "Refresh" button in the "Manage microarray experiments" or "Manage protein array experiments" windows is pressed, and also when a .path file referencing an array experiment is opened.
P-values for a microarray experiment may be searched using the window that appears when a microarray experiment is selected and the "P-values" button is pressed.
To search P-values, select a type of P-value and enter the upper P-value of the range to be used.Press "Search". A list of gene symbols and their P-values are shown.
The gene symbols and P-values can be sorted by using the "Sort" buttons, or by pressing a column header.
The Pathway Editor loads CSV (Comma Separated Value) data files generated by Microsoft Excel. CSV files may be opened using Excel for editing, if desired. Data files may also be created using a text editor. Below is a description of a CSV data file.
Sample CSV files
Sample .path files
Note that steps 1 and 2 can be performed any number of times and in any order.
Each data file may contain one or more experiments. Each experiment may contain Analytes (metabolites, comprised of Small molecules, Proteins, or Nucleic acids), Microarray, or Proteinarray compound types. However, an experiment may not contain a mixture of compound types.
The Pathway Editor reads simplified user data files in Excel and in tab-delimited formats. Both metabolomic (analyte) and array data may be contained in these files. As with CSV files, they may also contain biological treatments that are different from those contained in the Pathway database.
Excel and tab-delimited files are read by selecting the appropriate menu items on the File menu. Upon reading a user data file, the Pathway Editor creates an experiment and assigns data to nodes that contain the label that is the same as a name in the files. If no compound is associated with the node, a new compound is created. This new compound is cleared from the program when the experiment is removed.
When calculating averages for heat maps, and for ratios calculated for line charts, each experiment is weighted equally, regardless of the number of repetitions within the experiment.
Heatmaps involve ratios of measured values at each time point. If there is no measured value for either numerator or denominator, a blank is drawn. Similarly, node color animations also involve ratios of measured values. If there is no measured value at a time point for either numerator or denominator, the last color for which there is both numerator and denominator is used.
The format of VANTED-style template 1 (for analyte) and template 2 Excel files (for arrays) is followed (
For both analyte and array files, replicate numbers are ignored by the Pathway Editor. In addition, time values need not be integers. Any time unit may be used. However, the user is cautioned when attempting to simultaneously view database and user data, as the time unit of the first experiment in each experiment list is used for charts and heat maps and may not be the same as for other experiments.
Some optional modifications of the template 1 format have been added for the Pathway Editor, and should be readily understandable by inspection. These include differences in required and optional fields. Optional fields are marked by an asterisk (*).
A description of the Excel data format for microarrays and protein arrays may be found at http://vanted.ipk-gatersleben.de/index.php?file=doc9.html (VANTED "Template 2"). This format follows that of the program J-Express. Pathway Editor will assign the data to protein nodes.
The initial rows of the file may contain information that is ignored until a row beginning with "Spot" or"spot" is reached. This row is assumed to contain column headers. Column headers are traversed until data column headers are found. The columns prior to reaching the data columns are assumed to contain metadata for the protein. Cells underneath data column headers contain data for the time and treatment specified by the respective column header.
Data column headers may contain the following different formats:
When an Excel array data file is read, a dialog appears that displays text fields in which experiment metadata may be entered. An important concern is that the column to be used for comparing with node labels must be carefully chosen. In addition, if the column headers contain single treatments, and one or more ratios should be chosen for display. The Pathway Editor computes ratios as needed. If data column headers contain treatment ratios, the selection list is non-editable, and all treatment ratios in the list are accessible by the user.
Metadata for the respective protein is shown on the Comments tab of the compound dialog for each node.
Tab-delimited analyte data files contain 4 columns with the following headers in the first row: "Analyte", "Treatment name", "Time", and "Value". Each of the columns must be separated by tabs. Times and values may be in either integer or decimal format. An example is contained in SampleTabDelimitedAnalyteData.tsv. This file contains 4 treatments. The treatments may be any desired by the user.
When a tab-delimited data file is read, a Metabolomics experiment metadata dialog appears in which the user must select or enter the date of the experiment, the analyte type, time units, data units, and one or more ratios for heat map or chart ratio display.
An example file containing array tab-delimited data is SampleTabDelimitedArrayData.tsv. This file contains 10,000 rows of data drawn from another file containing 43,962 lines of data for an experiment involving RAW cells. Additional information on this experiment may be found at http://www.lipidmaps.org/data/results/raw2647/kdo2lipidatimecourse/compactin.html. Attempting to read a file of this size may cause problems. If this happens, reducing the number of lines in the file may be effective.
The first row contains column headers. A varying number of metadata columns may be contained in array data files; however, one of these columns must be headed "Gene symbol" and must contain names of node labels if the data is to be associated with a node. To the right of the metadata columns are the actual data columns.
The format of the data columns is "nn cccc", where "nn" is a time and "cccc" is a single treatment or a ratio of treatments (such as "Treated/Control"), with time and treatment separated by a space. A zero time column is not necessary, though it may be included.
After a tab-delimited array data file is read, an Array experiment metadata dialog is shown. The user must select the array type (Microarray or Protein array) and enter text for the time units. If the file contains single treatments, ratios must be selected from the list of ratios.
Metadata for the gene symbol is shown on the Comments tab of the compound dialog for each node.
The Pathway Editor can analyze a list of LIPID MAPS identifiers and report on the involvement of KEGG pathways using a technique known as "pathway enrichment analysis".
The pathway enrichment analysis tool is accessed from the Tools menu, as follows.
Following are the parameters used to calculate probabilities, using one type of notation:
Results are reported in a format in which N is on the first line and k is shown on the second line. Below these are the results for each pathway, in decreasing order of i. Each line contains the name and KEGG ID of the pathway, i, b, and the p value as a decimal value between 0 and 1.
Following are 2 test sets of 30 LM identifiers. The first set was chosen randomly. The second set was chosen from the set of identifiers that are contained within the KEGG arachidonic acid pathway.
The Pathway Editor reads and writes pathway layouts in GML format. These layouts describe a two dimensional node layout, along with node labels. VANTED and other modeling programs may use more features of GML, but such information does not interconvert into Pathway Editor-usable information.
Two GML files are available: CentralMetabolismBarley.gml and VANTEDDemo.gml. Both were obtained from the VANTED program (http://vanted.ipk-gatersleben.de/index.php?file=doc0.html).
A GML file may be read after selecting the appropriate item from the File Menu to bring up a file dialog. The Pathway Editor will read the file and present a "GML reader dialog". By default, nodes are assumed to be of small molecule type. The GML reader permits the user to change the type of selected nodes as desired. Pressing the "Layout" button will transfer the layout to the drawing panel and will connect nodes using edge directions that are specified as reversible or non-reversible in the file. The layout will be expanded or compressed to reside within the borders of the viewing panel, unless preferences are set differently on the Pathway preferences dialog available from the Edit menu.
A GML file may be written by selecting the appropriate item from the File Menu to bring up a file save dialog. The Pathway Editor will write edge directions and relative node layout in the output file in a way such that it will be readily laid out and displayed upon reading by VANTED. VANTED deals with interaction glyphs differently than the Pathway Editor. An interaction that has more than 1 reactant or more than 1 product in a GML file generated by the Pathway Editor does not display properly in VANTED. Node colors will also be incorporated into the file. However, references to subpathway nodes or nodes contained within subpathways are not included in the GML file.
Organelle drawing makes use of complex 3D drawing and lighting effects.
When reading a pathway containing organelles, nodes, and interactions at values of Z greater than 0, it may be necessary to deselect the "Automatically fit to screen" option on the Pathway preferences dialog. This feature cannot effectively fit structures outside the XY plane at this time.
1. A compressed pathway may be created by selecting a group of participant and/or subpathway nodes, right-clicking on the drawing surface, and selecting "Compress selection".
The selection must include at least 2 nodes and at least 1 interaction.
The resulting subpathway node has display properties that may be set by right-clicking and selecting "Show info" or "Subpathway preferences", analogous to participant nodes.
Interactions may be drawn to and from subpathway nodes using the mouse if they exist within the same upper-level pathway and are showing. "Links" or individual connections may be made between participant nodes or subpathway nodes in different pathways using dialogs. Connections may also be made between participant and subpathway nodes node in one pathway and an interaction in another. These links are either created anew, or are added onto already existing interactions.
When an interaction is created between a node in one pathway and an interaction in another pathway, the resulting interaction is considered to be within the same pathway as the original interaction.
2. The subpathway node contains a pathway that can be expanded by right-clicking, and selecting "Expand selection". Note that this feature can result in loss of information pertaining to the sub pathway. Expanding subpathways using the Manage subpathways dialog should be the preferred method.
3. A second way of expanding can be executed from the Manage subpathways dialog, obtained using the Tools menu. This dialog displays tabs that contain the following:
To expand a subpathway, select a subpathway on the pathway list tab and press "Expand selection."
To return to the top-pathway, press "Show top pathway".
Information on the subpathway can be obtained by selecting a subpathway on the pathway list tab and pressing "Show info."
4. The contents of a subpathway can be altered by bringing up the subpathway on the display using one of the above expansion methods, and altering or changing the display.
The changes are stored when the user displays another subpathway, or the top pathway.
5. Links or interactions between nodes and interactions that are internal to subpathways may be viewed and deleted using the "Manage pathway links dialog", available from the Tools menu.
To view properties of a link, select a row of the Manage pathway links table and press the appropriate button. To delete a link, select a row and press "Delete link". There is a bug in the program involving a link between a node in one pathway and an interaction in a second. In this case, select the row again and press "Delete link" a second time.
Interactions may be constructed from any participant or subpathway to any other participant or subpathway. Reactants and products can also be added to an existing interaction between or within subpathways.
3. After a subpathway is expanded on the drawing surface, changes may be made to the subpathway. These changes are preserved after the modified subpathway is compressed (i.e., another pathway is expanded). Information on any visible dialogs is then updated.
Two methods may be used. The first is laborious and involves adding nodes and interactions individually. Z heights that place icons at different heights above the plane of the screen are entered during construction. The second method is faster and involves prior construction of pathways for the layers and saving to separate files, depending upon the desired result. After the files have been constructed and saved, build up a layered pathway as follows:
The Pathway Editor can read and write models in Systems Biology Markup Language Format (http://www.sbml.org). SBML models are quantitative computation models that are mathematical descriptions of time-dependent changes to species in a pathway. The Pathway Editor makes use of JSBML, a Java-based API that is still under development (http://sbml.org/Software/JSBML). The complex nature of such models requires that users possess a good understanding of SBML before modifying or building models. Seven different releases of SBML specifications are supported. Each has a level number and version number. Level 1, version 1 models are read-only; new models in level 1, version 1 cannot be written. To ease use, dialogs in the Pathway Editor may appear different for different releases. In addition, some menu items and controls are inactivated (greyed out) to indicate that they do not apply to the release that has been selected. In the following, note that information entered into dialogs is inserted into an SBML model when the user presses "Done" on Windows or closes a dialog on Macs.
To reiterate, the user can arrange nodes in the drawing panel by recursively selecting (checking) the left cell in a row and left-clicking on the drawing panel and pasting by going to Edit | Paste on the top menu to achieve the desired layout. Alternatively, the user can press "Auto layout" to lay out nodes automatically. The viewing panel can be cleared by pressing "Reset" on the SBML Reader dialog.
Note that double-clicking on a row of the annotation table in a dialog causes the user's browser to access the associated URL contained within the program.
Ensure that the desired SBML level and version are set on the SBML Model dialog when beginning to design a model. Enter model content using the SBML dialogs. The SBML Default save dialog, available on the SBML menu, allows the user to turn off or on automated species ID and compartment creation, as desired. Using the Save SBML dialog available on the File menu, save the model. JSBML does not validate models against SBML model specifications. To check whether a model is in accordance with SBML specification, use the on-line validator at http://sbml.org/Facilities/Validator/. Local validation is expected to be added in the future. The "Clear SBML model" option on the File menu clears the SBML model.
Math expressions in SBML are written using a subset of Mathematics Markup Language (MathML). Please consult http://www.w3.org/Math/Software/ and SBML specification documents at http://www.sbml.org for information. The Pathway Editor uses JSBML to convert MathML expressions to formula string or algebraic formats (such as x * y, which represents the product of 2 variables x and y). The format is the same as that specified in SBML level 1. Unfortunately, later SBML levels are more advanced and the MathML may not convert to formula strings. Thus, by default, math expressions must be entered into models in MathML format. Also, because the Pathway Editor makes use of a pre-release version of JSBML, the Pathway Editor does not currently enable reading, editing, or writing SBML models that make use of SBML constructs within MathML called "csymbols". Csymbols represent, for example, simulation time, delay time, or Avogadro's number. The user should find alternate ways of expressing these in a model.
To enter and save formulas in MathML:
To enter and save formulas in formula string or algebraic form:
The button above the MathML entry area can be used to toggle between formula string and MathML views. However, if the area contains a csymbol, or more advanced MathML elements, some of the content may be lost. This is because of difficulty translating between MathML and formula strings.
The BioPAX ("Biological Pathway Exchange", http://www.biopax.org) model file format provides for descriptions of pathways in text form. The Pathway Editor supports levels 2 and 3. Within the Pathway Editor, BioPAX models may be read from file, modified or constructed from scratch, and saved as either a .path file, for further editing within the Pathway Editor, or in .owl or .xml format for further editing in other applications.
BioPAX model files are structurally more complex than the basic Pathway Editor file format. Following is a brief description of the relationship between BioPAX and Pathway Editor requirements. These instructions address primarily level 2. Level 3 usage is analogous.
In BioPAX, the basic entity is a physical entity, analogous to a compound in the Pathway Editor path layout. The participants of an interaction are formally defined as Interaction Participants. In the Pathway Editor, participant nodes are not required to contain a compound. However, BioPAX requires that each Interaction Participant contain a physical entity.
One or more BioPAX interactions comprised of Interaction Participants may be represented by a single Pathway Editor interaction (for example, a biochemical conversion plus a catalysis). In BioPAX, additional links may be defined between different pathways and between pathways and nodes contained within other pathways. BioPAX links between components of pathways are not shown directly on the Pathway Editor drawing panel, but instead are shown in dialogs.
Many features of BioPAX are optional, such as entities referred to as pathway steps. Pathway steps may contain complete pathways and nested subpathways, or may just contain a series of interactions, or combinations of subpathways and interactions.
The Pathway Editor uses identifiers of entities given in BioPAX files that are read by the program, and will also assign identifiers to new entities that are added by the user. Identifiers for BioPAX entities are not shown in the Pathway Editor, but instead are managed out of view of the user.
Pathway steps are optional entities that enclose one or more BioPAX pathways, pathway steps, and interactions. Pathway steps may be created by the user after BioPAX interactions are created, using the "Pathway steps" dialog obtained from the BioPAX interaction tab of interaction dialogs. Lists of pathway steps are shown on the "Pathway steps" dialog, obtained by selecting the BioPAX | Pathway step menu. Select from the list at the top of the dialog to see the properties of individual steps. The comments tab shows comments for the pathway step that is selected.
BioPAX pathway entities are optional in a BioPAX model. If a pathway is present, it is shown as a subpathway node on the drawing panel. The attributes of pathways are set on the dialog that is obtained by right-clicking on the pathway node and selecting "BioPAX entity info." Attributes can also be set on the "Manage BioPAX pathways" dialog, obtained by selecting the BioPAX | Pathway menu.
A single top-level pathway that encloses all other BioPAX entities can be established using the "Create top pathway" button on the Manage BioPAX pathways dialog. At least one BioPAX interaction and two nodes containing BioPAX Interaction Participants must be showing on the viewing panel. The presence of a tab containing the title "Top pathway: Top pathway" indicates that a top-level pathway has been created. The top pathway can be removed using the "Remove top pathway" button.
A new BioPAX pathway may be created by first constructing a subpathway node. Then right-click on the subpathway and select "BioPAX entity info." Enter the attributes, synonyms, and comments to be assigned to the new pathway. Many attributes, such as the biosource, datasources, and so on must be created first using other BioPAX dialogs. When finished, press "Done" to create the pathway and insert all the sub-entities contained within the compressed node.
BioPAX requires that certain kinds of information, such as chemical structures, references to external sources, and publication and database references, be defined separately from the participants in interactions. This information may be entered or viewed in dialogs available from the BioPAX menu. If needed, Pathway Editor names signifying a utility information may be obtained from utility class dialogs and entered into other BioPAX dialogs as necessary, using selection dialogs called by pressing buttons. Because the designers of BioPAX intend that BioPAX identification tags in a model not be shown to users, the Pathway Editor creates names that can be used to track this information for presentation purposes. Thus, in the process of model building, these names may change each time the model is read from file. See the BioPAX documentation for details.
The Pathway Editor reads, constructs and edits mathematical models in CellML. Both CellML 1.0 and CellML 1.1 are supported (http://www.cellml.org/specifications).
In CellML, reactions (reactants, participants, and enzymes) are not supported. The actual term is "deprecated", meaning that though the specification documents describe reactions, their implementation is discouraged (http://www.cellml.org/getting-started/cellml-primer#section-7)). Mathematical expressions in CellML files are described using MathML (www.w3.org/Math/). CellML does not specify visual presentations, except for presentation of mathematical equations. However, there is no agreed upon mechanism for visually editing either CellML or MathML. Consequently, nearly all of the manipulation of CellML and MathML content is performed using text entered into dialogs.
After a specification version is set on the Model dialog, the version cannot be changed.
The Pathway Editor uses code libraries that are specific to each operating system. Unfortunately, they are not accessible from Java Web Start. Consequently, a stand-alone program must be downloaded and installed for this functionality. For CellML in a stand-alone program, download and install a separate installer program using one of the following links. These installers were created using Install4j:Mac
Mac OS X 10.5: CellML code libraries do not work on this version. Please use the Web Start version (no CellML).
On Mac platforms, double-click on the .dmg file on the desktop or in a Finder dialog. Then, double-click on the Pathway Editor insta ller icon or row in a Finder dialog to install. After installation, double-click on the Pathway Editor icon or row in the Finder dia log.Windows
To install on Window platforms, double-click on the Windows executable and follow the dialogs. After installing on Windows, the option to start the Pathway Editor will appear on the list of installed programs that are accessed from the list of program files and also from the Start menu. For platforms other than the above, please contact the webmaster.. After installing on Windows, the option to start the Pathway Editor will appear on the list of installed programs that are accessed from the list of program files and also from the Start menu.
For platforms other than the above, please contact the webmaster.
Dialogs in the Pathway Editor allow inspection of model content by selecting names in tables. Generally, selecting a row of a table will lead to tables underneath the selection table to become populated with information relevant to the selected element and its sub-elements. This convention is used because of the generally hierarchical nature of CellML. Buttons associated with these tables become activated when such selections are performed.
The CellML file specification contains reactions; however, the website of the CellML project (www.cellml.org) discourages their use (http://www.cellml.org/getting-started/tutorials/the-now-defunct-reaction-element-in-cellml/?searchterm=deprecated).
Reading and writing CellML model files, and clearing models, is performed using menu items on the File menu. CellML dialogs are accessed from the CellML menu.
The CellMLReader dialog is displayed when a CellML model file (name ending in .cellml) is read using a dialog selected on the File menu, or the "CellML reader dialog" is selected on the View menu.
The CellMLReaderDialog dialog works similarly to the SBMLReaderDialog and the BioPAXReaderDialog, except that interactions are not drawn when transferring nodes to the drawing panel.
As a substitute for reaction components, the CellMLReaderDialog transfers components and variables to the viewing panel but does not draw interactions. CellML components are represented by subpathway nodes, while variables are represented by the usual nodes for different compound types. Thus, variables serve as placeholders for reaction participants. Because there are typically more variables than needed for representation of reactions, the user needs to decide which variables are worthy of being part of a pathway drawing.
The model element is the highest level structure in CellML. In actuality, the “Document” element may perhaps be a higher-level element, as a document may be considered to contain a model plus metadata that is associated with the document. A document element is not explicitly indicated in the CellML file, but it is referenced in the Metadata Dialog only for purposes of tracking metadata.
The Model dialog shows several kinds of model constituents that are defined or constructed using their own dialogs.
Every model must have a name. Models may contain units that may be used by components. These components may be comprised of model components as well as components that are imported. Imports are composed of model units and components that are extracted from other models and may be used to add computational features. This is an example of reuse.
Units are shown in the Units table when a component is selected. The "Model units" button causes units that are defined within models to be listed in the Units table.
Components are the smallest functional unit of a model. A single component can represent a valid CellML model (Lloyd et al, Prog. Biophys. Molec. Biol 85 (2004), 433-450). They contain variables and one or more mathematical formulae that describe biological processes. They may also contain units that are used locally by the component.
The CellMLComponent dialog shows names of components within the model, as well as any imported components.
Units may be defined within a component, but the units are not made available for use outside the component. Variables may be assigned both local units and model units.
Formulas in components are constructed in XML in the form of MathML elements and are listed in the MathML table as "Expression 1", "Expression 2", and so on.
The Units dialog may be used to build units that are associated with variables inside components. Units may also be placed inside a model element, in which case they are shared among components. Units may be either standard units that are a part of CellML, or they may be defined by each model.
The top table shows a list consisting of the model name, imports, components, and imported components. Selecting any of these rows causes the "Units" table to become populated with a list of the units within that element.
Selecting a "Units" in the Units table will show the structure of the Units in the form of separate "unit" elements on tabs of the tabbed pane at the bottom of the dialog. These unit elements comprise the blocks upon which units elements are constructed. The properties of each unit may be set. After setting unit properties, "Accept tabs" must be pressed, after which "Done" must be pressed to save the contents of the entries.
The Variables dialog defines variables that are used within components. Variables consist of a name and a "units", that is in turn composed of 1 or more "unit" elements. Variables may be assigned a standard units that is part of the CellML language, or variables may have units that are user-defined.
The top table contains lists of component and imported component names. Selecting one causes the "Variables" table to become populated.
In turn, selecting a variable name causes the controls beneath the Variables table to display the properties of the variable.
The "Public interface" and "Private interface" properties allow grouping of components in different relationships with respect to each other. These relationships allow sophisticated modeling calculations to be performed independently when used within a simulation program.
Connections loosely defined are interactions between 2 components, in which values of a variable may be obtained from 1 component and used in a second component during simulations.
The Connections dialog allows definition of connections. Connections may be constructed between components of a model, and between model components and imported components. There are restrictions on constructing connections, based upon relationships between groups.
The CellML specifications contain explanations of the importance of connections for modeling purposes. See the section on groups found below for more information.
On first opening the Connections dialog, a list of all connections in the model appears at the top in the "Current connections" table. If one of the listed connections is selected, details of the connection are listed in the tables below. The "Current variables" tables show the variables and units that currently comprise the connection.
To construct a new connection:
Groups are assemblies of components that restrict connections according to relationships. CellML specifications define two relationships that are named "encapsulation" and "containment". For a description of restrictions imposed by encapsulation, please consult the CellML specifications. Containment is also a relationship that is named in the specifications, but restrictions are stated to be imposed by the processing software rather than the CellML software itself. The Pathway Editor allows use of containment, but it does not associate restrictions with containment.
In addition to encapsulation and containment, any arbitrary relationship may be added to the model. The rules for grouping of these relationships are enforced by processing software outside the Pathway Editor.
When the Group dialog is first displayed, all groups defined by the model are shown in the "Groups" table. Selecting one of the groups causes the relationships for the group to be shown in the "Relationships" table. The "Component hierarchy" table is also filled. Top-level components are shown beginning at the left side of the table. Sub elements of the hiearchy are indented.
To create a new group:
To add a subcomponent:
To replace a component:
To delete a component:
The MathML dialog allows management of formulas (expressions) in MathML (XML) format. When the MathML dialog first appears, components and imported components are shown in the top table. Expressions take the general form of two-sided equations such as y = f(x).
CellML models that conform to the CellML 1.1 specification may be combined by importing model units and components from one file into a second. Once imported, imports cannot be modified.
For purposes of constructing connections, the units of an imported component must be defined in the imported model, not in the imported component.
In the Import dialog, the component name and units name tables contain the names that may be used in the current model as a substitute for names in the imported model in the first column. This permits avoidance of name clashes.
Connections can be made to imported components, and imported model units can be used within existing components. Variables, component units, and MathML in imported components can be inspected but cannot be modified using dialogs on the CellML menu.
In some cases, a component in an import must access other components in the import, which are part of groups. Consequently, these other components are imported automatically into the current model.
To import from a model:
The Pathway Editor can display, modify, and add metadata, or information about a CellML model, according to the CellML Metadata 1.0 specification. The metadata is contained within "Description" elements. Any CellML element may be described by one or more Description elements.
CellML model files may contain other kinds of metadata than described in the CellML Metadata 1.0 specification. Such metadata is not displayed.The Metadata Manager dialog is displayed when the "Metadata manager" menu item on the CellML menu is selected.
If a BioPAX, CellML, or SBML model has been created, and a corresponding entity (physical entity participant, variable, or species) in one of these models has been associated with a node, annotations in these models are readily added. This is achieved by downloading a compound with its database references. The database references automatically become associated with the entity.
Basic SBML, BioPAX, and CellML models may be created from pathways laid out on the drawing panel. Existing compound database annotations (references) are transferred into the resulting models. After creating models, names may be modified and model type-specific details such as mathematical formulas may be added.
Windows operating systems may update themselves automatically. In so doing, Internet Explorer sometimes loses track of the program that is used to open .jnlp files. These files are read by browsers when the user clicks on hyperlinks to the files. The browser passes .jnlp files to Java Web Start for downloading and processing of programs specified in the .jnlp file.
The following steps will ensure that Internet Explorer will remember to use Java Web Start on .jnlp files.
As a first step, you might try installing Java using your preferred browser, following the instructions for Internet Explorer according to the previous section.
Alternatively, or in addition to, a new installation of Java, a browser option can be set to use a different installation. This may be required when a Web Start program requires a more recent version of Java. The following instructions refer to Mozilla Firefox version 11.0. Other versions and browsers should have similar instructions.