Visualization

From BioNetWiki

Jump to: navigation, search

Welcome to visualization of rule-based models. You will need BioNetGen 2.2.6 or higher to use these tools. It is recommended to use the latest version of these tools from github, which will be documented on this page.

Contents

Notes on Usage

Deploying visualization commands

Visualization tools can be deployed in two ways.

  • In ACTION MODE, the tools are accessed using the visualize() action from within a BNGL file. If you're using the latest version of these tools, multiple visualize() actions can be called from the same file. This is useful if you are visualizing alongside editing the model. After including these actions, execute the BNGL file from the command line as usual: perl BNGPATH\BNG2.pl model.bngl.
  • In SCRIPT MODE mode, the tools are accessed from the command line, by calling the Perl script visualize.pl, which can be found under BNGPATH\Perl2\Visualization\. This is useful for those comfortable with command line input, as well as to try different combinations of input options or embed in batch scripts.
Displaying the help menu
  • ACTION MODE: visualize({help=>1})
  • SCRIPT MODE: ./visualize.pl --help
Visualizing the output

The output files are in GML format and are best viewed and laid out using yEd Graph Editor. After importing in yEd, to take a quick look at the graph, do the following:

  • Tools->Fit Node to Label,
  • Layout->One-Click Layout or Layout->Organic.

Experiment with automated node layouts and edge layouts to get the best diagram. Remember, you can always re-layout the edges after manually moving the nodes. Use the "Dock" feature on many yEd dialogs to keep repeated actions easily accessible.

Rulebender support

Rulebender does not officially support the new visualization tools yet. However, you can still include and execute visualize() actions, ignoring any errors that pop up. The GMLs are within the default output folder that is created every time a model is executed. Currently, option files cannot be provided to visualize() actions in Rulebender.

Naming rules

Before trying to visualize a model, it is best to ensure that rules are properly named, i.e. every rule is specified as:

 RuleName: Reactants [<]-> Products RateConstants 

This ensures that rules are uniquely identifiable on regulatory graph visualizations. Names of reverse rules are generated automatically.

Unsupported

Currently, we do not support visualization of cBNGL models and rules with DeleteSpecies operations, transport operations and local functions.

Example files

Download the example files here. The file fceri.bngl contains the model and the specified visualization actions. The options files opts0*.txt specify additional options for the visualization actions that will be used here. Unless you are using the latest github version, comment out all actions and uncomment them one at a time before executing the BNGL. The folder named output should contain examples of the output files you should be able to generate if you used the commands specified here.

Rule Visualization

Syntax
ACTION MODE: visualize({type=>"ruleviz_pattern"/"ruleviz_operation",each=>0/1,suffix=>"optionalstring"})
SCRIPT MODE: perl visualize.pl --bngl model.bngl --type [ruleviz_pattern|ruleviz_operation] [--each] [--suffix optionalstring]
  • ruleviz_pattern is used for direct rule visualization.
  • ruleviz_operation is used for compact rule visualization.
  • each=>1 displays each rule in a separate GML file (each=>0 is default).
  • suffix=>"optionalstring" suffixes _optionalstring to the filename.

New Features v2.3

  • conventional can be used instead of ruleviz_pattern
  • compact can be used instead of ruleviz_operation
Direct rule visualization
In direct rule visualization, the patterns of the rule are converted to site graphs and arrows are used to represent input/output relations. The full set of rule diagrams was generated from fceri_ji.bngl by the command
visualize({type=>"ruleviz_pattern"})

We show rules R6 and R7 after layout:

Compact rule visualization
In compact rule visualization, both reactants and products are merged into a single site graph. Graph operation nodes show the changes implemented by the rule. The full set of rule diagrams was generated from fceri_ji.bngl by the command
visualize({type=>"ruleviz_operation"})

We show rules R6 and R7 after layout:

Contact Map

The contact map shows one instance each of every molecule type, component, internal state and bond in the model.
Syntax
ACTION MODE: visualize({type=>"contactmap",suffix=>"optionalstring"})
SCRIPT MODE: perl visualize.pl --bngl model.bngl --type contactmap [--suffix optionalstring]
  • suffix=>"optionalstring" suffixes _optionalstring to the filename.

Rule-derived Regulatory Graph

Syntax
ACTION MODE: visualize({type=>"regulatory",each=>0/1,
                       background=>0/1,textonly=>1,
                       groups=>0/1,collapse=>0/1,opts=>["x.txt","y.txt"],
                       filter=>0/1,level=>INT,
                       suffix=>"optionalstring"})
SCRIPT MODE: perl visualize.pl --bngl model.bngl --type contactmap [--each] 
                       [--background] [--textonly] 
                       [--groups [--collapse]] [--opts x.txt] [--opts y.txt] 
                       [--filter [--level INT]]
                       [--suffix optionalstring]http://bionetgen.org/index.php?title=Special:Userlogout&returnto=Visualization
  • type=>"regulatory" generates the regulatory graph.
  • each=>1 outputs each rule in a separate GML file (default: each=>0).
  • background=>1 ensures all nodes are shown, i.e. no background removal is performed (default: background=>0).
  • textonly=>1 outputs a text file describing nodes and edges on the graph, which is useful to make options files (default: textonly=>0).
  • groups=>1 turns on automated rule grouping (default: groups=>0).
  • collapse=>1 collapses groups of nodes to single nodes (default: collapse=>0).
  • opts=>["...","..."] is used to specify options files that modify background, grouping and filtering algorithms.
  • filter=>1 turns on filtering the graph, which can be used to look at neighborhoods of specific nodes (default filter=>0).
  • level=>INT decides how many levels deep the graph should be explored during the filtering process (default level=>1).
  • suffix=>"optionalstring" appends suffix _optionalstring to the output filename.

New Features v2.3

  • Rule grouping is stricter and takes context edges into consideration. Rule grouping without considering context can be performed using doNotUseContextWhenGrouping=>1.
  • doNotCollapseEdges=>1 when used with collapse=>1 leaves multiple edges of the same type intact during collapsing regulatory graph.
  • Removing context from the reactants to a rule group removeReactantContext=>1. This step is performed after grouping.
  • Make inhibition edges from reactant edges makeInhibitionEdges=>1. The specific reactant edges to be converted are specified as a list of RuleName:AtomicPattern elements within begin inhibition and end inhibition in the options file. An error will be thrown if the specified reactant edge does not exist.
  • Rule motifs. Experimental feature. compressRuleMotifs=>1.
Individual Rules
The rule-derived regulatory graph transforms a rule specified using patterns to a set of bipartite relationships between the rule and atomic patterns. Atomic patterns are patterns identifying simple and atomic structural features such as binding sites, bonds, internal states and molecule types. The decomposition of patterns to atomic patterns necessarily results in a loss of information: the specific configuration of sites cannot be recovered. However, the regulatory graph presents a picture more akin to regulation and signal flow.

The following graphs show regulatory graphs of rules R6 and R7 generated using the following action:

visualize({type=>"regulatory",each=>1,background=>1})

We shall see in #Removing background section why background=>1 is necessary.

Model regulatory graph
The regulatory graph of individual rules can be aggregated into a regulatory graph of the model. The full regulatory graph of the fceri_ji.bngl model was generated using the action:
visualize({type=>"regulatory",background=>1,suffix=>"a"})

It is useful to generate a text-only version of the full graph, which can be used to create option files for subsequent analysis, using the action:

visualize({type=>"regulatory",background=>1,textonly=>1})

Note that text-only is not supported for any combination of options other than the one given above.

Removing background
Some atomic patterns are redundant on the regulatory graph. These typically include default states (such as unphosphorylated), and free binding sites. Depending on the order in which the rules are specified, BioNetGen guesses which atomic patterns are background and removes them when background=>0, which is also the default behavior. This is why generating the full graph of individual rules or the whole model in the previous sections required background=>1. We generated a graph with default background assignment and removal from fceri_ji.bngl using the action:
visualize({type=>"regulatory",suffix=>"b"})

This is equivalent to the action:

visualize({type=>"regulatory",background=>0,suffix=>"b"})

If you are not satisfied with the default algorithm, you can modify its choices by specifying one or more options files. You can specify both atomic patterns and rules that should be excluded or included in the background, overriding their default assignments. The format for the options file is as follows:

begin background
    begin include
         <whitespace-separated list of atomic patterns>
         <whitespace-separated list of rule names>
    end include

    begin exclude
         <whitespace-separated list of atomic patterns>
         <whitespace-separated list of rule names>
    end exclude
end background

Note that the include block specifies what is included in the background, ergo what will be removed when background=>0. Similarly, the exclude block specifies what is excluded from the background, ergo what will be displayed when background=>0.

To specify the atomic patterns and rule names such that BioNetGen would recognize them, it is useful to generate a text-only version of the full graph as shown in #Model regulatory graph, and then copy and paste the appropriate atomic patterns and rules from the generated text file into the options file.

For the fceri_ji.bngl model, we specified opts01.txt, where we included free binding sites and unphosphorylated states within the background and excluded bonds and phosphorylated states. The regulatory graph with the modified background assignment was generated using the following action:
visualize({type=>"regulatory",opts=>["opts01.txt"],suffix=>c})

Grouping
The automated rule grouping algorithm can automatically identify groups of rules on the graph with identical reaction centers, indicative of groups of contextual variants of some fundamental process. The algorithm does not identify groups of atomic patterns, but these can be specified in the options file using the following format:
begin classes
      begin classname1
            <whitespace-separated list of atomic patterns>
      end classname1

      begin classname2
            <whitespace-separated list of atomic patterns>
      end classname2
end classes

The grouping of atomic patterns is information that will be used by the rule-grouping algorithm. Two atomic patterns in the same group will be considered as "equal" and any rules with equivalent relationships to members of the same group will also be grouped together.

For the fceri_ji.bngl model, we specified groups of atomic patterns in opts02.txt. This options file can be provided in addition to the file opts02.txt, which specifies the background assignement. An example of such a group specified by the user is Rec_p which groups the phosphorylated states of the receptor phosphorylation sites Rec(b~pY) and Rec(g~pY). The regulatory graph with groups was generated with the action:

visualize({type=>"regulatory",groups=>1,opts=>["opts01.txt","opts02.txt"],suffix=>"d"})

Note how the rules implementing phosphorylation of the receptor are grouped together under RG1. This is a direct consequence of specifying Rec(b~pY) and Rec(g~pY) as grouped under Rec_p.

Collapsing
Collapsing reduces the regulatory graph by merging groups of nodes into single representative nodes. This coarse-grains the context relations, since individual members are not distinguishable anymore. However, the reduced graph is typically easier to comprehend, since it provides the overall regulatory picture and hides the details.

The collapsed regulatory graph of fceri_ji.bngl was generated using the following action:

visualize({type=>"regulatory",groups=>1,collapse=>1,opts=>["opts01.txt","opts02.txt"],suffix=>"e"})

Alternate Grouping Strategies
The grouping of atomic patterns is left to the user and creative grouping strategies can result in different diagrams that are optimal for different reasons. In the previous section, notice on the collapsed graph that the atomic patterns Lyn(U) and Lyn(SH2) were left ungrouped, as are the Syk phosphorylated states Syk(a~pY) and Syk(l~pY). This allows us to distinguish constitutive recruitment of Lyn to receptor (via Lyn(U)) versus activated recruitment of Lyn to receptor (via Lyn(SH2)) to receptor. Similarly, we are able to distinguish Syk phosphorylation on the activation loop (Syk(a~pY)) which is Syk-mediated and Syk phosphorylation on the linker region (Syk(l~pY)) which is Lyn-mediated.

In opts03.txt, we specify an additional group Rec_Lyn that includes both atomic patterns Lyn(U!1).Rec(b!1) and Lyn(SH2!1).Rec(b!1). When grouping and collapsing is performed including these options, the constitutive and activated recruitment cannot be distinguished on the resultant graph, but the feedback loop between activated recruitment and receptor phosphorylation is now routed through the generic recruitment group.

visualize({type=>"regulatory",groups=>1,collapse=>1,opts=>["opts01.txt","opts02.txt","opts03.txt"],suffix=>"f"})

In opts04.txt, we specify an additional group Syk_p that includes both atomic patterns Syk(a~pY) and Syk(l~pY). If we include these options, activation loop and linker region phosphorylation are grouped into a generic Syk phosphorylation group.
visualize({type=>"regulatory",groups=>1,collapse=>1,opts=>["opts01.txt","opts02.txt","opts03.txt","opts04.txt"],suffix=>"g"})

Filtering
Filtering can be used to look at subsets of the graph. The user has to specify a seed set of nodes and an integer number called the level. The algorithm identifies the subset of the regulatory graph in the vicinity of the seed nodes and the level determines how many edges away from the seed nodes the algorithm explores. The seed nodes are specified in the options file using the following format:
begin filter
      <whitespace-separated list of seed nodes>
end filter

To generate a graph that includes the immediate vicinity of rules R6 and R7, we specified them as the seed nodes in opts05.txt. Then, we generated the filtered regulatory graph using the action:

visualize({type=>"regulatory",filter=>1,level=>1,opts=>["opts01.txt","opts05.txt"]})

Gallery

All visualizations shown on this page, generated from fceri_ji.bngl.

Glossary

Personal tools