— the global portal for all things SBML

No default values

A source of confusion and error in interpreting models in SBML Level 2, as well as a burden on implementers, is the specification of default values for certain attributes of SBML components, as well as the default unit identifiers substance, time, volume, area, and length.

The¬†motivation for having default values in Level 2 was to allow SBML model definitions to omit mentioning the defaulted attributes or entities, making for a smaller and less verbose file. The following example using Species illustrates how defaults are used for the value of the attributes hasOnlySubstanceUnits, boundaryCondition, and constant:

The presence of a default attribute value means that an SBML model file does not need to mention the defaulted attributes and their values. For example, the following <species> definition in SBML Level 2 does not mention a value for the attributes hasOnlySubstanceUnits, boundaryCondition, and constant, and thus their values are assumed to be all "false":

<species id="s" compartment="c">

Note that this matter only concerns attributes that have default values, not optional attributes with no default values (such as initialConcentration) ; such attributes have no value at all if they are not mentioned in a component's definition in a model.

The decision to codify specific default values into SBML turned out to be problematic for several reasons. First, the particular values¬†chosen were in some cases contentious, with different people strongly preferring one default value over another. Second, more importantly, experience has shown that it is far too easy for a reader (especially a human reader) to misinterpret a model in this scheme. It was necessary to know the entire SBML specification in considerable detail to understand which attributes, even if not mentioned in a given SBML file, still had default values that affected the interpretation of the model. Finally, the fact that default values exist at all means that a Level 2 model is in some sense not self-contained.

For SBML Level 3, the SBML Editors have concluded the best approach is simply to remove all default values from the specification. This means that any attribute or element not mentioned in the XML file does not exist in that model. Referring again to the example above, the consequence of this change in Level 3 is that the species above would have to be written as follows:

<species id="s" compartment="c" 
                hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false">

Note that in this particular example, the other Species attributes (e.g., initialAmount) are not assigned values and thus (like the original Level 2 version above) have no value for this particular instance. (This example is not necessarily realistic for a functioning model; it is only meant to illustrate how the Level 3 no-default-values approach works.)

Changes compared to Level 2

The changes apply to two areas of SBML:

  • Any attribute listed in Level 2 as being both optional and having a default value will, in Level 3, become a required attribute with no default value. From the standpoint of a reader, if an SBML file does not contain a particular attribute, it means the attribute has no value. The following SBML components are affected by this change:
    • Unit
    • Compartment
    • Species
    • Parameter
    • Reaction and its subsidiary component class SpeciesReference
    • Event
  • The "built-in" unit identifiers substance, time, volume, area, and length will no longer be defined. The definition of default units for a model will instead be handled by new attributes on the Model component.
  • This principle does not apply to the MathML subset used in SBML. MathML constructs that have attributes with default values remain unchanged in Level 3 Core. The rationale for this is the following: (1) it would not be a MathML requirement, but an SBML requirement, and thus would represent a new restriction on MathML content in SBML; (2) it would potentially lead to implementation problems for developers using off-the-shelf MathML parser libraries, because such parsers may not offer control over this behavior.

Notable implications

The following are some specific implications of this change:

  • There will be no "built-in" units anymore. The units of substance, time, volume, etc., in the model will have to be explicitly defined using new attributes on Model. Undefined units will be, quite literally, undefined.
    • A corollary of this is the following: if a model does not define all the relevant units for the quantities used in the model, then the model's unit specification is incomplete. Numerical values appearing in the model, and the results of simulations, will be interpreted as being purely numerical, with no physical units associated with the values.
  • A number of attributes that are often omitted in Level 2 models today (because they have default values that suit most people) will have to be given explicit values in Level 3 models. For example, the attributes constant, hasOnlySubstanceUnits, and boundaryCondition on Species objects will have to be set on every species defined in a Level 3 model.
  • Model file verbosity and file size will increase. The former is only an issue for human readers (computer software doesn't care), while the negative consequences of the latter issue are largely mitigated by the high speeds and storage capacities of modern computers and software solutions such as compression.

Retrieved from ""

This page was last modified 02:58, 6 July 2009.

Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 02:58, 6 July 2009.