Pathway Logic Assistant Reference Guide
The Pathway Logic Assistant (PLA) allows you to explore a Pathway logic knowledge base (KB) and to query models derived from such a KB. One interacts with PLA via two main types of window: the knowledge base manager (KBManager, unique to a session) and graph viewer windows (zero or more per session). A model can be derived using a predefined initial state (called a dish), or by interactively creating an initial state using the dish editor. The resulting model is represented as a Petri net whose transitions are the KB rules reachable from the initial state. The Petri net graph is displayed in the PLA viewer which the user can use to browse the network and query the model for subnets and pathways. Using PLA you can also incrementally explore the KB network by specifying a set of rules or occurrences from which to start and then selectively adding connected rules and occurrences. In addition, graphs (i.e. the underlying networks) that have been constructed by querying models or exploring can be compared. A graph viewer has a mode determined by the interface provided by the underlying network: Pnet for networks generated from a dish (models) and subnets resulting from queries; Xnet for networks generated by exploring; and Cnet for comparison nets. The reason for modes is that the meaningful operations/interactions depend on the mode (how the network was generated).
KBManager Window
Creating a Model
Dish Editor
Exploring a Network
From Occs
From Rules
PLA Graph Viewer
Navigation
Information
Menus
ToolBar
Mode Specific Functionality
Pnet
Xnet
Cnet
KBManager Window
When PLA starts up it loads a knowledge base (KB) and a knowledge base manager window (title: PLA KBManager) appears in the upper left corner of your screen. The KBManager displays a list of available knowledge bases (rule sets). Initially, there is just one KB. The currently selected KB highlighted in blue.
The KBManager has three buttons on the right. Use one of these buttons to open a PLA viewer window displaying the corresponding network graph.
- Select Dish --- create a model to study.
- Explore(Occs) --- explore the KB starting with occurrences chosen from a list of known occurrences.
- Explore(Rules) --- explore the KB starting with rules chosen from a list of rules in the KB.
Creating a Model
To create a model press the "Select Dish" button. You will be offered two choices, "edit" and "predefined", from a drop down menu. If you select "predefined", a list of available dishes will be displayed. Click on one of the listed dishes to select it. If you select edit, a dish editor dialog will open. Use this to specify a dish (see below). In either case, once you have specified a dish PLA will display the resulting model (a Pnet) in a graph viewer window in Pnet mode. You can use the viewer to browse and analyze the model (see the section on the graph viewer).
If you select "Edit", a dish editor dialogue will appear which you can use to create an initial state (aka dish). The dish editor has two columns: the left column (labeled Dish) lists the set of occurrences currently in your dish; the right column (labeled Scope) lists the set of occurrences from which you can choose. The occurrence lists are grouped into sublist according to the first character of the occurrence name. As shown is the leftmost dish editor screen shot below, initially the Dish column is empty and the Scope column contains all the occurrences that appear in the KB.
|
Dish Editor: before editing |
Dish Editor with Egf-Out, EgfR-CLm, Gab1-CLc, Gab2-CLc, and Sos1-CLc checked |
Dish Editor after pressing the "Add" button (Egf-Out, EgfR-CLm, Gab1-CLc, and Gab2-CLc) |
You can add occurrences to the dish by selecting them from the scope (checking the associated box) and pressing the "Add" button at the bottom of the Scope column. Dually, you can remove occurrences from the dish by checking the associated boxes and pressing the "Delete" button at the bottom of the Dish column. In more detail click on the triangle to the left of a sublist to expose the sublist items for selection. If you click on the folder icon, you will be given the open to select all items in the list, none of the items, or reverse the current selection. The center dish editor screen shot above shows a dish dialog after checking Egf-Out, EgfR-CLm, Gab1-CLc, Gab2-CLc, and Sos1-CLc. The rightmost dish editor screen shot above shows the result of pressing the "Add" button. Notice that the selected occurrences have disappeared from the Scope and non-empty sublists in the E,G, and S categories have appeared in the Dish.
The pair of buttons at the top of the Dish and Scope lists control the grouping of occurrences into sublists (categorization). The "Lexical" button selects lexical grouping according to the first character (the initial setting). The "Spatial" button groups occurrences according to lacation. (Try it.)
You can also select an occurrence by typing the first few characters. Matching occurrences will appear in a drop down list from which to select.
Using the Dish menu at the top of the Dish column you can save your
dish in a file, load a saved dish from a file, or load a predefined dish. In
the case of loading or saving a dish, a file chooser dialog will appear
to allow you specify the file name.
In the case of a predefined dish, you will be shown a list of
available dishes to choose from. Thus, using the dish editor you can define
variations on a basic dish, for example adding different ligands, or combine
dishes. At any point you can exit the dish Editor by
pressing the "Dismiss" button at the bottom of the window. Once you have created
a dish/initial state you want to study,
press the "OK" button at the bottom of the window.
An input dialog will appear asking for a name for the new dish. Type in a name
(please no spaces or other non-printing characters)
and press
Exploration of a KB can be initialized by selecting
a starting set of occurrences or a starting set of rules.
To explore a KB network starting with a given set of occurrences
click Explore(Occs). A selection dialog (titled Select occs and direction to
explore from < graph id >) will appear. The occurrences to select from
(all that appear connected to a rule in the KB) are grouped according to
the first letter of their label.
The leftmost selection dialog screen shot below shows the initial
dialog state. Click on the triangle pointing
to a letter to expose the occurrences in that group. For example
the E group of the SmallKB contains 4 occurrences:
An occurrence can be selected for exploration up, down, or both.
The first click on an occurrence selects it for both. Repeated
clicking cycles through the options: both, up, down, (not selected).
The rightmost selection dialog screen shot below shows the result
of selecting EgfR-CLm for both.
Explore Occurrences |
Explore Occurrences |
A list of selected occurrences appears in the pane at the bottom of the dialog, for convenience. Clicking on the icon associated to the letter allows you to select all occurrences in that group, none of them, or to invert the current selection.
At any point, pressing the "Dismiss" button will cancel the Explore request. When you are finished choosing occurrences and their exploration directions, press the "OK" button on the bottom right. Shortly an Xnet graph view window (Xnet mode) will appear with the graph of the network formed from the selected occurrences and associated rules. If the "up" option is specified for an occurrence, the associated rules are those rules whose output includes that occurrence (upstream rules). If the "down" option is specified for an occurrence, the associated rules are those rules whose input (reactants and modifiers) includes that occurrence (downstream rules). The "both" option corresponds to the union of the up and down rules. Note that when a rule is included in a network, all of its connected occurrences are included as well.
To explore a KB network starting with a given set of rules press Explore(Rules). A selection dialog (titled: Select rules to add to < graph id >>) will appear. The rules to select from (all rules in the KB) are grouped according to the first character their label. Rule selection works like occurrence selection except there is no direction option. At any time you may press the "Dismiss" button to exit the selection dialog without submitting an Explore request. When you are finished selecting rules, press the "OK" button on the bottom right. Shortly an Xnet graph view window (Xnet mode) will appear with the graph of the network containing the selected rules.
PLA Graph Viewer
Screen shot of the Hras dish graph
- Title: the text at the very top of the window. It tells you the name and type of the graph
- Subtitle: lists the parameters used to generate a subnet or path
- Menubar: the top row of buttons
- Toolbar: the second row of buttons
- Graph and navigation panels: left and right under the toolbar
- Information panel: bottom right. The information panel has three tabs: Find, Selections, and Context. By default the Find tab is open. The other tabs can be opened (if available) by clicking on the tab name.
The buttons in the Menubar and Toolbar mainly provide means to query the graph and modify the rendering. The navigation panel displays a thumb nail sketch of the full graph with a red rectangle indicating the part of the graph visible in the graph panel. The SouthEast panel has Find/Context/Selection tabs for browsing, displaying information, and query parameter setting.
In the graph panel, the network of reactions is displayed as a graph with two kinds of node, occurrence and rule. Ovals represent occurrences---proteins or chemicals in a specific state and location. For example the oval labelled EgfR-act-CLm represents an Efg receptor (also known as ErBb1) that is activated (-act) and located in the cell membrane (-CLm). We use the following abbreviations here.
Locations Out --- outside the cell, the medium or supernatant CLm --- in/across the cell membrane CLi --- attached to the inside of the cell membrane CLc --- in the cytoplasm Modifications Yphos --- phosphorylated on a tyrosine act --- activated reloc --- relocated ubiq --- ubiquitinated GDP --- loaded with Guanosine diphosphate (GDP) GTP --- loaded with Guanosine triphosphate (GTP)
Darker colored ovals represent occurrences in the initial state (the selected dish when the network is generated by selected a dish). Lighter colored ovals represent potenial states/locations of these components. Rectangles represent reaction rules. The label in a reactangle is its (abbreviated) identifier in the knowledge base. Solid arrows from an occurrence oval to a rule indicate that the occurrence is a reactant (rule input). Solid arrows from a rule to an occurrence oval indicate that the occurrence is a product (rule output). Dashed arrows from an occurrence oval to a rule indication that the occurrence is a modifier/enzyme/catalyst. It is necessary for the reaction to take place but is not changed by the reaction.
There are three types of graph---Pnet, Xnet, and Cnet---depending on how the graph was generated:
- Pnet graphs are graphs of models, and subnets derived by queries. They have an initial state.
- Xnet graphs are graphs generated by exploration
- Cnet graphs are generated by graph comparison.
The graph viewer mode (Pnet, Xnet, or Cnet) reflects the graph type. The available queries/buttons in the menu and tool bars and the information pane depend on the graph type, according to what is meaningful for the type.
There are a number of keyboard short cuts for those who prefer typing
to pointing and clicking. (A keyboard shortcut is a combination of keys
that when pressed has the same effect as some sequence of mouse moves,
for example selecting a menu item or toolbar function.
See #
We begin by describing the network-type independent features.
Click on a name to select it (the name will be highlited). Now there are three
ways to bring the selected item into view in the graph panel.
In all three cases the graph view will be centered on the selected item
(occurrence or rule) and the border of item will become red to make it
easy to see. In the case of pressing Click, the Context menu for the
selected item will be displayed in the informantion panel (see #nodeInfo).
Press one of the buttons to perform the indicated reaction.
You can also double click on the arrow to directly go to the other end
(center on the other end).
You can obtain general information about the graph, a node, or an edge
in the Context Menu tab of the Information pane.
There are four mode independent menus: File, Compare, Graph, and Window.
They appear in that order (left to right) just under the title bar.
The File Menu contains the following items
The Compare Menu provides access to the graph comparison functionality. The current
graph can be compared to any visible graph (other than its self) by selecting
(clicking on) this menu and choosing one of the graphs presented. When you
select the Compare menu, the visible graph names are displayed using the window
hierarchy organization (see #WindowMenu), allowing you to readily see the
relationships amongst the available graphs. The current graph will be grey (non
selectable).
Once you have selected a "compare to" graph, the comparison graph (a Cnet) will
be displayed in a new window (CNet mode). The comparison graph is simply the
union of the nodes of the two graphs being compared. Nodes in both graphs a
colored pink, nodes in the requesting graph are colored blue/lavendar, and
nodes in the compare to graph are cyan (blue-green).
Note that comparing a graph to its parent is visually similar to
viewing the graph in context, although comparing creates a new
graph that you can manipulate, while viewing in context just draws
it differently.
The Window Menu controls the organization and layout of windows
on your screen.
The windows of a PLA session are organized in a tree with the KB Manager (KBMW)
window at the root. Children of the KBM are graph view windows created using
the Select Dish, Explore(Occs), and Explore(Rules) buttons. Children of a Pnet
graph are subnets formed by FindPath or Subnet queries or by exploration
starting from the Pnet (see the
pnet toolbar discussion.) The graph of child window is a
subgraph of the graph of the parent window. Explore nets (Xnets) have no
children, as they can be modified both by adding and deleting nodes.
There are four items in the window menu.
Every PLA graph view window has at least the following buttons
in its tool bar (right to left)
Color Key:
The color of a graph node is used to convey status information.
Place the mouse pointer over a color rectangle and a little text
box (tooltip) will appear with a brief description of the meaning
of the color. The colors used and their meaning depends on the
mode. When the graph is rendered "InContext" (see #InContext/DotLayout)
context nodes are white. Mode specific colors are explained
in the discussion of each mode.
Zoomies:
There are four zoomies (magnifying glass icons) each labeled with
an indicator of the functionality. The zoomies can be used to resize
the graph panel viesw of the graph.
InContext/DotLayout:
This button only appears if the graph has a visible parent,
for example if it is a subnet or path within some other graph,
or an exploration graph initiated from a Pnet graph rather than a KB.
Pressing the button causes the graph to be rendered in the
context of its (nearest parent). Thus the graph nodes will be appear
in their position in the parent graph. Parent nodes (called context nodes),
will be colored white. The subject graph nodes will not change color.
The button will now be dark and labeled DotLayout. If you press it again
the graph will be displayed in its original form.
ToKB:
This button allows you to turn the rule network underlying the graph
into a knowledge base. When you press the button an input dialog will
appear asking for a name for the new KB. Type in a name and press
A Pnet graph differs from other types of graph by having a subset
of the occurrences marked as initial, corresponding to the initial
state specified by the dish from which the net is derived. Thus it
serves as a model of some aspect of a cell, its behavior can be studied
by asking for subnets or pathways satisfying certain simple conditions:
The graph state includes a set of occurrences marked as goals, a set of
occurrences marked as avoids, and a set of rules marked as hidden. In a graph
generated by specifying a dish, each of these sets is initially empty. In a
graph resulting from a query the initial set of goals is that of the query
generating the graph. The other two sets are necessarily initially empty. Nodes
can be added to or removed from the query sets either using the selections tab
of the information pane, or by using the check boxes that appear in the context
menu for a node (this appears when you click on a node).
A pathway is a set of rules (and connected occurrences) together with a set of
marked occurrences that represents an execution (see #models.petrinet). That
is, there is at least one rule with all of its inputs in the initial set.
Firing these rules removes each rules reactants from the marked set and adds
each rules products. Repeating this process all of the rules will fire.
Given a non empty set of goals, and possibly empty avoids and hidden sets, a
pathway satisfying the corresponding conditions is a subnet that contains all
of the occurrences in the goals set, none of the occurrences in the avoids set,
and none of the hidden rules. Furthermore, when the pathway is executed
the marked occurrences at the end include goal occurrences. This corresponds to
the modeled cell evolving to a state in which the components of a goal
occurrences have the state and location indicated by the occurrence. Note that
there may be no pathways satisfying a given set of conditions, or there may be
just one, or there may be several.
Given goals, avoids, and hidden sets, with goals non-empty, a minimal pathway
is a pathway satisfying these conditions in which removing any rule will
prevent execution from reaching one or more of the goals. The relevant subnet
for these conditions is a subnet that contains all of the minimal pathways. As
for pathways it contains all occurrences in the goals set, none of the
occurrences in the avoids set, and none of the hidden rules. The relevant
subnet for the case when the goals set is emtpy is obtained by removing all
hidden rules and all rules connected to an occurrence in the avoids set.
In addition to asking for pathways and subnets, exploration of the underlying
rule network can be initiated from a Pnet using the Explore button in the
toolbar.
Suppose you choose Set Goals. The information pane will contain
a list of all occurrences in the graph, each with a check box.
Check those occurrences that you wish to add to the graph's goal set,
uncheck any previously checked ones to remove them.
There is a button labeled In Bulk at the top of the selection pane. Use this
button load a file containing a list of goals. A file chooser menu will appear
for you to specify the file. The file should be a plain text file containing
names (full labels) of occurrences, one per line. This is especially useful
if you want to specify a large number of goals, or to be able to use
the same goal set at different times.
The buttons labeled All On/Off check/uncheck all occurrences.
Setting Avoids and and Hiding Rules works in a similar manner.
If there is no pathway (the goals are not achievable under the specified
conditions) a small warning message window will appear. Its title is "Lola
failed" and the message is "return code 1".
Exploration in carried out in the context of a scope net, the rules of the KB
or Pnet from which exploration was initiated. The Xnet specific operations
allow you to add and remove nodes from the graph, either by following
connections up and/or down stream from some or all occurences, picking specific
rules or occurrences to add to the graph, or hiding rules. The rules up stream
from an occurrence are those rules in the scope net that have arrows from the
rule to the occurrence (the occurrence appears in the rules output). The rules
down stream from an occurrence are those that have arrows from the occurrence
to the rule (the occurrence appears in the rules input or is a modifier).
Exploring up/down stream from a set of occurrences adds all (non-hidden) rules
up/down stream of one of those occurrences along with any additional
occurrences connected to the rule that are not already present.
Hiding a rule marks it unavailable for exploration, and if the rule is present
in the Xnet graph it is removed along with all occurrences connected to it and
no other rule. Unhiding a rule makes it available for exploration, but does not
add it to the graph.
A specific occurrence is added along with its up and/or down stream rules,
according the mode of exploration. A specific rule is added with all of its
connected occurrences that are not already present.
Exploration is carried out using the Xnet specific toolbar buttons
as explained below.
New Frame Check Box:
Normally explore operations modify the graph and redisplay the modified graph
in the same window. This avoids window clutter, but if you reach a state you
want to save, for roll back or alternative exploration paths, check the box
labelled New Fram and the next operation will create a new Xnet graph and
display it in a new window. The box is unchecked initially, and is reset to
unchecked after an operation.
Up/Down buttons:
If you press the Up/Down button in the toolbar, the
has the effect of selecting all occurrences in the graph for up/down stream
exploration. The graph will be updated and redisplayed.
By default just one level is explored. If you change the number
in the text box to the right of the Down button, say to 2, then
two levels of connect will be explored. The same effect can be
achieved by pressing the Up/Down button twice. Similarly for any
number.
Explore:
Pressing the Explore button provides a menu of operations to choose from
Context Menu:
(Click on a node and its context menu shows in the information
pane)
In an Xnet the context menu can be used to select occurrences to to explore or
rules to hide. The context menu for an occurrence node
has three check boxes in
addition to the information buttons: explore Ua&Down, explore upstream, and
explore down stream.
Checking one of the boxes (clicking the box) selects the occurrence for
exploration with the indicated option.
Unchecking (clicking again) deselects the
occurrence from the goal set.
The context menu for a rule has one check box: Hide rule. Checking
this box selects the rule to be hidden. Unchecking deselects the rule.
Note that selected nodes are colored yellow.
exploreSelected:
If you press the exploreSelected button in the toolbar selected rules will be
hidden, then the selected occurrences will be explored in the specified
direction(s), and the modified graph will be displayed.
Note: If no occurrences or rules are selected, or if the
occurrences selected have no unexplored connections, the
action simply redisplays the unchanged graph.
Cnet graphs have no specific functionality.
The only mode specific aspect of a Cnet graph is the color key
Information (Context Menu Tab)
PLA KB Manager
Exploring in SmallKB
InitialNet for rasDish
Exploring in InitialNet for rasDish
Pathnet in rasDish
Figures
rasNetInvis.png rasDish Pnet with redundant edges invisible
rasNetRemoved.png rasDish Pnet with redundant edges removed
Figures
ExploreRasRule.png The Xnet for rule 6
ExploreSosUp.png With Sos1-reloc selected for upstream exploration
ExploredUp.png After pressing exploreSelected
Color Key