BioNetGen language format

From BioUML platform
Jump to: navigation, search
File format title
BioNetGen language format (*.bngl)
Element type
Type-Diagram-icon.png Diagram
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.

Action/parameter1 Type Description Default
generate_network Generate species and reactions through iterative application of rules to seed species
max_agg float Maximum number of molecules in one species 1e99
max_iter int Maximum number of iterations of rule application 100
max_stoich hash Maximum number of molecules of specified type in one species
overwrite2 0/1 Overwrite existing .net file 0
print_iter2 0/1 Print .net file after each iteration 0
prefix string Set basename of .net file to string basename of .bngl file
suffix string Append _string to basename of .net file
simulate_ode/simulate_ssa/simulate Simulation parameters for current model/network
t_end float End time for simulation 100
t_start float Start time for simulation 0
n_steps/n_output_steps int Number of times after t=0 at which to report concentrations/observables [t_end−t_start]
sample_times array Times at which to report concentrations/observables (supersedes t_end, n_steps)
netfile2 string Name of .net file used for simulation
atol3 float Absolute error tolerance for ODE's 1e−08
rtol3 float Relative error tolerance for ODE's 1e−08
steady_state2,3 0/1 Perform steady state check on species concentrations 0
sparse2,3 0/1 Use sparse Jacobian / iterative solver 0
method4 string Specify type of simulation (ode/ssa) required

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

2 Are irrelevant for BioNetGen-plugin.

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

4 Is necessary only in 'simulation' action.

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


# 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
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



# 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=>"ssa",suffix=>ssa,t_end=>100,n_steps=>50})
Personal tools

BioUML platform
Analysis & Workflows
Collaborative research
Virtual biology