Subcellular application

Subcellular application (https://subcellular.humanbrainproject.eu/model/meta) provides a web interface for simulation of biomolecular networks expressed on bionetgen language (https://bionetgen.org/) using network free solver NFsim and reaction-diffusion stochastic systems solver STEPS (http://steps.sourceforge.net/STEPS/documentation.php) Models can be imported from an sbml file. In this repository we used two model examples to exemplify the usage of this tool.

BioNetGen translation of SBtab Nair_2016 model

The model was translated from SBtab model format to rule-based BioNetGen language for the simulation with STEPS and NFsim solvers embedded in the subcellular web app and with the RuleBender

Conversion steps

  • Run convert_Nair_2016_from_SBTAB_to_SBML.R in RStudio to translate SBtab model to SBML. This step depends on SBtab to SBML converter

  • Run convert_Nair_2016_from_SBML_to_BNGL.ipynb jupyter notebook to translate from SBML to BioNetGen language

  • Import the resulted BioNetGen model Nair_2016_optimized_alternative.bngl to the subcellular web app. Add spine geometry .json, .node, .ele, .face files and stimulation pattern stim_DA_complex.tsv. See the subcellular web app help for details

  • Simulate the final model Nair_2016_optimized_alternative.ebngl in the subcellular web app using STEPS or NFsim solvers

Files and folders

Nair_2016_optimized_alternative.ebngl - extended BNGL model corresponding to the optimized Nair 2016 SBtab model with added geometry and stimulation patterns. Can be imported and simulated in the subcellular web app

SBTAB_Nair_2016 - the folder with the optimized Nair 2016 SBtab model tsv tables.

Nair_2016_optimized.xml - SBML model translated from the optimized Nair 2016 model by convert_Nair_2016_from_SBTAB_to_SBML.R script based on SBtab to SBML converter

Nair_2016_optimized_alternative.bngl - BioNetGen model obtained from Nair_2016_optimized.xml by convert_Nair_2016_from_SBML_to_BNGL.ipynb jupyter notebook which is based on sbml_to_bngl.py conversion tool

spine.ele, spine.face, spine.node, spine.json - these files specify TetGen meshes and model geometry needed for the subcellular web app Geometry section and STEPS solver (see the subcellular web app help for details)

stim_DA_complex.tsv, stim_noDA_complex.tsv - these files specify the stimulation pattern in Simulations section of the subcellular web app (corresponds to the experiments E0 - E9 of the SBtab model).

SBtabVFGEN-master - the folder containing a copy of SBtab to SBML converter

sbml_to_bngl.py - the python tool for conversion of SBML models to BioNetGen language.

BioNetGen translation of SBtab Viswan_2018 model

The model was translated from SBtab model format to rule-based BioNetGen language for the simulation with STEPS and NFsim solvers embedded in the subcellular web app and with the RuleBender

Conversion steps

  • Run convert_Viswan_2018_for_STEPS_optimised_from_SBTAB_to_SBML.R in RStudio to translate SBtab model to SBML. This step depends on SBtab to SBML converter and LibSBML

  • Run convert_Viswan_2018_for_STEPS_optimised_from_SBML_to_BNGL.ipynb jupyter notebook to translate from SBML to BioNetGen language. This step depends on sbml_to_bngl.py and on LibSBML or pySB

  • Import the BioNetGen model (SBTAB_Viswan_2018_alternative.bngl) to the subcellular web app. Add spine geometry ( .json, .node, .ele, .face files) and stimulation pattern (stim_E0.tsv). See the subcellular web app help for details

  • Simulate final model (SBTAB_Viswan_2018_alternative.ebngl) in the subcellular web app using STEPS or NFsim solvers

  • Simulate the BioNetGen model with the RuleBender

Files and folders

SBTAB_Viswan_2018_alternative.ebngl - extended BNGL model corresponding to the Viswan_2018_for_STEPS_optimised.xlsx SBTAB model with added geometry and stimulation patterns. Can be imported and simulated in the subcellular web app

Viswan_2018_for_STEPS.xlsx - SBtab model equivalent to the original Viswan_2018 model. It was obtained from Viswan_2018.xlsx by the modification of the model features incompatible with BNGL.

Viswan_2018_for_STEPS_optimised.xlsx - SBtab model equivalent to the optimized Viswan_2018 model. It was obtained from Viswan_2018_optimized.xlsx by the modification of the model features incompatible with BNGL.

SBTAB_Viswan_2018.xml - SBML model translated from Viswan_2018_for_STEPS_optimised.xlsx model by convert_Viswan_2018_for_STEPS_optimised_from_SBTAB_to_SBML.R script based on SBtab to SBML converter

SBTAB_Viswan_2018_alternative.bngl - BioNetGen model obtained from SBTAB_Viswan_2018.xml by convert_Viswan_2018_for_STEPS_optimised_from_SBML_to_BNGL.ipynb jupyter notebook which is based on sbml_to_bngl.py conversion tool

cell.ele, cell.face, cell.node, cell.json - these files specify TetGen meshes and model geometry needed for the subcellular web app Geometry section and STEPS solver (see the subcellular web app help for details)

stim_E0.tsv, stim_E1.tsv - these files specify the stimulation pattern in Simulations section of the subcellular web app (corresponds to the experiments E0 and E1 of the SBtab model).

Viswan_2018_alternative_RuleBender.bngl - BNGL model corresponding to the Viswan_2018_for_STEPS_optimised.xlsx SBtab model with additional section specifying stimulation and BioNetGen solver. Can be imported and simulated in the RuleBender

SBtabVFGEN-master - the folder containing copy of SBtab to SBML converter

SBTAB_Viswan_2018_for_STEPS_optimised - the folder containing tsv tables of Viswan_2018_for_STEPS_optimised.xlsx

sbml_to_bngl.py - the python tool for conversion of SBML models to BioNetGen language.

Conversion of SBML to BioNetGen language

The conversion is implemented in sbml_to_bngl.py python module. Two approaches are supported by sbml_to_bngl.transform() function:

  • if converter=’pysb’ - the converter based on the Atomizer implemented in pysb.importers.sbml.sbml_translator() function within pySB framework will be used. The Atomizer will try to modify the set of model molecules and reactions to convert them from reaction network to rule-based BioNetGen format.

  • if converter=’plain’ - a libsbml based converter for sbml level 2, version 4 will be used. This converter produces a bngl approximation to reaction network format of a model. It is assumed that sbml models were obtained by exporting a MATLAB simbiology model to sbml, or by translation of SBTAB model by SBtab to SBML converter.

Models expressed by SBML and SBTAB often are not fully compatible with BNGL. Additional model adaptation steps are required in this case to obtain a working BNGL model. These steps will be partially automatized by sbml_to_bngl.transform() function if adapt_steps argument dictionary ‘list_of_steps’ is nonempty.

The adaptation steps include:

  1. The STEPS and NFsim solvers require different units for species quantities an kinetic rates. An adapted BNGL model provides modifed expressions for all species concentrations and kinetic rates and provides an easy way for units changing by specification of auxilary bngl model parameters: Na and V_comparment_name. These parameters should be selected to: Na=6.022e23 and V_comparment_name = volume of corresponding compartment in liters for NFsim and to: Na=1 and V_comparment_name=1 for STEPS.

  2. Species with fixed concentrations are not supported by NFsim solver. The BNGL model adaptation will modify model reactions such that a fixed species concentration became a model parameter. This parameter can be used for the clamping of species concentration or for the stimulation pattern application

  3. If SBML to BNGL converter implemented in Atomizer is selected then additional transformation steps include renaming of duplicated molecule sites and reparing incorrect molecule names and kinetic rate transformations

  4. In case when MATLAB simbiology is used for SBML model creation, adapt_steps will repare incorrect molecule and parameter names

  5. Compartmental model of BNGL assumes tree structure of the set of model comartments. This assumption is often incompatible with mesh geometries supported by STEPS. The model adaption steps can produce bngl models with flexible compartmental structure

  6. There is a number of incompatibilities between SBTAB and BNGL which still require manual correction. These include concentrations fixed to an expression, functional expressions for reaction rates in case of STEPS solver, some nonstandard types of reaction kinetic functions etc. The adapt_steps detects the cases of known incompatibilities and produces corresponding warning messages