Detailed Description

A MIRIAM-compliant controlled vocabulary term.

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_t, ModelCreator_t, ModelHistory_t, RDFAnnotationParser_t, and Date_t.

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_t, Compartment_t, etc. A small change was introduced in SBML Level 2 Version 5 and SBML Level 3 Version 2 to permit nested annotations: lower Versions of the SBML specifications did not explicitly allow this. We first describe the different parts of SBML annotations in XML form for SBML Level 2 below Version 5 and SBML Level 3 below Version 2:

<SBML_ELEMENT +++ metaid="meta id" +++>
  +++
  <annotation>
    +++
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
             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_t 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_t 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). Note that these namespace URIs are only labels, and not actual Web locations, which means you cannot visit an address such as "http://biomodels.net/model-qualifiers" in your browser or try to have your application access it. Refer instead to the enumerations ModelQualifierType_t and BiolQualifierType_t for a list of the available relationship elements that can be used for RELATION_ELEMENT.

The URI is a required data value that uniquely identifies a resource and data within that resource to which the annotation refers. Again, being URIs, these do not refer to physical Web locations; nevertheless, applications will often want a means of finding the resource to which a given URI refers. Providing the facilities for this task is the purpose of MIRIAM Resources, described in detail online at http://biomodels.net/miriam) and also in the paper "MIRIAM Resources: tools to generate and resolve robust cross-references in Systems Biology", BMC Systems Biology, 58(1), 2007.

Finally, the following is the same template as above, but this time showing the nested content permitted by the most recent SBML specifications (SBML Level 2 Version 5 and Level 3 Version 2):

<SBML_ELEMENT +++ metaid="meta id" +++>
  +++
  <annotation>
    +++
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
             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" />
            NESTED_CONTENT
            ...
          </rdf:Bag>
        </RELATION_ELEMENT>
        ...
      </rdf:Description>
      +++
    </rdf:RDF>
    +++
  </annotation>
  +++
</SBML_ELEMENT>

The placeholder NESTED_CONTENT refers to other optional RDF elements such as "bqbiol:isDescribedBy" that describe a clarification or another annotation about the RELATION_ELEMENT in which it appears. Nested content allows one to, for example, describe protein modifications on species, or to add evidence codes for an annotation. Nested content relates to its containing RELATION_ELEMENT, not the other way around. It qualifies it, but does not change its meaning. As such, ignoring a NESTED_CONTENT does not affect the information provided by the containing RELATION_ELEMENT.

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_t

Annotations that refer to controlled vocabularies are managed in libSBML using CVTerm_t objects. The relation-resource pairs discussed in the previous section are the "controlled vocabulary" terms that CVTerm_t is designed to store and manipulate. A set of RDF-based annotations attached to a given SBML <annotation> element are read by RDFAnnotationParser_t and converted into a list of these CVTerm_t objects. Each CVTerm_t 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_t 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_t, the qualifiers can be manipulated using the methods CVTerm_t::getQualifierType(), CVTerm_t::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_t class, the resource component can be manipulated using the methods CVTerm_t::addResource() and CVTerm_t::removeResource().

Note that a CVTerm_t 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_t object class supports this by supporting a list of resources.

Detailed explanations of the qualifiers defined by BioModels.net can be found at http://co.mbine.org/standards/qualifiers.

Examples:: addCVTerms.c, addingEvidenceCodes_1.c, and addingEvidenceCodes_2.c.

Public Member Functions
BiolQualifierType_t	BiolQualifierType_fromString (const char *s)
	This method takes a string and returns a biol qualifier representing the string. More...

const char *	BiolQualifierType_toString (BiolQualifierType_t type)
	This method takes a biol qualifier type code and returns a string representing the code. More...

int	CVTerm_addNestedCVTerm (CVTerm_t cvt, const CVTerm_t term)
	Adds a copy of the given CVTerm_t to the list of nested CVTerm_t's within this CVTerm_t structure. More...

int	CVTerm_addResource (CVTerm_t term, const char resource)
	Adds a resource to the CVTerm_t. More...

CVTerm_t *	CVTerm_clone (const CVTerm_t *term)
	Creates a deep copy of the given CVTerm_t structure. More...

CVTerm_t *	CVTerm_createFromNode (const XMLNode_t *node)
	Create a new CVTerm_t from the given XMLNode_t and returns a pointer to it. More...

CVTerm_t *	CVTerm_createWithQualifierType (QualifierType_t type)
	Creates a new CVTerm_t with the given QualifierType_t value `type` and returns a pointer to it. More...

void	CVTerm_free (CVTerm_t *c)
	Frees the given CVTerm_t structure. More...

BiolQualifierType_t	CVTerm_getBiologicalQualifierType (CVTerm_t *term)
	Takes a CVTerm_t structure and returns the BiolQualifierType_t. More...

const List_t *	CVTerm_getListNestedCVTerms (const CVTerm_t *cvt)
	Returns a list of CVTerm_t structures contained within this CVTerm_t structure. More...

ModelQualifierType_t	CVTerm_getModelQualifierType (CVTerm_t *term)
	Takes a CVTerm_t structure and returns the ModelQualifierType_t type. More...

const CVTerm_t *	CVTerm_getNestedCVTerm (const CVTerm_t *cvt, unsigned int n)
	Returns the nth CVTerm_t in the list of CVTerm_t's of this CVTerm_t structure. More...

unsigned int	CVTerm_getNumNestedCVTerms (const CVTerm_t *cvt)
	Returns the number of CVTerm_t structures nested within this CVTerm_t structure. More...

unsigned int	CVTerm_getNumResources (CVTerm_t *term)
	Returns the number of resources for this CVTerm_t. More...

QualifierType_t	CVTerm_getQualifierType (CVTerm_t *term)
	Takes a CVTerm_t structure and returns its QualifierType_t type. More...

XMLAttributes_t *	CVTerm_getResources (CVTerm_t *term)
	Takes a CVTerm_t structure and returns the resources. More...

char *	CVTerm_getResourceURI (CVTerm_t *term, unsigned int n)
	Returns the value of the nth resource for this CVTerm_t. More...

int	CVTerm_hasRequiredAttributes (CVTerm_t *term)
	Checks if the CVTerm_t has all the required attributes. More...

CVTerm_t *	CVTerm_removeNestedCVTerm (CVTerm_t *cvt, unsigned int n)
	Removes the nth CVTerm_t in the list of CVTerm_t's of this CVTerm_t structure and returns a pointer to it. More...

int	CVTerm_removeResource (CVTerm_t term, const char resource)
	Removes a resource from the CVTerm_t. More...

int	CVTerm_setBiologicalQualifierType (CVTerm_t *term, BiolQualifierType_t type)
	Sets the BiolQualifierType_t of this CVTerm_t. More...

int	CVTerm_setBiologicalQualifierTypeByString (CVTerm_t term, const char qualifier)
	Sets the BiolQualifierType_t of this CVTerm_t. More...

int	CVTerm_setModelQualifierType (CVTerm_t *term, ModelQualifierType_t type)
	Sets the ModelQualifierType_t of this CVTerm_t. More...

int	CVTerm_setModelQualifierTypeByString (CVTerm_t term, const char qualifier)
	Sets the ModelQualifierType_t of this CVTerm_t. More...

int	CVTerm_setQualifierType (CVTerm_t *term, QualifierType_t type)
	Sets the QualifierType_t of this CVTerm_t. More...

ModelQualifierType_t	ModelQualifierType_fromString (const char *s)
	This method takes a string and returns a model qualifier representing the string. More...

const char *	ModelQualifierType_toString (ModelQualifierType_t type)
	This method takes a model qualifier type code and returns a string representing the code. More...

Member Function Documentation

BiolQualifierType_t BiolQualifierType_fromString ( const char * s )

This method takes a string and returns a biol qualifier representing the string.

This method takes a string as argument and returns a biol qualifier type corresponding to that string. For example, passing it the string "hasVersion" will return the qualifier BQB_HAS_VERSION.

Parameters

s	the string to translate to a BiolQualifierType_t value.

Returns: a libSBML qualifier enumeration value for the given human readable qualifier name.

const char * BiolQualifierType_toString ( BiolQualifierType_t type )

This method takes a biol qualifier type code and returns a string representing the code.

This method takes a biol qualifier type as argument and returns a string name corresponding to that code. For example, passing it the qualifier BQB_HAS_VERSION will return the string "hasVersion".

Parameters

type	the BiolQualifierType_t value to translate.

Returns: a human readable qualifier name for the given type.

Note: The caller does not own the returned string and is therefore not allowed to modify it.

int CVTerm_addNestedCVTerm	(	CVTerm_t *	cvt,
		const CVTerm_t *	term
	)

Adds a copy of the given CVTerm_t to the list of nested CVTerm_t's within this CVTerm_t structure.

Parameters

cvt	the structure to add the CVTerm_t to.
term	the CVTerm_t to assign.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int CVTerm_addResource	(	CVTerm_t *	term,
		const char *	resource
	)

Adds a resource to the CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
resource	string representing the resource e.g. http://www.geneontology.org/#GO:0005892

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: this method adds the name "rdf:resource" to the attribute prior to adding it to the resources in this CVTerm_t.

Examples:: addCVTerms.c, addingEvidenceCodes_1.c, and addingEvidenceCodes_2.c.

CVTerm_t * CVTerm_clone ( const CVTerm_t * term )

Creates a deep copy of the given CVTerm_t structure.

Parameters

term	the CVTerm_t structure to be copied.

Returns: a (deep) copy of the given CVTerm_t structure.

CVTerm_t * CVTerm_createFromNode ( const XMLNode_t * node )

Create a new CVTerm_t from the given XMLNode_t and returns a pointer to it.

RDFAnnotations within a model are stored as a List_t of CVTerm_t's. This allows the user to interact with the CVTerm_t's directly. When LibSBML reads in a model containing RDFAnnotations it parses them into a List of CVTerm_t's and when writing a model it parses the CVTerm_t's into the appropriate annotation structure. This function creates a CVTerm_t from the XMLNode_t supplied.

Parameters

node	an XMLNode_t representing a CVTerm_t.

Returns: a pointer to the newly created CVTerm_t structure.

Note: this method assumes that the XMLNode_t is of the correct form

CVTerm_t * CVTerm_createWithQualifierType ( QualifierType_t type )

Creates a new CVTerm_t with the given QualifierType_t value type and returns a pointer to it.

The possible QualifierTypes are MODEL_QUALIFIER and BIOLOGICAL_QUALIFIER.

Parameters

type	a QualifierType_t.

Returns: a pointer to the newly created CVTerm_t structure.

Examples:: addCVTerms.c, addingEvidenceCodes_1.c, and addingEvidenceCodes_2.c.

void CVTerm_free ( CVTerm_t * c )

Frees the given CVTerm_t structure.

Parameters

c	the CVTerm_t structure to be freed.

BiolQualifierType_t CVTerm_getBiologicalQualifierType ( CVTerm_t * term )

Takes a CVTerm_t structure and returns the BiolQualifierType_t.

Parameters

term	the CVTerm_t structure whose BiolQualifierType_t value is sought.

Returns: the BiolQualifierType_t value of this CVTerm_t or BQB_UNKNOWN (default).

const List_t * CVTerm_getListNestedCVTerms ( const CVTerm_t * cvt )

Returns a list of CVTerm_t structures contained within this CVTerm_t structure.

Parameters

cvt	the structure to getListNestedCVTerms from.

Returns: the list of CVTerm_t's for this CVTerm_t structure.

ModelQualifierType_t CVTerm_getModelQualifierType ( CVTerm_t * term )

Takes a CVTerm_t structure and returns the ModelQualifierType_t type.

Parameters

term	the CVTerm_t structure whose ModelQualifierType_t is sought.

Returns: the ModelQualifierType_t value of this CVTerm_t or BQM_UNKNOWN (default).

const CVTerm_t * CVTerm_getNestedCVTerm	(	const CVTerm_t *	cvt,
		unsigned int	n
	)

Returns the nth CVTerm_t in the list of CVTerm_t's of this CVTerm_t structure.

Parameters

cvt	the structure to get CVTerm_t's from.
n	unsigned int the index of the CVTerm_t to retrieve.

Returns: the nth CVTerm_t in the list of CVTerm_t's for this CVTerm_t structure or NULL if no such object exists.

unsigned int CVTerm_getNumNestedCVTerms ( const CVTerm_t * cvt )

Returns the number of CVTerm_t structures nested within this CVTerm_t structure.

Parameters

cvt	the structure to get the number of nested CVTerms from.

Returns: the number of CVTerm_t structures nested within this CVTerm_t structure.

Note: this does not recurse through potentially nested CVTerm_t objects within a given nested CVTerm_t. It returns the number of terms immediately nested within this CVTerm_t.

unsigned int CVTerm_getNumResources ( CVTerm_t * term )

Returns the number of resources for this CVTerm_t.

Parameters

term	the CVTerm_t structure whose resources are sought.

Returns: the number of resources in the set of XMLAttributes_t of this CVTerm_t.

QualifierType_t CVTerm_getQualifierType ( CVTerm_t * term )

Takes a CVTerm_t structure and returns its QualifierType_t type.

Parameters

term	the CVTerm_t structure whose QualifierType_t value is sought.

Returns: the QualifierType_t value of this CVTerm_t or UNKNOWN_QUALIFIER (default).

XMLAttributes_t * CVTerm_getResources ( CVTerm_t * term )

Takes a CVTerm_t structure and returns the resources.

Parameters

term	the CVTerm_t structure whose resources are sought.

Returns: the XMLAttributes_t that store the resources of this CVTerm_t.

char * CVTerm_getResourceURI	(	CVTerm_t *	term,
		unsigned int	n
	)

Returns the value of the nth resource for this CVTerm_t.

Parameters

term	the CVTerm_t structure.
n	the index of the resource to query.

Returns: string representing the value of the nth resource in the set of XMLAttributes_t of this CVTerm_t.

Note: Since the values of the resource attributes in a CVTerm_t are URIs this is a convenience function to facilitate interaction with the CVTerm_t structure.

int CVTerm_hasRequiredAttributes ( CVTerm_t * term )

Checks if the CVTerm_t has all the required attributes.

Parameters

term	the CVTerm_t structure.

Returns: 1 (true) if this CVTerm_t has all the required elements, otherwise 0 (false) will be returned, including if an invalid CVTerm_t was provided.

CVTerm_t * CVTerm_removeNestedCVTerm	(	CVTerm_t *	cvt,
		unsigned int	n
	)

Removes the nth CVTerm_t in the list of CVTerm_t's of this CVTerm_t structure and returns a pointer to it.

Parameters

cvt	the structure to get CVTerm_t's from.
n	unsigned int the index of the CVTerm_t to retrieve.

Returns: a pointer to the nth CVTerm_t in the list of CVTerm_t's for this CVTerm_t structure.

int CVTerm_removeResource	(	CVTerm_t *	term,
		const char *	resource
	)

Removes a resource from the CVTerm_t.

Parameters

term	the CVTerm_t structure.
resource	string representing the resource e.g. http://www.geneontology.org/#GO:0005892

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int CVTerm_setBiologicalQualifierType	(	CVTerm_t *	term,
		BiolQualifierType_t	type
	)

Sets the BiolQualifierType_t of this CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
type	the BiolQualifierType_t.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: if the QualifierType_t for this structure is not BIOLOGICAL_QUALIFIER then the BiolQualifierType_t will default to BQB_UNKNOWN.

Examples:: addCVTerms.c, addingEvidenceCodes_1.c, and addingEvidenceCodes_2.c.

int CVTerm_setBiologicalQualifierTypeByString	(	CVTerm_t *	term,
		const char *	qualifier
	)

Sets the BiolQualifierType_t of this CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
qualifier	the string representing a biol qualifier.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: if the QualifierType_t for this structure is not BIOLOGICAL_QUALIFIER then the BiolQualifierType_t will default to BQB_UNKNOWN.

int CVTerm_setModelQualifierType	(	CVTerm_t *	term,
		ModelQualifierType_t	type
	)

Sets the ModelQualifierType_t of this CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
type	the ModelQualifierType_t.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: if the QualifierType_t for this structure is not MODEL_QUALIFIER then the ModelQualifierType_t will default to BQM_UNKNOWN.

int CVTerm_setModelQualifierTypeByString	(	CVTerm_t *	term,
		const char *	qualifier
	)

Sets the ModelQualifierType_t of this CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
qualifier	the string representing a model qualifier.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: if the QualifierType_t for this structure is not MODEL_QUALIFIER then the ModelQualifierType_t will default to BQM_UNKNOWN.

int CVTerm_setQualifierType	(	CVTerm_t *	term,
		QualifierType_t	type
	)

Sets the QualifierType_t of this CVTerm_t.

Parameters

term	the CVTerm_t structure to set.
type	the QualifierType_t.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

ModelQualifierType_t ModelQualifierType_fromString ( const char * s )

This method takes a string and returns a model qualifier representing the string.

This method takes a string as argument and returns a model qualifier type corresponding to that string. For example, passing it the string "isDescribedBy" will return the qualifier BQM_IS_DESCRIBED_BY.

Parameters

s	the string to translate to a ModelQualifierType_t value.

Returns: a libSBML qualifier enumeration value for the given human readable qualifier name.

const char * ModelQualifierType_toString ( ModelQualifierType_t type )

This method takes a model qualifier type code and returns a string representing the code.

This method takes a model qualifier type as argument and returns a string name corresponding to that code. For example, passing it the qualifier BQM_IS_DESCRIBED_BY will return the string "isDescribedBy".

Parameters

type	the ModelQualifierType_t value to translate.

Returns: a human readable qualifier name for the given qualifier type.

Note: The caller does not own the returned string and is therefore not allowed to modify it.

Detailed Description

Components of an SBML annotation

The parts of a CVTerm_t

Public Member Functions

Member Function Documentation