BioNetGen language format

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.

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

¹ 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})