0% found this document useful (0 votes)

400 views190 pages

SBML Tutorial for Biologists

This document provides a tutorial on SBML (Systems Biology Markup Language) and SBML Level 2 Version 2. It discusses the background and importance of computational modeling in biology. It also describes the need for a common file format to exchange models between software tools, and how SBML fulfills this role as a machine-readable format for representing computational models. The tutorial outlines key SBML concepts like components, structure, and usage to provide a general overview of SBML.

Uploaded by

Lluís M Bosch Lladó

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

400 views190 pages

SBML Tutorial for Biologists

Uploaded by

Lluís M Bosch Lladó

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 190

A tutorial about SBML and

SBML Level 2 Version 2

Michael Hucka
Biological Network Modeling Center, Beckman Institute California Institute of Technology Pasadena, California, USA

Sarah Keating
Science & Technology Research Institute University of Hertfordshire Hateld, Hertfordshire, UK

UH
1

Tutorial outline
1. Some background about SBML 2. SBML language basics 3. LibSBML and other SBML software infrastructure 4. Additional SBML features and SBML Level 2 Version 2 differences 5. A brief survey of SBML-compatible software 6. Closing comments and discussions

The background of SBML

Computational modeling is essential

Computational modeling is increasingly crucial to biology

Computational modeling is essential

Computational modeling is increasingly crucial to biology Not a new idea!

Experiencing heightened interest thanks to systems biology

Computational modeling is essential

Computational modeling is increasingly crucial to biology Not a new idea!

Experiencing heightened interest thanks to systems biology

Serves the scientic method

Enables quantitative hypothesis testing

Forces you to quantify every assumption & make it testable

Enables precise knowledge transfer Reduces ambiguities

Computational modeling is essential

Computational modeling is increasingly crucial to biology Not a new idea!

Experiencing heightened interest thanks to systems biology

Serves the scientic method

Enables quantitative hypothesis testing

Forces you to quantify every assumption & make it testable

Enables precise knowledge transfer Reduces ambiguities

Sign of rising popularity: new journals starting up

E.g., PLoS Computational Biology

Computational models

Software tools to aid modeling

General-purpose environments

Mathematica, MATLAB, etc.

Software tools to aid modeling

General-purpose environments

Mathematica, MATLAB, etc.

Special-purpose software
model editing simulation analysis visualization

Software tools to aid modeling

General-purpose environments

Mathematica, MATLAB, etc.

Special-purpose software
model editing simulation analysis visualization

CellDesigner

Software tools to aid modeling

General-purpose environments

Mathematica, MATLAB, etc.

Special-purpose software
model editing simulation analysis visualization

CellDesigner

JDesigner

Software tools to aid modeling

General-purpose environments

Mathematica, MATLAB, etc.

Special-purpose software
model editing simulation analysis visualization

COPASI

CellDesigner

JDesigner

Ability to exchange models is critical

Simply publishing equations is not enough

Dont want to transcribe equations from papers Want a common le format

Ability to exchange models is critical

Simply publishing equations is not enough

Dont want to transcribe equations from papers Want a common le format

Not an earth-shattering idea!

But curiously, such a format hadnt existed before year 2000

Each tool had its own unique proprietary format

SBML = Systems Biology Markup Language

Machine-readable format for representing computational models

SBML = Systems Biology Markup Language

Machine-readable format for representing computational models Suitable for reaction networks

Arbitrary rate functions

2A+BC CD+F ...

SBML = Systems Biology Markup Language

Machine-readable format for representing computational models Suitable for reaction networks

Arbitrary rate functions

Declarative, not procedural

2A+BC CD+F ...

SBML = Systems Biology Markup Language

Machine-readable format for representing computational models Suitable for reaction networks

Arbitrary rate functions

Declarative, not procedural Models can also include

2A+BC CD+F ...

Compartments (i.e., where chemical substances are located) Mathematical extras (assignments, explicit different eqs) Discontinuous events with arbitrary triggers

Fundamentally an exchange format

For transferring models between software tools Not meant as a systems internal format Not suited for representing

Experimental results Numerical simulation results

Now the de facto standard

Supported by >100 systems

Simulators, databases, analysis tools, editing tools

Accepted by journals
Nature PLoS Computational Biology BMC

Used in texbooks & courses

SBML Levels

Levels are meant to coexist Level 1: mostly basic compartmental modeling Level 2: signicantly more featurese.g.:

User-dened functions Events Types for chemical species and compartments Initial conditions, constraints, other ddly bits

Level 3: now (back) in development

Latest: SBML Level 2 Version 2

Final version released September 26

Embodies years of discussions and practical experience Most software currently only supports L2V1, not L2V2 yet

But L2V2 support will come soon

A general overview of SBML

How is SBML used?

Meant to provide an exchange language for software tools

How is SBML used?

Meant to provide an exchange language for software tools Dont write SBML by hand if you can help it

(SBML is in XML, so you could write it by hand if you had to)

How is SBML used?

Meant to provide an exchange language for software tools Dont write SBML by hand if you can help it

(SBML is in XML, so you could write it by hand if you had to)

Software tools that speak SBML provide a higher-level interface

How is SBML used?

Meant to provide an exchange language for software tools Dont write SBML by hand if you can help it

(SBML is in XML, so you could write it by hand if you had to)

Software tools that speak SBML provide a higher-level interface Applications usually have their own native format
Import/export SBML rather than natively save as SBML

Some important SBML constructs

Basic elements

species compartment parameter reaction

species A

reaction 1 species B reaction 2

Additional useful elements

unit denition rule function denition event initial assignment constraint

compartment_1

reaction 3 reaction 4 species C

species D

compartment_2

Example #1

One reaction, 2A

B + C, where rate is given as k[A(t)]2

Initial conditions: [A(0)] = 3, [B(0)] = 0, [C(0)] = 0.

Basic SBML document structure

<?xml version="1.0" encoding="UTF-8"?> <sbml xmlns="http://www.sbml.org/sbml/level2/version2" level="2" version="2"> ... </sbml>

Format: plain text (technically UTF-8) Extension: usually .xml (not .sbml)

The Model container

Overall structure of the XML rendition of a Model instance

<model id=m name=Example> <listOfFunctionDefinitions> ... </listOfFunctionDefinitions> <listOfUnitDefinitions> ... </listOfUnitDefinitions> <listOfCompartmentTypes> ... </listOfCompartmentTypes> <listOfSpeciesTypes> ... </listOfSpeciesTypes> <listOfSpecies> ... </listOfSpecies> ...

Overall structure of the XML rendition of a Model instance

order is signicant

listOf______s

Lists like Parameter[0..*] in the denition are translated into

listOf_____s are derived from SBase

Therefore, can have metaid, <notes>, <annotation>

SBase

Abstract type Most object structures in SBML are derived from SBase
<notes> allows human-readable annotations to be added

Format is XHTML

<annotation> allows machine-readable annotations to be added

Applications can put their own data into itjust needs to be XML Guidelines are discussed later in this tutorial

metaid is for references by annotations

Common feature: identiers and names

Most elements have both an id and a name eld

Identier eld has restricted syntax: abc123 or _abc123 or a_b_c_1 etc.

The id is what you use in expressions

Identier
species id compartment id parameter id function id reaction id (L2v2)

Meaning
quantity of the species size of the compartment numerical value a call to that function rate of the reaction

Value of name is unrestricted (exception: no newlines or carriage returns) Must assign a value to id on most objects, but name is always optional

Some tools let you use names & auto-generate ids (e.g., COPASI)

Representation of mathematical expressions in SBML

SBML Level 1: mathematical expressions encoded as text strings

In the XML, have formula=2*S1

SBML Level 2: math expressions encoded using MathML 2.0

Standard XML format for encoding mathematical expressions SBML uses only a subset of the content portion of MathML

MathML content always must be placed in a <math> element

MathML operators in SBML

Most common operators available:

plus, minus, power, exp, etc.

relational operators: eq, neq, gt, lt, geq, leq

piecewise pi, exponentiale many others

Complete list on p. 21 of L2V2 specication document

References in MathML

References to numbers are through the <cn> element:

References to identiers are through the <ci> element:

References in MathML

References to numbers are through the <cn> element:

References to identiers are through the <ci> element:

References in MathML

References to numbers are through the <cn> element:

References to identiers are through the <ci> element:

References in MathML

References to numbers are through the <cn> element:

References to identiers are through the <ci> element:

Compartment basics

id & name spatialDimensions

3, 2, 1, 0 (default: 3)

size

Floating-point number giving the compartment size (volume or other) Identier of the units of measure for the size Identier of the compartment outside of this one
Boolean: is the compartment size constant? (Default: true)

units outside outside

constant

Compartment example
... <listOfCompartments> <compartment id="cytoplasm" size="5"/> <compartment id="nucleus" size="1" outside="cytoplasm" /> </listOfCompartments> ... <listOfSpecies> <species id="X" compartment="nucleus" initialAmount="1" /> <species id="Y" compartment="cytoplasm" initialAmount="1" /> </listOfSpecies> ...

Species basics

id & name compartment

Identier of compartment where species is located Floating-point number giving initial quantity as molecular/item count Floating-point number giving initial quantity as concentration

initialAmount initialConcentration

More precisely: (units of substance)/(units of size)

Species basics

id & name compartment

Identier of compartment where species is located Mutually exclusive initialAmount Floating-point number giving initial quantity as molecular/item count Floating-point number giving initial quantity as concentration

initialConcentration

More precisely: (units of substance)/(units of size)

Species basics

id & name compartment

initialConcentration

More precisely: (units of substance)/(units of size)

boundaryCondition
Boolean: should a rate of change equation be constructed for the species based on the system of reactions? (Default: false) Boolean: is the species quantity constant? (Default: false)

constant

More about species

Think of species as a pool of molecules of the same type Species must be located in some compartment

If have the same species in multiple compartments, must have separate species denitions for each

... but in L2V2, can use SpeciesType to relate them together

If doing stochastic model, best dene species in terms of amounts

Species example
<listOfSpecies> <species id="S1" initialConcentration="0" compartment="c1" boundaryCondition="true" /> <species id="S3" initialConcentration="10" compartment="c2" constant="true"/> <species id="S4" initialConcentration="4.5" compartment="c2"/> </listOfSpecies>

Parameter basics

id & name value

The oating-point value of the parameter

units
Identier of the units of measure for the value

constant
Boolean: is the value of the parameter constant? (Default: true)

Parameter example
<listOfParameters> <parameter id="k1" value="0.5"/> <parameter id="k2" value="0.1"/> </listOfParameters>

Reaction basics

References to dened species

Reaction basics

id & name

<listOfReactants> (optional) <listOfProducts> (optional) <listOfModifiers> (optional) <kineticLaw> (optional)

References to dened species

Reaction basics

id & name

<listOfReactants> (optional) <listOfProducts> (optional) <listOfModifiers> (optional) <kineticLaw> (optional)

reversible

References to dened species

Boolean: is the reaction reversible? (Default: true)

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

Reaction can have any number of reactants or products, but must have at least one reactant or product

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

Reaction can have any number of reactants or products, but must have at least one reactant or product A species can appear in both the list of reactants & list of products

Effective stoichiometry is then: (stoich.-as-react.) - (stoich.-as-prod.)

E.g.: 2A

A+B

==> effective stoichiometry of A is +1

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

Reaction can have any number of reactants or products, but must have at least one reactant or product A species can appear in both the list of reactants & list of products

Effective stoichiometry is then: (stoich.-as-react.) - (stoich.-as-prod.)

E.g.: 2A

A+B

==> effective stoichiometry of A is +1

A species labeled as modier may also appear in list of reactants and/or productsnot an either/or situation

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

Reaction can have any number of reactants or products, but must have at least one reactant or product A species can appear in both the list of reactants & list of products

Effective stoichiometry is then: (stoich.-as-react.) - (stoich.-as-prod.)

E.g.: 2A

A+B

==> effective stoichiometry of A is +1

A species labeled as modier may also appear in list of reactants and/or productsnot an either/or situation A modier species appears in the rate expression but is neither created nor destroyed in that reaction

About reactants, products and modiers

All species must be dened in the models top-level list of species

Reactions simply refer back to the species denitions

Reaction can have any number of reactants or products, but must have at least one reactant or product A species can appear in both the list of reactants & list of products

Effective stoichiometry is then: (stoich.-as-react.) - (stoich.-as-prod.)

E.g.: 2A

A+B

==> effective stoichiometry of A is +1

Lists of reactants, products and modiers

Most import common eld: species

species value must be id of existing species dened in the model

ModierSpeciesReference does not add any more elds SpeciesReference adds elds for stoichiometry

Lists of reactants, products and modiers

Most import common eld: species

species value must be id of existing species dened in the model

ModierSpeciesReference does not add any more elds SpeciesReference adds elds for stoichiometry

Lists of reactants, products and modiers

Most import common eld: species

species value must be id of existing species dened in the model

ModierSpeciesReference does not add any more elds SpeciesReference adds elds for stoichiometry

Stoichiometries

Normally a stoichiometry is an integer or oating-point scalar value

Default value is 1

<reaction id="Dimerization" reversible="false"> <listOfReactants> <speciesReference species="P" stoichiometry="2"/> </listOfReactants> <listOfProducts> <speciesReference species="P2" /> </listOfProducts> ...

For more complicated stoichiometries, use stoichiometryMath

MathML expression Mutually exclusive with stoichiometry, use one or the other

Stoichiometries

Normally a stoichiometry is an integer or oating-point scalar value

Default value is 1

For more complicated stoichiometries, use stoichiometryMath

MathML expression Mutually exclusive with stoichiometry, use one or the other

Stoichiometries

Normally a stoichiometry is an integer or oating-point scalar value

Default value is 1

For more complicated stoichiometries, use stoichiometryMath

MathML expression Mutually exclusive with stoichiometry, use one or the other

KineticLaw basics

<math>

MathML expression for the speed of the reaction Units must be substance/time

<listOfParameters>
Denes parameters whose identiers have scope local to the reaction only

Not visible from any other reaction, or rest of model Identiers shadow global identiers

Data type is same Parameter as for global parameters

KineticLaw basics

<math>

MathML expression for the speed of the reaction Units must be substance/time not concentration/time

<listOfParameters>
Denes parameters whose identiers have scope local to the reaction only

Not visible from any other reaction, or rest of model Identiers shadow global identiers

Data type is same Parameter as for global parameters

Interpreting reactions

Why are SBML rate expression not identical to rate laws?

Consider simple example:

What does this mean?

S1 S2 rate law = k [S1 ]

V1 S1 S2 V2

d[S2 ] d[S1 ] = = k [S1 ] dt dt But what if V1 = V2 ? For example, what if V2 = 3V1 ?

How molecules leave & enter each compartment?

Look at number of molecules of each species in each compartment:

nS1 = [S1 ] V1

nS2 = [S2 ] V2

k [S1 ] V1 molecules leave the rst compartment 3 k [S1 ] V1 molecules enter the second compartment

Kinetic law in SBML

Rate expressions are substance/time, not substance/size/time Conversion for basic cases is simple:

Multiply by volume of compartment where reactants are located:

rate = k [S1 ] V1
Express rates of changes of reactants & products in terms of substances:

dnS1 = k1 [S1 ] V1 dt dnS2 = k1 [S1 ] V1 dt

Can easily recover concentrations:

nS1 [S1 ] = V1

nS2 [S2 ] = V2

Kinetic law in SBML

Rate expressions are substance/time, not substance/size/time Conversion for basic cases is simple:

Multiply by volume of compartment where reactants are located:

rate = k [S1 ] V1
Express rates of changes of reactants & products in terms of substances:

dnS1 = k1 [S1 ] V1 dt dnS2 = k1 [S1 ] V1 dt

Can easily recover concentrations:

moles items mass dimensionless

nS1 [S1 ] = V1

nS2 [S2 ] = V2

Example #2
S1 S2 S3
Rate laws:

r1 = k1 [S1 ]

r2 = k2 [S2 ]

Compartments: Compartment volumes: Initial concentrations: Volumes: Constants:

S1 V1 S1 = 4 V1 = 1

S2 V2

S3 V3 S2 = 10 S3 = 0

V2 = 0.5 V3 = 2 k2 = 0.7

k1 = 0.2

Example #2: interpretation of differential equations

Express rates of change of species quantities (as amounts, not concentrations):

dnS1 = r1 dt dnS2 = + r1 r2 dt dnS3 = + r2 dt

= k1 [S1 ] V1 = +k1 [S1 ] V1 k2 [S2 ] V2 = + k2 [S2 ] V2

LibSBML and other SBML software infrastructure

Software infrastructure supporting use of SBML

http://sbml.org/wiki/icsb2006_tutorial

libSBML
Ben Bornstein and Sarah Keating

Application Programming Interface read write validate translate

manipulate

Languages ISO C and C++ java python perl lisp MATLAB octave
(coming in libSBML-3)

XML Parsers Xerces Expat libXML

(coming in libSBML-3)

Platforms Linux Windows Mac OS

Why use libSBML ?

Memory efficient

Why use libSBML ? SBML validation

XML checks syntax checks ordering checks consistency checks

Why use libSBML ? High level interface

Query a model
Model->getNumReactions() Compartment->isSetSize()

Retrieve information from a model

Model->getSpecies(s1) Species->getInitialConcentration()

Why use libSBML ? High level interface

Add information to a model
Species->setInitialConcentration(2.0) Compartment->setSize(5.6)

Create a model
Model->create(my_model) Model->addCompartment(Compartment&)

Why use libSBML ? Math support

Infix (Level 1)
k*A*B

MathML (Level 2)
<apply> <times/> <ci> k </ci> <ci> A </ci> <ci> B </ci> </apply>

Getting started
http://sourceforge.net/project/showfiles.php?group_id=7 1971&package_id=71670

http://sbml.org/wiki/icsb2006_tutorial Download libSBML

Online validator
Ben Bornstein

http://sbml.org/validator/

SBMLToolbox
Sarah Keating

An SBML toolbox for MATLAB users

Why use SBMLToolbox ?

import SBML into MATLAB represent models as MATLAB structures

Why use SBMLToolbox ?

mimic libSBML API examples of simulation

Why use SBMLToolbox ?

GUI Model inspector/creator save/load models to MATLAB data files

NOT a systems biology toolbox

provides import/export between SBML and MATLAB provide examples of how MATLAB functionality can be applied to SBML models

Acknowledgements
Ben Kovitz Stefan Hoops Christoph Flamm Rainer Machne Martin Ginkel Mike Hucka Anyone who caught bugs, made suggestions, discussed

Break

Additional SBML features and SBML Level 2 Version 2 differences

Units in SBML

All mathematical entities can have units dened or implied. 2 ways:

Key object structures have explicit elds for setting units:

Structure Compartment Species Parameter Event KineticLaw Units elds
units substanceUnits, spatialSizeUnits units timeUnits substanceUnits, timeUnits

removed in L2V2

Built-in default units

Identifer substance volume area length time Default mole litre square metre metre second Possible scalable units mole, item, gram, kilogram, dimensionless litre, cubic metre, dimensionless square metre, dimensionless metre, dimensionless second, dimensionless

Redening units

Same mechanism for dening new units and redening the built-ins:

Unit denition creates a new unit identier (the value of id)

Unit identier namespace is global but different from space of other ids

Approach is multiplicative composition

E.g., moles/(litre second) =

mole
UnitDenition Unit

1 litre
Unit

1 second
Unit

The meaning of elds in Unit

yb {ub } = y {u} w {ub } {u}

The meaning of elds in Unit

yb {ub } = y {u} w {ub } {u}

Quantity y in original units u

The meaning of elds in Unit

yb {ub } = y {u}
Units you want to convert into

w {ub } {u}

Quantity y in original units u

The meaning of elds in Unit

Resultant quantity

yb {ub } = y {u}
Units you want to convert into

w {ub } {u}

Quantity y in original units u

The meaning of elds in Unit

Resultant quantity

yb {ub } = y {u}
Units you want to convert into

w {ub } {u}

SBML lets you dene this

Quantity y in original units u

The meaning of elds in Unit

yb {ub } = y {u} w {ub } {u}

The meaning of elds in Unit

yb {ub } = y {u} w {ub } {u}

{u} = (multiplier 10scale {ub })exponent

The meaning of elds in Unit

yb {ub } = y {u} w {ub } {u}

{u} = (multiplier 10scale {ub })exponent

UnitKind is an enumeration of base units (SI + a few extras)

mole, kelvin, second, metre, litre, gram, kilogram, item, dimensionless, etc.

Example unit denition

Denition of foot:
foot = (0.3048 "100 "metre)1 yb metres = 0.3048 "y feet
<listOfUnitDefinitions> <unitDefinition id="foot"> <listOfUnits> <unit kind="metre" multiplier="0.3048" exponent=1 scale=0/> </listOfUnits> </unitDefinition> </listOfUnitDefinitions>

Default model-wide units

Redene the special units time, substance, volume, length, area

Tools usually provide a more direct way

Changes to unit system in L2V2

No offset on UnitDenition No predened unit Celsius

Modeler needs to include necessary conversions explicitly

Could use a function denition Could use an assignment rule

AssignmentRule, RateRule, AlgebraicRule

Rules in SBML dene extra mathematical expressions

E.g.: if need to express additional mathematical relationships beyond what is implied by the system of reactions

3 subtypes:
Rule type algebraic assignment rate General form Example 0 = S1 + S2 x=y+z dS/dt = 10.5