libSBML Python API
5.8.0
|
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.
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.
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.
Public Member Functions | |
def | addResource |
def | clone |
def | getBiologicalQualifierType |
def | getModelQualifierType |
def | getNumResources |
def | getQualifierType |
def | getResources |
def | getResourceURI |
def | hasRequiredAttributes |
def | removeResource |
def | setBiologicalQualifierType |
def | setModelQualifierType |
def | setQualifierType |
def libsbml.CVTerm.addResource | ( | self, | |
args | |||
) |
Python method signature(s):
addResource(CVTerm self, string resource)int
Adds a resource reference to this CVTerm object.
The SBML Level 2 and Level 3 specifications define a simple standardized format for annotating models with references to controlled vocabulary terms and database identifiers that define and describe biological or other entities. This annotation format consists of RDF-based content placed inside an <annotation>
element attached to an SBML component such as Species, Compartment, etc.
The specific RDF element used in this SBML format for referring to external entities is <rdf:Description>
, with a <rdf:Bag>
element containing one or more <rdf:li>
elements. Each such element refers to a data item in an external resource; the resource and data item are together identified uniquely using a URI. The following template illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>
In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. 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 resource URI is a required data value that uniquely identifies a resource and data within that resource to which the annotation refers. The present method allows callers to add a reference to a resource URI with the same relationship to the enclosing SBML object. (In other words, the argument to this method is a resource URI as shown in the XML fragment above.) Resources are stored in this CVTerm object within an XMLAttributes object.
The relationship of this CVTerm to the enclosing SBML object can be determined using the CVTerm methods such as getModelQualifierType() and getBiologicalQualifierType().
resource | a string representing the URI of the resource and data item being referenced; e.g., 'http://www.geneontology.org/#GO:0005892' . |
def libsbml.CVTerm.clone | ( | self | ) |
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.
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.
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. Python method signature(s):
clone(CVTerm self)CVTerm
Creates and returns a deep copy of this CVTerm object.
def libsbml.CVTerm.getBiologicalQualifierType | ( | self | ) |
Python method signature(s):
getBiologicalQualifierType(CVTerm self)long
Returns the biological qualifier type of this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
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). Callers will typically use getQualifierType() to find out the type of qualifier relevant to this particular CVTerm object, then if it is a biological qualifier, use the present method to determine the specific qualifier. The set of known biological qualifiers is, at the time of this libSBML release, the following:
Any other BioModels.net qualifier found in the model is considered unknown by libSBML and reported as BQB_UNKNOWN.
def libsbml.CVTerm.getModelQualifierType | ( | self | ) |
Python method signature(s):
getModelQualifierType(CVTerm self)long
Returns the model qualifier type of this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
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). Callers will typically use getQualifierType() to find out the type of qualifier relevant to this particular CVTerm object, then if it is a model qualifier, use the present method to determine the specific qualifier. The set of known model qualifiers is, at the time of this libSBML release, the following:
Any other BioModels.net qualifier found in the model is considered unknown by libSBML and reported as BQM_UNKNOWN.
def libsbml.CVTerm.getNumResources | ( | self | ) |
Python method signature(s):
getNumResources(CVTerm self)long
Returns the number of resources for this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
The fragment above illustrates that there can be more than one resource referenced by a given relationship annotation (i.e., the resource URI values associated with a particular RELATION_ELEMENT). The present method returns a count of the resources stored in this CVTerm object.
def libsbml.CVTerm.getQualifierType | ( | self | ) |
Python method signature(s):
getQualifierType(CVTerm self)long
Returns the qualifier type of this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
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 present method returns a code identifying which one of these two relationship namespaces is being used; any other qualifier in libSBML is considered unknown (as far as the CVTerm class is concerned). Consequently, this method will return one of the following values:
The specific relationship of this CVTerm to the enclosing SBML object can be determined using the CVTerm methods such as getModelQualifierType() and getBiologicalQualifierType(). Callers will typically want to use the present method to find out which one of the other two methods to call to find out the specific relationship.
def libsbml.CVTerm.getResources | ( | self, | |
args | |||
) |
Python method signature(s):
getResources(CVTerm self)XMLAttributes getResources(CVTerm self)
XMLAttributes
Returns the resource references for this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
The resource URI values shown in the template above are stored internally in CVTerm objects using an XMLAttributes object. Each attribute stored inside the XMLAttributes will have the same name (specifically, "rdf:resource
") but a different value, and the value will be a resource URI shown in the XML template above.
A valid CVTerm entity must always have at least one resource and a value for the relationship qualifier.
def libsbml.CVTerm.getResourceURI | ( | self, | |
args | |||
) |
Python method signature(s):
getResourceURI(CVTerm self, long n)string
Returns the value of the nth resource for this CVTerm object.
The RDF element used in the SBML format for referring to external entities is<rdf:Description>
, with a
<rdf:Bag>
element inside of it containing one or
more <rdf:li>
elements. The following template
illustrates the structure:
<rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="resource URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description>In the template above, 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, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element.
The fragment above illustrates that there can be more than one resource referenced by a given relationship annotation (i.e., the resource URI values associated with a particular RELATION_ELEMENT). LibSBML stores all resource URIs in a single CVTerm object for a given relationship. Callers can use getNumResources() to find out how many resources are stored in this CVTerm object, then call this method to retrieve the nth resource URI.
n | the index of the resource to query |
def libsbml.CVTerm.hasRequiredAttributes | ( | self | ) |
Python method signature(s):
hasRequiredAttributes(CVTerm self)bool
Predicate returning True
if all the required elements for this CVTerm object have been set.
def libsbml.CVTerm.removeResource | ( | self, | |
args | |||
) |
Python method signature(s):
removeResource(CVTerm self, string resource)int
Removes a resource URI from the set of resources stored in this CVTerm object.
resource | a string representing the resource URI to remove; e.g., 'http://www.geneontology.org/#GO:0005892' . |
def libsbml.CVTerm.setBiologicalQualifierType | ( | self, | |
args | |||
) |
Python method signature(s):
setBiologicalQualifierType(CVTerm self, long type)int setBiologicalQualifierType(CVTerm self, string qualifier)
int
This method has multiple variants that differ in the arguments they accept. Each is described separately below.
Method variant with the following signature:
setBiologicalQualifierType(string qualifier)
Sets the of this CVTerm object.
qualifier | the string representing a biology qualifier |
Method variant with the following signature:
setBiologicalQualifierType(long type)
Sets the biology qualifier type of this CVTerm object.
type | the biology qualifier type. |
def libsbml.CVTerm.setModelQualifierType | ( | self, | |
args | |||
) |
Python method signature(s):
setModelQualifierType(CVTerm self, long type)int setModelQualifierType(CVTerm self, string qualifier)
int
This method has multiple variants that differ in the arguments they accept. Each is described separately below.
Method variant with the following signature:
setModelQualifierType(string qualifier)
Sets the value of this CVTerm object.
qualifier | the string representing a model qualifier |
Method variant with the following signature:
setModelQualifierType(long type)
Sets the model qualifier type of this CVTerm object.
type | the model qualifier type |
def libsbml.CVTerm.setQualifierType | ( | self, | |
args | |||
) |
Python method signature(s):
setQualifierType(CVTerm self, long type)int
Sets the qualifier code of this CVTerm object.
type | the qualifier type. The possible values returned by this function are: |