SBML

SBML Home Page

Annotated Extensions to SBML for Graphical Layout

See the following document for details of Graphical Layout Annotations used by JDesigner

PDF Document

SBML DLL Library

DOWNLOAD

Update to version 1.45

If you have an application which you'd like to have the ability to read SBML but haven't got the time to learn how to parse XML or read the SBML document (and who can blame you), then this DLL is for YOU! This windows DLL exposes an API which you can use to load SBML files or parse SBML strings and then access the details of the model via the API. Here's an example:

OpenNOM();  // Initialise DLL memory usage
if (!LoadSBMLFromFile ("mymodel.xml")) {

   printf ("Number of reactions in the model equals %d\n", GetNumReactions()); 
   for (i=0; i<GetNumSpecies(); i++)
       printf ("Species %d = %s\n", GetNthSpeciesName (i)); 
} else
   printf ("Error loading SBML file: %s\n", GetErrString());

CloseNOM();  // Free all memory used by DLL

and so on. For more details check out the documentation. Download binaries, src and docs HERE.

Instructions:

unzip the download file and copy the file sbml11.dll to your application area or windows system area. Read the docs and add the appropriate calls to your application. There is a small test program (exe provided) which you can use to load some of the test examples.

Source code is also provided and should in theory compile under Linux, though I haven't tried. The DLL uses the OpenXML library (http://www.philo.de/xml/) which is an open source, easy to use and fairly light-weight XML parser. 

Comments on SBML Level 1:

1.  Local versus Global Parameters

2. Default Compartment

In the current version, a compartment must always be defined. In the majority of cases, models are build using a single volume of unit size. It would have been convenient therefore to assume that if no volume were specified for a species then the simulator could assume that the volume associated with the species was the unit volume. In the current version, all species must be explicitly associated with a volume, this adds unnecessary clutter to the XML. SBML should employ sensible defaults when necessary.

3. Rules

The rules section is not well defined in level one. A case in point, the parameter rule is derived from assignmentRule. However, the assignmentRule has an attribute type indicating whether the left hand side refers to a rate or a simple scalar. In other words parameter are allowed to have rates of change, now unless I am mistaken, parameter should not have this property. Parameters may have scalar rules which change them, eg Glucose = sin (time)*a + b) but not rates of change.

SBML Level 3: Proposed Changes to Level 1

Level 1 has proved problematic in a number of areas and I therefore propose the following modifications to Level 1. Note that Level 2 has already been determined by the original SBML team. If anyone has solid scientific reasons to object to these proposed changes please let me know!

Proposal for L13

1. Default Compartments

It is proposed that if a species is declared without specifying a compartment then it will be assumed that the species exists in the default unit volume. All species which have undeclared volumes will assume to be in this unit volume.

Secondly, there is no longer any need to define at least one volume in a model since the default volume is implied. Previously one always had to declare a unit volume and every species had to reference this volume. With the proposed changes this requirement is no longer necessary.

Reason for proposal: Make SBML model files simpler.

2. Positive Stoichiometries

SBML Level 1 and 2, define stoichiometries as positive integers. This is not in accordance with the usual definition a stoichiometry. This is only a minor irritation and will therefore be left as is. However it is important that all SBML reader software (eg the SBML DLL library) make the necessary sign conversion when reading the stoichiometry.

3. Empty Elements

In Level 1 (State of Level 2 is unknown at this stage), empty elements such as the listOfParameters or listOfReactions are considered invalid SBML. In the Level 3 proposal this restriction will be relaxed. Thus listOfCompartment, listOfSpecies, listOfParameters, listOfRules, and listOfReactions may be empty.

4. Rules

The biggest proposed change is to the rules section.

1. Simple assignments. In the current spec assignments are categorized according to what type the left hand side the rule has (eg parameter, species, volume). The spec does not contain any recommendations on how we should use the categorization and particularly on why these categories exist. For example how are they useful to software developers?

The following assignments include, simple parameter assignments, as in k2 and pH, derived quantities, k1 and v1, which may be used in one or more subsequent equations in order to improve the performance of function evaluation. And lastly species assignments, these could be used to compute equilibrium concentrations.

The parameter assignments are worth commenting on. Parameters which as assigned in a rule are not your usual run of the mill parameter. They are either derived values from other parameters etc, or they are newly introduced constants. Either way, an outside agent has no way to directly affect one of these parameters during a run because if the assignment is from a constant (eg k2) then it's impossible and if the assignment is a derived quantity then an outside agent can only affect this parameter by manipulating things which the parameter depends on (eg v1). In a sense rule based parameters are hidden parameters. There is thus a distinction to be made between rule based parameters and those declared in the local or global parameter lists.

I think pretty much anything goes in a simple assignment, it is entirely up to the modeler to decide what assignments he or she needs. Some simulators can construct assignments automatically, for example species equilibrium assignments may be derived automatically rather than being specified by the user. There has been some discussion that species rules must be limited to species which do no occur in the reaction scheme or have in ode rules, this is modeling tool issue, one which can be enforced by the tool.

Another point about equilibrium pools, I suppose it is better to use the fast attribute on a reaction rather then specifying the pools explicitly since the simulator will then have the option to implement fast reactions or not. Using the fast attribute also preserves the structural information of the network which has it's advantages. At the same time we shouldn't stop people from explicitly defining fast sub-networks if they so wish. 

2. Linear or non-linear constraints. These will be combined with any odes rules and odes derived from the reaction scheme to form a set of differential-algebraic equations.

3. Additional differential equations which augment the odes derived from the reactions section. Note that the reaction section is optional since a model can in principal be fully characterized using the rules section only, although quite a bit of information is lost in this process, in particular the structure of the biochemical network.

4. Finally the reaction scheme itself. These schemes will often have additional constraints implied in the network structure, these constraints are in addition to any constraints specified in the rules section. In these cases the simulator will work out the implied constraints and add them internally to the rules section.

In terms of SBML we only need three rule tags, assignment rules, constraint rules and ode rules. For the constraint rules I would specify both left and right hand sides and the constraint operator. This allows at some future date the option to include relational constraints such as, A + B > 5.6 example

Rules are evaluated in the order they are given and I think it is up to the SBML generation code to ensure that the order is a sensible one, i.e. no cyclic references. Another issue which people have raised is that fact that boundary species are defined as constant, yet we allow them to vary by inserting rules which manipulate them, see second assignmentRule in the example above. I don't think this is such an issue, we can treat the assignmentnrule as overriding the constant boundary condition. Note that the assignmentRule still leads to a boundary conditions, it's just that it is no longer constant.

5. Pre-declaration of New Symbols in the Rules Section

The rules section has the potential to create new symbols, see examples above. Within the context of a simulator these new symbols are local to the equations that define the model. In contrast, the list of parameters that can be defined in the listOfParameters element are global and are not local to the model, they may be passed to the model through the models argument list but nevertheless they are essentially global symbols. There was talk of requiring that new symbols in the rules section be declared in the global parameter list, however we can see that these two entities are quite different. I therefore suggest that if people really want to declare new symbols beforehand that they be declared in the rules section itself, since this is where they really belong. The question which comes to my mind is do we actually need to pre-declare new rule symbols? As far as I know there are only two reasons why languages pre-declare symbols (if there are others tell me please): 1) because a language may have multiple data types and rather than carry out a dynamic typing at runtime (which is expensive), the type is declared at compile time and memory can be specifically allocated during compilation to store the declared variables;

2) It assists the user in locating bugs, by insisting on pre-declaration of symbol names, it is not possible for a programmer to inadvertently make a typo and thus introduce a bug (Basic and Python programmer I guess, get this problem all the time).

In SBML we have only a single type, namely double, therefore reason 1) does not apply. Secondly SBML is written by computers not humans, thus the risk of making typo mistakes is not very likely. I therefore wonder if there is any reason at all why we need to pre-declare new symbols introduced in the rules section, personally I see no compelling reason to pre-declare local rule symbols. If someone can come up with a really good reason, then sure we should pre-declare them. There was a lot of huff and puff at the Herts meeting about this topic but no one seemed to come up with a really compelling reason other that because that's what we'd been taught in comp sci.

6. Local versus global Parameters

This issue is more difficult to resolve and at the moment there is no simple solution, however see parameters. The proposal to to remove local parameters.