Difference between revisions of "BioNetGen language format"

Revision as of 13:06, 25 August 2015

File format title

BioNetGen language format (*.bngl)

Element type

diagram

Plugin

biouml.plugins.bionetgen (Support for BioNetGen)

BioNetGen (*.bngl) format

BioNetGen is a set of software tools for rule-based modeling. Rule-based modeling involves the representation of molecules as structured objects and molecular interactions as rules for transforming the attributes of these objects. The approach is notable in that it allows one to systematically incorporate site-specific details about protein-protein interactions into a model for for the dynamics of a signal-transduction system, but the method has other applications as well, such as following the fates of individual carbon atoms in metabolic reactions. The consequences of protein-protein interactions are difficult to specify and track with a conventional modeling approach because of the large number of protein phosphoforms and protein complexes that these interactions potentially generate.

A BioNetGen input file contains the information required to specify a model, including definitions of molecules, rules for molecular interactions, and model outputs, which are called "observables". Model definition is delimited by 'begin model' and 'end model' tags. All of model elements are specified in blocks delimited by 'begin block_name' and 'end block_name' tags as indicated in example below. The five block types are 'parameters', 'species' (or 'seed species'), 'reactions', 'observables', 'molecule types'. Other simulation parameters follow the model specification. All text following a '#' character on a line is treated as a comment, and comments may appear anywhere in an input file.

The following is a list of of general steps involved in construction a model with the relevant section of the input file:

1. (parameters) Define the parameters that govern the dynamics of the system (rate constants, the values for initial concentration of species in the biological system).
2. (molecule types) Define molecules, including components and allowed component states. (optional)
3. (species) Define the initial state of system (initial species and their concentration).
4. (reactions) Define rules that describe how molecules interact.
5. (observables) Define model outputs, which are functions of concentrations of species having particular attributes.

They may appear in any order, although, because of the dependencies the above order is the most logical. The model specification is followed by a set of commands (actions) that operate on the model. The most important are

1. generate_network,
2. simulate (simulate_ode, simulate_ssa).

Syntax and parameters for BioNetGen actions. Scalar types are int, 0/1 (a boolean), string and float. Multi-valued parameters may be either arrays or hashes.

¹ General syntax is action({scal⇒val,array⇒[x1,x2,…],hash⇒{key1⇒val1,key2⇒val2,…},…});

² Are irrelevant for BioNetGen-plugin.

³ These parameters only apply to simulate_ode (or to simulate with method⇒"ode").

⁴ Is necessary only in 'simulation' action.

For more information, see the official website of the BioNetGen and BioNetGen-plugin wiki page.

Example:

# Comments in BNGL are always preceded with a pound (#) character. 
# so that any text that follows a pound character is ignored. 
# The model file below is commented to help you
# understand the main parts of a BNGL file.  Note that some 
# commands at the end of the model file that allow you to 
# run the model with different simulators are commented out.
# To use these other options, simply remove the pound
# character before the command.

begin model

# The first part of a BNGL file is the parameters
# block, where you can define the rates
# of equations or the starting numbers of
# any of the molecular species.
begin parameters
     kon   10
     koff   5
     kcat   0.7
     dephos   0.5
end parameters

# Next, we define the set of molecule types in the system.  This is a declaration only, so
# we don't specify how many of each molecules there are, and we have to provide a list
# of all possible state values for each component of each molecule with a tilda (~)
# character.
begin molecule types
     X(y,p~0~1)
     Y(x)
end molecule types

# Here is where we declare the starting molecules
# in our simulation.  Each component
# must be assigned a single state value, and
# we have to provide how many of each
# molecule exists in the system.
# The number of starting molecules can also be
# specified with one of the parameters defined earlier
begin species
     X(y,p~0)     5000
     X(y,p~1)     0
     Y(x)         500
end species

# This is a very simple system indeed. 
# The only rules that are defined
# tell us that X can bind Y if X is 
# dephosphorylated.  Then the XY complex
# can either disassociate, or a
# phosphorylation reaction can occur.
# Finally, X will dephosphorylate 
# regardless of whether or not it is bound
# to Y, although for these rules, it will
# always be unbound to Y if it is phosphorylated.
# Here are the rule definitions:
begin reaction rules
     X(y,p~0)  +  Y(x)  ->  X(y!1,p~0).Y(x!1)    kon
     X(y!1,p~0).Y(x!1)  ->  X(y,p~0)  +  Y(x)    koff
     X(y!1,p~0).Y(x!1)  ->  X(y,p~1)  +  Y(x)    kcat

     X(y,p~1)  ->  X(y,p~0)                    dephos
end reaction rules

# Observables allow us to define simulation output. 
# Here we have declared a number
# of Molecules observables with the given name and pattern. 
# If you look at the output
# .gdat files that are generated from simulations of this model,
# you will see that they
# each have a count for every simulation time.
begin observables
     Molecules    X_free           X(p~0,y)
     Molecules    X_p_total        X(p~1,y!?)
     Molecules    Xp_free          X(p~1,y)
     Molecules    XY               X(y!1).Y(x!1)
     Molecules    Ytotal           Y
     Molecules    Xtotal           X
end observables

end model

# COMMAND FOR RUNNING OR PROCESSING THIS BNGL FILE

generate_network({overwrite=>1})

# Then we can call the simulate_ode or simulate_ssa methods to run the model file, where
# "t_end" is the simulation time, "n_steps" is the number of steps, and "suffix" is
# the filename ending.

simulate({method=>"ode",t_end=>100,n_steps=>50})
# simulate({method=>"ssa",suffix=>ssa,t_end=>100,n_steps=>50})