Bionessie

User Manual


 BRC


[Introduction] [Model Construction] [Model Simulation] [Parameter Scans] [Model Fitting] [Sensitivity Analysis] [Bibliography]

Introduction

BioNessie is an integrated software platform for the composition, simulation and analysis of biochemical networks which is being developed by the Systems Biology team at the Bioinformatics Research Centre as a part of a large DTI funded project BPS: A Software Tool for the Simulation and Analysis of Biochemical Networks. It simulates the kinetics of models of biochemical networks and provides users with functions of parameter scans, model fitting and sensitivity analysis. BioNessie is currently being integrated with a number of web services which will allow advanced analysis to be performed on a computational cluster or GRID.

This document is a step-by-step guide to use features of BioNessie to construct, simulate and analyse models of biochemical pathways. The first two sections cover essential steps for the construction and simlation of biochemical models in BioNessie, followed by an explanation of the use of the three advanced functions for pathways analysis.

[Top]

Model Construction

There are two ways of contructing models in BioNessie: creating a model from scratch and creating a model upon an existing model. For the latter, refer to the section of how to upload models to BioNessie. Here below lists a procedure to follow for constructing models from scratch.

Step1: Model Settings

  • Once you start BioNessie, the graphical interface appears as a window containing a tree-structured file on the left and a menu bar on the top along with several functional icons located below. There are five folders in the tree that you will work with quite often: models, fitting, paramscan, sens and simulations, which corresponds to each of the features thatBioNessie holds: model construction, model fitting, parameter scans, sensitivity analysis and simulation, respectively. The command Kinetic Law Creator at the far end of the icon bar is used to create user-defined kinetic laws which will be explained later.
  • You will have to create a new project first before creating a SBML model. To do this, select File->New Project. In the dialog popped up, click Next to activate the page where you can assign a name and define a path for your project. Click Finish to exit project settings. You will find that your project has been added into the tree.
  • Now you are ready to setup a SBML model under the project that you are going to work with. To do this, click on the tree node of your newly created project, right click on the models folder shown below and follow New->File/Folder to activate the setting dialog. Choose the name of your project, select Other from the left list box and SBML Template from the right, and click Next to exit the page. Give an expressive name to the model, select the folder to save it and then click Next. Accept the defaults on the last page and click Finish to complete the model settings. You can see that the right side of the window is now characterised with a welcoming panel, which contains text boxes and commands: Species, Parameters, UnitDefinitions, Reactions and Compartments. The use of these commands will be explained in the rest of this section.
  • To confirm that a new SBML model has been successfully created for your project, go to the tree file and open the Models folder. You will see that your SBML model is right there.

Step 2: Compartment Definition

  • Click Compartments tag on the top of the panel. Click New Compartment button in bottom right corner, and give a name to the new compartment in the dialog popped up (normally, we will use compartment1, compartment 2, etc. to name compartments). Click OK to exit the dialog.
  • Click the button Add to save the compartment just created. You can also edit or delete an existent compartment by clicking Delete or Change Commit button.
  • Go to the right side of the page to characterize the compartment, which includes defining size, spatial dimension and volume of the compartment BioNessie will use in the model. You will need to assign values to those parameters.

    NOTE: You can create several SBML models and a few of different compartments for your project, but you have to put everything of each model into the same compartment.

Step3: Species Definition

  • Click Species tag on the top of the panel. Click the button New Species in bottom right corner. Enter a name to the new species in the dialog popped up, and click OK to exit.
  • Click the button Add to save the species just added. You can also delete or edit an existent species by clicking Delete or Change Commit button.
  • Go to the right side of the page to characterize the newly added species, which includes defining initial concentration, initial amount and charge. You will need to assign values to those parameters that BioNessie will use in the model. The number of these attributes needed to be specified differs in problems of interest. Normally, we just need to give names to species and assign values to initial concentrations.
  • Choose a compartment from Owner compartment and allocate it to species.

Step4: Parameter Definition

  • Click Parameters tag. Click the button New Parameter in bottom right corner. Give a name to this newly defined parameter in the dialog popped up, and click OK to exit.
  • Click the button Add to save the parameter just added. You can also delete or edit an existent parameter by clicking Delete or Change Commit button.
  • Go to the right side of the page to characterize the newly added parameter. You will need to assign a value to this parameter that BioNessie will use in the model.

Step5: Reaction Input

  • Go to Reaction page by clicking on Reaction tag. Clicking on the button Add new Reaction brings out a new dialog, where you can define a chemical reaction that will be added to the SBML model. Give an expressive name to the reaction and write down the expression in the text box titled Reaction . You will see that BioNessie classifies all species involved in the reaction into reactants and products automatically.
  • Assign kinetic type to the reaction by clicking on Edit button , which will lead you to a new dialog titled "Edit Reaction's formula". To assign a predefined kinetic law, select a kinetic law from the box at the top and click Refresh to validate the operation. Click commit to save this assignment and exit the dialog. Click OK to complete the Reaction Input.

    How to create a user-defined kinetic type?

    You can also assign a user-defined kinetic law to a reaction. To do this, go through the following steps:

    • Click the button Kinetic Law Creator on the icon bar. Give a name and write down the formula of the kinetic law in the text box. Elements of the formula will be species and parmeters defined in the model, linked with mathematical operators (+, -, *, /). Notice that there are certain rules in representing species in the user-defined kinetic law: users can only use substrate, productamplifier to represent reactants, products and enzymes which are contained in the formula. Other names won't be accepted by BioNessie. There are no such constraints on parameters: users can give any names to parameters included in the formula. and
    • Check the box Reversible Reaction if the reaction for which you are going to assign the user-defined kinetic law is reversible, otherwise check the box Inreversible Reaction.
    • Leave other boxes unchecked and click Commit

[Top]

How to upload a SBML model to BioNessie?

To upload an existing model with BioNessie, follow File->Open File from main menu, identify the folder and select the SBML file to upload. You will need to activate the file first before using it. To do this, go to upper right corner of the panel and click the button Save to save the model under the BioNessie project that you are currently working with. You can see that the model has been added to the tree and displayed under the tree node correspondingly.

[Top]

Model Simulation

To simulate a SBML model, go to the tree, right click on the SBML model under the Models folder and select Simulate. This will lead you to the simulation panel. Go to bottom left corner of the panel, define the total time (starting time point is set as 0 by default; total time is the ending point of a time interval over which a simulation is performed) and steps (the number of time points sampled over the interval) that BioNessie will use for the simulation. You can get the simulation results by double-clicking on the folder simulation in the tree file. There are two ways of generating simulation results: you can either run a simulation first and then save results later, or run a simulation meanwhile having the results saved which can be achieved by clicking button Save Results before doing it.

In BioNessie, 60 and 120 are used as default values of the total time and time steps for a simulation, but you can assign any values to them to observe changes in plots: curves will be getting much smoother with an increase in the number of steps, but in cost of more computational time. You can also have a particular part of the graph zoomed in or zoomed out to obtain a better view, which can be achieved by pressing and holding down the left button on the mouse and draging a box around the place where you want to zoom in. To zoom out, click the right mouse botton and follow Zoom Out->Both Axes. To get back to the original graph, click the right mouse button and follow Auto Range->Both Axes.

[Top]

Parameter Scans

Parameter scans is an effective way in exploring how a model behaves to changes in parameters. BioNessie provides users with two types of parameter scans, standard parameter scans and monitoring-function based parameter scans. Whichever is applied, you will have to go through scan settings first.

To set up a scan, go to the tree, right click on the SBML model and select Create Parameter Scan to trigger the setting dialog. Give an expressive name to the scanning task and configure associated attributes, which include selecting a parameter to be scanned, defining the minimum (Begin Value), maximum (End Value) and density (Steps: this is the number of different values that the parameter will take) of the parameter space. You will also need to specify the total time and time steps for the simulation. Click OK to finish the scan settings. Now, you can see that on the right side of the window a panel displays all information about the scan you just designed

How to perfrom a standard parameter scan?

To run a standard parameter scan, go to bottom right corner and click on the button Do Local Parameter Scan Now!. You can find out how much the task has been processed from the progress bar . It normally takes a few seconds, which of course depends on the density of the parameter space. After the computation is done, go to the top of the panel and click on the button Multi-Sims, which leads you to a page with a graphical viewer on the left side and the parameter values on the right. Select a species from the selected box above the viewer to observe the dynamic behaviour (time-dependent) of the species in response to different values of the parameter. You can also focus on investigating the effect of a paticular parameter value on dynamics of the species by dismissing the boxes of the rest.

How to perform a monitoring-function based parameter scan?

To run a monitoring-function based parameter scan, go to the top of the panel and click on the tag Monitor Formulas to define a monitoring function which BioNessie will apply to draw scanning results. You need to give an expressive name to the function and write down the formula (which will be in the form of a mathematical expression where players of the formula are connected with mathematical operators). Click Add to save the function, and now you are ready for the function-based scanning. Go to bottom right corner and click on the button Do Local Parameter Scan Now!. You can find out how much the task has been processed from the progress bar. It normally takes a few seconds, which of course depends on density and quantity of the parameter space. After the computation is done, go to the top of the panel and click the tag Chart Results to graphically view the results. You can see a graphical viewer on the left side of the window and a list with three options on the right. The three options, Max, Min and Final, represent the maximum, minimum and final values of a monitoring function in each simulation routine calculated with different parameter values over the time interval. Choose a monitoring function from the box above the viewer to explore the relationship between the function and the parameter. For the same parameter, scanning results will be different with the monitoring function selected. You can also focus on one of the three options by dismissing others.

[Top]

Model Fitting

Computational models, in particular, ODE-based models, are commonly-used approaches in representing biochemical pathways in order to better understand the functioning of those pathways. For a pathway, given a topology of the model and values of the variables, initial concentration, and parameters, rate constants, we can then observe and analyse the dynamics of the pathway. However, experimental measurement of parameters of biochemical models is either time consuming or very expensive.

BioNessie provides users with the function of model fitting, which allows unknown parameters of ODE-based models to be determined by examining the goodness of the estimated parameters in fitting the observed curves. Towards the end, BioNessie employs two global methods, namely Genetic algorithm (GA) and stimulated anealling (SA). To set up a model fitting, go to the tree, right click on the SBML model and select New Fitting, which will lead you to a dialog where you can fill in general information for your fitting task. Click OkInput: load files containing observed experimental data, Arithmetic: choose a fitting method you are going to use for your task and perform the fitting, Result chart: view fitting curves and Report: view fitting results and the difference between observed values and simulated values. Here is the procedure to follow for model fitting: to exit the dialog; this will activate a working panel to be displayed on the right side of the window. On the top of the panel lists four buttons, by which you can,

  1. Click on Input, go to bottom left corner of the panel and click on New/Input to upload the text file containing observed data. In the popped-up window, click on Import from text file, select the file and click Open to exit the dialog and go back to the panel. In the list box under Input Curve, you will be able to get the information of the text file uploaded, for example, the name of the species for which observed data are supplied. Click on the item to view observed curves. Click here to download an example text file.
  2. Click on Arithmetic to configure fitting features, which include selecting a fitting method and a parameter to be fitted. Go to the section titled Arithmetic setting, select GA, define the maximum of the iterations to be performed (Circle) and the number of simulated curves you would like to have (Result count, say k, BioNessie will then display the curves drawn with the first k best values of the fitted parameter). Afterward, go to the section titled Parameter scan setting and click on Add to characterise your fitting task, which include the selection of a parameter to be fitted, and the definition of the starting and ending values of the parameter. Click Ok to exit the dialog.
  3. Click on the button Do fitting on bottom right corner of the panel to perform model fitting. Go to the viewer by clicking on Result chart to graphically view fitting results. To obtain textual results of the parameter, go to the top of the panel and click on Report.

[Top]

Sensitivity Analysis

To create a sensitivity analysis, go to the tree, right click on the SBML model and select Create Sensitivity. This will lead you to a dialog where you can create a task of sensitivity analysis. Give an expressive name and fill in the following options, which include selecting a parameter to be analysed, defining total time and time steps that BioNessie will use for computation. Click OK to complete the settings. Now, you can see on the right side of the window a panel displays all information about the task you just designed . Go to bottom right corner of the panel and click Do Sensitivity Analysis. Click the tag Chart on the top of the panel to graphyically view the results.

[Top]

Bibliography

  1. Chemical reaction - Wikipedia, the free encyclopedia.
  2. Introduction - Enzyme Kinetics and the Michaelis-Menten equation.

[Top]