libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
CVTerm_t Class Reference

Detailed Description

Representation of MIRIAM-compliant controlled vocabulary annotation.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBML Level 2 and Level 3 specifications define a simple format for annotating models when (a) referring to controlled vocabulary terms and database identifiers that define and describe biological and biochemical entities, and (b) describing the creator of a model and the model's modification history. This SBML format is a concrete syntax that conforms to the guidelines of MIRIAM ("Minimum Information Requested in the Annotation of biochemical Models", Nature Biotechnology, vol. 23, no. 12, Dec. 2005). The format uses a subset of W3C RDF (Resource Description Format). In order to help application developers work with annotations in this format, libSBML provides several helper classes that provide higher-level interfaces to the data elements; these classes include CVTerm, ModelCreator, ModelHistory, RDFAnnotationParser, and Date.

Components of an SBML annotation

The SBML annotation format consists of RDF-based content placed inside an <annotation> element attached to an SBML component such as Species, Compartment, etc. The following template illustrates the different parts of SBML annotations in XML form:

<SBML_ELEMENT +++ metaid="meta id" +++>
  +++
  <annotation>
    +++
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
             xmlns:dc="http://purl.org/dc/elements/1.1/"
             xmlns:dcterm="http://purl.org/dc/terms/"
             xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#"
             xmlns:bqbiol="http://biomodels.net/biology-qualifiers/"
             xmlns:bqmodel="http://biomodels.net/model-qualifiers/" >
      <rdf:Description rdf:about="#meta id">
        HISTORY
        <RELATION_ELEMENT>
          <rdf:Bag>
            <rdf:li rdf:resource="URI" />
            ...
          </rdf:Bag>
        </RELATION_ELEMENT>
        ...
      </rdf:Description>
      +++
    </rdf:RDF>
    +++
  </annotation>
  +++
</SBML_ELEMENT>

In the template above, the placeholder SBML_ELEMENT stands for the XML tag name of an SBML model component (e.g., model, reaction, etc.) and the placeholder meta id stands for the element's meta identifier, which is a field available on all SBML components derived from the SBase base object class. The dotted portions are optional, the symbol +++ is a placeholder for either no content or valid XML content that is not defined by this annotation scheme, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. The optional content HISTORY is a creation and modification history; in libSBML, this is stored using ModelHistory objects.

The placeholder RELATION_ELEMENT refers to a BioModels.net qualifier element name. This is an element in either the XML namespace "http://biomodels.net/model-qualifiers" (for model qualifiers) or "http://biomodels.net/biology-qualifiers" (for biological qualifier). The URI is a required data value that uniquely identifies a resource and data within that resource to which the annotation refers. (Since a URI is only a label, not an address, applications will often want a means of looking up the resource to which the URI refers. Providing the facilities for doing this is the purpose of MIRIAM Resources.)

The relation-resource pairs above are the "controlled vocabulary" terms that which CVTerm is designed to store and manipulate. The next section describes these parts in more detail. For more information about SBML annotations in general, please refer to Section 6 in the SBML Level 2 (Versions 2–4) or Level 3 specification documents.

The parts of a CVTerm

Annotations that refer to controlled vocabularies are managed in libSBML using CVTerm objects. A set of RDF-based annotations attached to a given SBML <annotation> element are read by RDFAnnotationParser and converted into a list of these CVTerm objects. Each CVTerm object instance stores the following components of an annotation:

  • The qualifier, which can be a BioModels.net "biological qualifier", a BioModels.net "model qualifier", or an unknown qualifier (as far as the CVTerm class is concerned). Qualifiers are used in MIRIAM to indicate the nature of the relationship between the object being annotated and the resource. In CVTerm, the qualifiers can be manipulated using the methods CVTerm::getQualifierType(), CVTerm::setQualifierType(), and related methods.

  • The resource, represented by a URI (which, we must remind developers, is not the same as a URL). In the CVTerm class, the resource component can be manipulated using the methods CVTerm::addResource() and CVTerm::removeResource().

Note that a CVTerm contains a single qualifier, but possibly more than one resource. This corresponds to the possibility of an annotation that points to multiple resources, all of which are qualified by the same BioModels.net qualifier. The CVTerm object class supports this by supporting a list of resources.

Detailed explanations of the qualifiers defined by BioModels.net can be found at http://biomodels.net/qualifiers.