SBase¶

The attributes every element of an SBML model carries.

Almost every object of an SBML model derives from the abstract type SBase, which carries the identifier, the name, the term of the Systems Biology Ontology and the two places for annotation: the notes for human readers and the annotation for machine readable metadata. An element type adds its own attributes on top of these, and may make an inherited attribute required, for example the identifier of a species. The lists which hold the elements derive from SBase as well, and a list which states one of these attributes is an element of the report.

The report shows these attributes for every element: the id and the name in the first two columns of every table, the meta id and the SBO term in the attributes of the inspector, the notes, the annotations and the history in its last section, and the XML behind the button of its header.

Attributes¶

id

The id is the name of the element inside the model. It is unique within a model and is what the math of a rule, of a kinetic law or of an event assignment writes when it refers to the element. Some types make the id required, for example a species, a compartment or a parameter cannot be referenced without one. On an initial assignment, a rule and an event assignment it is optional and it exists from Level 3 Version 2 on, so most models leave it empty; what such an element sets is its symbol or its variable, not its id.

The report shows the id in the first column of every table, behind the mark of the type of the element, and uses it as the label of every link to the element. An element without an id is named by the key of its primary key instead, and an element which the file nests in another one after that element.

Default: nothing can reference the element; the types which exist to be referenced, for example a species, a compartment or a parameter, require it.

• 10301 (error): The value of the 'id' field on every instance of the following type of object in a model must be unique: <model>, <functionDefinition>, <compartmentType>, <compartment>, <speciesType>, <species>, <reaction>, <speciesReference>, <modifierSpeciesReference>, <event>, and model-wide <parameter>s. Note that <unitDefinition> and parameters defined inside a reaction are treated separately.
• 10310 (error): The syntax of 'id' attribute values must conform to the syntax of the SBML type 'SId'.

name

The name is meant for human readers and has no meaning inside the model: it is not used for cross references and it does not have to be unique. A model which uses short identifiers usually carries the readable label here, for example "glucose 6-phosphate" for the species g6p.

The report shows the name in the second column of every table, next to the id.

metaid

The meta id exists so that the RDF metadata in the annotation of an element can name the element it describes. It is unique within the whole file, not only within the model, and it has no meaning for the mathematics of the model.

The report shows the meta id in the attributes of the inspector and uses it as a fallback label when an element has no id.

• 10307 (error): Every 'metaid' attribute value must be unique across the set of all 'metaid' values in a model.
• 10309 (error): The syntax of 'metaid' attribute values must conform to the syntax of the XML type 'ID'.

sboTerm

The Systems Biology Ontology is a set of controlled terms for the parts of a model, for example "simple chemical" for a species or "mass action rate law" for a kinetic law. The term makes the intention of the model author explicit for software which understands the ontology, and a model stays interpretable without it.

The report shows the term in the attributes of the inspector and links it to its entry on identifiers.org.

• 10308 (error): The value of an 'sboTerm' attribute must have the data type 'SBOTerm', which is a string consisting of the characters 'S', 'B', 'O', ':' followed by exactly seven digits.

notes

The notes hold XHTML written for human readers: a description of what the element stands for, the assumptions behind a rate law, the source of a value. They are the place where the story of a model is told, and many published models carry their documentation here.

The report renders the notes of the selected element in the last section of the inspector, under its annotations, with a restricted set of markup.

• 10801 (error): The contents of the <notes> element must be explicitly placed in the XHTML XML namespace.
• 10802 (error): The contents of the <notes> element must not contain an XML declaration (i.e., a string of the form "<?xml version="1.0" encoding="UTF-8"?>" or similar).
• 10803 (error): The contents of the <notes> element must not contain an XML DOCTYPE declaration (i.e., a string beginning with the characters "<!DOCTYPE".
• 10804 (error): The XHTML content inside a <notes> element can only take one of the following general forms: (1) a complete XHTML document beginning with the element <html> and ending with </html>; (2) the "body" portion of a document beginning with the element <body> and ending with </body>; or (3) XHTML content that is permitted within a <body> ... </body> elements.
• 10805 (error): A given SBML object may contain at most one <notes> element.

annotations

An annotation relates the element to an entry of an external database, for example to a ChEBI compound, a UniProt protein or a Gene Ontology process. Every relation names a qualifier, such as "is" or "is part of", so that the meaning of the reference is explicit. The qualifiers are those of MIRIAM and the entries are named by their identifiers.org url.

An annotation can carry annotations of its own, which qualify it further: the evidence for a relation, or the modification of the protein a species stands for.

The report groups the annotations of an element by qualifier and shows every resource as a card: its collection, its identifier, the term of its ontology with synonyms, description and cross references, the providers which show it, and for a ChEBI compound or a UniProt protein the information of that database.

• 99401 (warning): In order to follow the general syntax for a standard SBML RDF annotation the first element of RDF element must be a Description element with an 'about' attribute.
• 99402 (warning): In order to follow the general syntax for a standard SBML RDF annotation, the 'about' attribute of the Description element must be of the form #string.
• 99403 (warning): In order to follow the general syntax for a standard SBML RDF annotation, the 'about' attribute of the Description element must be of the form #string, where the string component is equal to the value of the metaid attribute of the containing SBML element.

history

The history is part of the standard annotation and records the creators of an element with their affiliation and electronic mail address, the date of creation and the dates of the modifications.

The report shows the history of the selected element below its annotations.

replacements

Replacements are the glue of a composed model. An element may state that it replaces elements of submodels, in which case every reference to those elements points at it afterwards, or that it is itself replaced by an element of a submodel. Two elements of different submodels are connected by letting one element of the containing model replace both.

The report shows the rows "replaced by" and "replaced elements" in the inspector of every element which carries them.

comp:replacedBy

An element which is replaced disappears from the composed model: every reference to it points at the element of the submodel instead. The submodel is named by its identifier, the element inside it by a port, an identifier, a unit identifier or a meta id, the four ways a reference of the package names an element.

The report links the submodel and shows the named element next to it.

• 1020105 (error): Any object derived from the extended SBase class (defined in the Hierarchical Model Composition package) may contain at most one instance of a <replacedBy> subobject.

comp:listOfReplacedElements

Every entry names a submodel and one element inside it which this element replaces. It is how a species of the containing model is connected to the species of two submodels: the containing species replaces both, and the three become one pool.

The report lists the submodel and the named element of every replacement in the inspector.

• 1020101 (error): Any object derived from the extended SBase class (defined in the Hierarchical Model Composition package) may contain at most one instance of a <listOfReplacedElements> subobject.
• 1020102 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfReplacedElements> container object may only contain <replacedElement> objects.
• 1020104 (error): The <listOfReplacedElements> in an SBase object is optional, but if present, must not be empty.

fbc:listOfKeyValuePairs

A key value pair carries metadata for which SBML has no attribute: the tool which produced a number, the database a reaction was taken from, the assumption behind a bound. It is written into the annotation of an element, in a namespace the package defines, so that every tool reads the same format instead of inventing its own.

Every key of one element is unique, the value is a string, and the uri says where the key is defined, for example a document which lists the keys of a tool.

The report lists the pairs of an element in its inspector. libsbml does not read the identifier and the name back from a file, so the report shows the key, the value and the uri alone.

• 2021501 (error): A <keyValuePair> object may have the optional SBML Level 3 Core attributes 'metaid' and 'sboTerm'. No other attributes from the SBML Level 3 Core namespaces are permitted on a <keyValuePair>.
• 2021502 (error): A <keyValuePair> object may have the optional SBML Level 3 Core subobjects for notes and annotations. No other elements from the SBML Level 3 Core namespaces are permitted on a <keyValuePair>.
• 2021503 (error): A <keyValuePair> object must have the required attribute 'fbc:key', and may have the optional attributes 'fbc:id', 'fbc:name', 'fbc:value' and 'fbc:uri'. No other attributes from the SBML Level 3 Flux Balance Constraints namespaces are permitted on a <keyValuePair> object.
• 2021504 (error): The attribute 'fbc:key' on a <keyValuePair> must have a value of data type 'string'.
• 2021506 (error): The attribute 'fbc:value' on a <keyValuePair> must have a value of data type 'string'.
• 2021507 (error): The attribute 'fbc:uri' on a <keyValuePair> must have a value of data type 'string'.
• 2021508 (error): A <ListOfKeyValuePairs> object must have the required attribute 'xmlns'. No other attributes from the SBML Level~3 Flux Balance Constraints namespaces are permitted on a <ListOfKeyValuePairs> object.

distrib:listOfUncertainties

Any element with a mathematical meaning or with math of its own may carry uncertainties, and it may carry several of them, because measures from different experiments or different publications may overlap or contradict each other and each set belongs together.

The report shows the uncertainties of an element in its inspector, each of them named with a link to it and with the table of the measures it collects, so that how well a value is known is read where the value is. Every uncertainty is an element of its own, which names the element it describes under "Referenced by", and the search finds an element by the names, the notes and the types of the measures of its uncertainties.

• 1520201 (error): A 'SBase' object may contain one and only one instance of the <listOfUncertainties> element. No other elements from the SBML Level 3 Distributions namespaces are permitted on a 'SBase' object.
• 1520202 (error): Apart from the general notes and annotations subobjects permitted on all SBML objects, a <listOfUncertainties> container object may only contain <uncertainty> objects.

In the report¶

xml

The report keeps the XML of every element so that a modeller can see what the file actually contains, including the parts of a package the report does not display. The document and the model are the exception: their XML is the whole file, so the report carries their annotation element instead. The nodes of a gene product association carry none either, because the XML of their reaction contains the whole association and every node of a deep tree would repeat the part below it.

The "XML" button in the header of the inspector puts the XML view in the place of its sections.

lists

The lists of an element, the listOfSpecies of a model or the listOfReactants of a reaction, derive from SBase themselves and may carry a meta id, an SBO term, notes and an annotation, and from Level 3 Version 2 on an id and a name. The report collects the lists of an element which state at least one of these, each as a list which is an element of its own. A list which states nothing is not part of the report, so most elements have none.

The report shows the lists of an element as links in the attributes of its inspector, and the row is left out where there are none.

Specification¶

SBML Level 3 Version 2 Core, Section 3.2 (Hucka et al. 2019, J Integr Bioinform 16(2):20190021).