libSBML Python API
5.11.0
|
The libSBML “comp” extension implements support for the SBML Level 3 Hierarchical Model Composition package.
In the context of SBML, hierarchical model composition refers to
the ability to include models as submodels inside another model. The goal is
to support the ability of modelers and software tools to do such things as
(1) decompose larger models into smaller ones, as a way to manage complexity;
(2) incorporate multiple instances of a given model within one or more
enclosing models, to avoid literal duplication of repeated elements; and (3)
create libraries of reusable, tested models, much as is done in software
development and other engineering fields. SBML Level 3 Version 1 Core, by
itself, has no direct support for allowing a model to include other models as
submodels. The Level 3 Hierarchical Model Composition package adds the
missing capabilities. The figure below illustrates some of the scenarios
targeted by this package.
This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Hierarchical Model Composition (“comp”) package. If you are developing software that uses “comp”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).
Specification (in PDF format) | Known issues |
---|---|
![]() |
![]() |
Classes | |
class | libsbml.CompExtension |
comp
Base extension class for the package. More... | |
class | libsbml.CompFlatteningConverter |
comp
'Flattens' a model, removing composition. More... | |
class | libsbml.CompModelPlugin |
comp
Extension of Model. More... | |
class | libsbml.CompPkgNamespaces |
comp
SBMLNamespaces extension for the package. More... | |
class | libsbml.CompSBasePlugin |
comp
Extension of SBase. More... | |
class | libsbml.CompSBMLDocumentPlugin |
comp
Extension of SBMLDocument. More... | |
class | libsbml.Deletion |
comp
Deletion of an object from a submodel. More... | |
class | libsbml.ExternalModelDefinition |
comp
A reference to an externally-defined model. More... | |
class | libsbml.ListOfDeletions |
comp
A list of Deletion objects. More... | |
class | libsbml.ListOfExternalModelDefinitions |
comp
A list of ExternalModelDefinition objects. More... | |
class | libsbml.ListOfModelDefinitions |
comp
A list of ModelDefinition objects. More... | |
class | libsbml.ListOfPorts |
comp
A list of Port objects. More... | |
class | libsbml.ListOfReplacedElements |
comp
A list of ReplacedElement objects. More... | |
class | libsbml.ListOfSubmodels |
comp
A list of Submodel objects. More... | |
class | libsbml.ModelDefinition |
comp
A model used in model composition. More... | |
class | libsbml.Port |
comp
An interface to be used in composition. More... | |
class | libsbml.ReplacedBy |
comp
Indicates an object replaced by another. More... | |
class | libsbml.ReplacedElement |
comp
Indicates an object replaces another. More... | |
class | libsbml.Replacing |
comp
Convenience class. More... | |
class | libsbml.SBaseRef |
comp
Base class for references to objects. More... | |
class | libsbml.SBMLFileResolver |
comp
Resolves documents stored on a file system. More... | |
class | libsbml.SBMLResolver |
comp
Base class for SBML resolvers. More... | |
class | libsbml.SBMLResolverRegistry |
comp
Registry of all SBML resolvers. More... | |
class | libsbml.SBMLUri |
comp
Utility class for handling URIs. More... | |
class | libsbml.Submodel |
comp
A model instance inside another model. More... | |
Functions | |
def | libsbml.CompSBasePlugin.__init__ (self, args) |
comp
Extension of SBase. More... | |
def | libsbml.CompModelPlugin.__init__ (self, args) |
comp
Extension of Model. More... | |
def | libsbml.CompSBMLDocumentPlugin.__init__ (self, args) |
comp
Extension of SBMLDocument. More... | |
def | libsbml.SBMLUri.__init__ (self, args) |
comp
Utility class for handling URIs. More... | |
def | libsbml.SBMLResolver.__init__ (self, args) |
comp
Base class for SBML resolvers. More... | |
def | libsbml.SBMLFileResolver.__init__ (self, args) |
comp
Resolves documents stored on a file system. More... | |
def | libsbml.CompFlatteningConverter.__init__ (self, args) |
comp
'Flattens' a model, removing composition. More... | |
def | libsbml.SBaseRef.__init__ (self, args) |
comp
Base class for references to objects. More... | |
def | libsbml.Deletion.__init__ (self, args) |
comp
Deletion of an object from a submodel. More... | |
def | libsbml.ExternalModelDefinition.__init__ (self, args) |
comp
A reference to an externally-defined model. More... | |
def | libsbml.ModelDefinition.__init__ (self, args) |
comp
A model used in model composition. More... | |
def | libsbml.Port.__init__ (self, args) |
comp
An interface to be used in composition. More... | |
def | libsbml.ReplacedBy.__init__ (self, args) |
comp
Indicates an object replaced by another. More... | |
def | libsbml.ReplacedElement.__init__ (self, args) |
comp
Indicates an object replaces another. More... | |
def | libsbml.Submodel.__init__ (self, args) |
comp
A model instance inside another model. More... | |
def | libsbml.ListOfDeletions.clone (self) |
comp
A list of Deletion objects. More... | |
def | libsbml.ListOfExternalModelDefinitions.clone (self) |
comp
A list of ExternalModelDefinition objects. More... | |
def | libsbml.ListOfModelDefinitions.clone (self) |
comp
A list of ModelDefinition objects. More... | |
def | libsbml.ListOfPorts.clone (self) |
comp
A list of Port objects. More... | |
def | libsbml.ListOfReplacedElements.clone (self) |
comp
A list of ReplacedElement objects. More... | |
def | libsbml.ListOfSubmodels.clone (self) |
comp
A list of Submodel objects. More... | |
def | libsbml.SBMLResolverRegistry.getInstance () |
comp
Registry of all SBML resolvers. More... | |
def | libsbml.CompExtension.getPackageName () |
comp
Base extension class for the package. More... | |
def | libsbml.Replacing.getSubmodelRef (self) |
comp
Convenience class. More... | |
The libSBML “comp” extension implements support for the SBML Level 3 Hierarchical Model Composition package.
In the context of SBML, hierarchical model composition refers to
the ability to include models as submodels inside another model. The goal is
to support the ability of modelers and software tools to do such things as
(1) decompose larger models into smaller ones, as a way to manage complexity;
(2) incorporate multiple instances of a given model within one or more
enclosing models, to avoid literal duplication of repeated elements; and (3)
create libraries of reusable, tested models, much as is done in software
development and other engineering fields. SBML Level 3 Version 1 Core, by
itself, has no direct support for allowing a model to include other models as
submodels. The Level 3 Hierarchical Model Composition package adds the
missing capabilities. The figure below illustrates some of the scenarios
targeted by this package.
This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Hierarchical Model Composition (“comp”) package. If you are developing software that uses “comp”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).
Specification (in PDF format) | Known issues |
---|---|
![]() |
![]() |
def libsbml.CompSBasePlugin.__init__ | ( | self, | |
args | |||
) |
The CompSBasePlugin class inherits from the SBasePlugin class, and codifies the extentions to the SBase class defined in the Hierarchical Model Composition package (“comp”). This extention allows the modeler to define one or more submodel elements which the parent SBase object replaces, and/or a single submodel element which replaces the parent SBase object. This is accomplished through the addition of an optional ListOfReplacedElements child, which may contain one or more ReplacedElement objects, each of which references a submodel object to be replaced by the containing SBase object, and through the addition of a single optional ReplacedBy child, which references a submodel object which is to replace the containing SBase object. If a single SBase element both contains a ListOfReplacedElements and has a ReplacedBy child, it and all the referenced ReplacedElement objects are to be replaced by the object referenced by the ReplacedBy element.
This method has multiple variants; they differ in the arguments they accept.
__init__(string uri, string prefix, CompPkgNamespaces compns) CompSBasePlugin __init__(CompSBasePlugin orig) CompSBasePlugin
Each variant is described separately below.
CompSBasePlugin(stringuri, stringprefix, CompPkgNamespaces compns)
Constructor.
CompSBasePlugin(CompSBasePlugin orig)
Copy constructor. Creates a copy of this CompSBasePlugin object.
def libsbml.CompModelPlugin.__init__ | ( | self, | |
args | |||
) |
The CompModelPlugin class inherits from the SBMLSBasePlugin class, and codifies the extentions to the Model class defined in the SBML Level 3 Hierarchical Model Composition package (“comp”). This extention allows a Model to define Submodels (other Models that are instantiated as new parts of the parent Model), and Ports, a defined interface for including the given Model as a Submodel of a different Model.
Submodels are stored in an optional child ListOfSubmodels object, which, if present, must contain one or more Submodel objects. All of the Submodels present in the ListOfSubmodels are defined to be instantiated in the 'complete' Model.
Ports are stored in an optional child ListOfPorts object, which, if present, must contain one or more Port objects. All of the Ports present in the ListOfPorts collectively define the 'port interface' of the Model.
This method has multiple variants; they differ in the arguments they accept.
__init__(string uri, string prefix, CompPkgNamespaces compns) CompModelPlugin __init__(CompModelPlugin orig) CompModelPlugin
Each variant is described separately below.
CompModelPlugin(CompModelPlugin orig)
Copy constructor. Creates a copy of this CompModelPlugin object.
CompModelPlugin(stringuri, stringprefix, CompPkgNamespaces compns)
Constructor.
def libsbml.CompSBMLDocumentPlugin.__init__ | ( | self, | |
args | |||
) |
comp Extension of SBMLDocument.
The CompSBMLDocumentPlugin class inherits from the SBMLDocumentPlugin class, and codifies the extentions to the SBMLDocument class defined in the SBML Level 3 Hierarchical Model Composition
package (“comp”). This extention allows multiple Model objects to be defined in a single SBMLDocument, stored in an optional child ListOfModelDefinitions object, as well as define references to Model objects in other files, stored in the optional child ListOfExternalModelDefinitions object. These model definitions, if present, allow Submodel objects to reference other Models to instantiate.
The presence of ModelDefinitions and ExternalModelDefinitions in an SBMLDocument does not change the default Model in the file. If a SBMLDocument is submitted somewhere to be simulated, it is still the <model>
child of the <sbml>
element that should be simulated.
In addition, as all packages do, the CompSBMLDocumentPlugin defines a required flag named required
, which indicates whether “comp” constructs can be used to change the core mathematics of the <model>
child of the <sbml>
element. Because they can, this attribute must be set True
.
This method has multiple variants; they differ in the arguments they accept.
__init__(string uri, string prefix, CompPkgNamespaces compns) CompSBMLDocumentPlugin __init__(CompSBMLDocumentPlugin orig) CompSBMLDocumentPlugin
Each variant is described separately below.
CompSBMLDocumentPlugin(CompSBMLDocumentPlugin orig)
Copy constructor. Creates a copy of this CompSBMLDocumentPlugin object.
CompSBMLDocumentPlugin(stringuri, stringprefix, CompPkgNamespaces compns)
Constructor.
def libsbml.SBMLUri.__init__ | ( | self, | |
args | |||
) |
comp Utility class for handling URIs.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
This class implements functionality for parsing URIs and extracting information about them.
This method has multiple variants; they differ in the arguments they accept.
__init__(string uri) SBMLUri __init__(SBMLUri orig) SBMLUri
Each variant is described separately below.
SBMLUri(SBMLUri orig)
Copy constructor. Creates a copy of an SBMLUri object.
orig | the SBMLUri object to copy. |
ValueError | Thrown if the argument orig is None . |
SBMLUri(string uri)
Creates a new SBMLUri from the given string URI.
def libsbml.SBMLResolver.__init__ | ( | self, | |
args | |||
) |
comp Base class for SBML resolvers.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
The SBMLResolver class is the base class for the various SBML resolvers: facilities that take a unique identifier as input and return the document associated with that identifier. In SBML, resolvers come into play with the SBML Level 3 Hierarchical Model Composition package; this package includes features that allow a model to be composed from pieces that are external to a given SBML document, which implies the need to be able to identify and locate those external pieces. The SBMLResolver class and its subclasses provide facilities for software applications to be able to do these tasks.
LibSBML provides a number of built-in resolvers, and applications can create their own by subclassing SBMLResolver and following the examples of the existing resolvers. The following are the built-in resolvers in libSBML 5.11.0:
More resolvers may be provided by libSBML in the future. Application authors may also write their own.
This method has multiple variants; they differ in the arguments they accept.
__init__() SBMLResolver __init__(SBMLResolver c) SBMLResolver
Each variant is described separately below.
SBMLResolver(SBMLResolver c)
Copy constructor. Creates a copy of an SBMLResolver object.
c | the SBMLResolver object to copy. |
ValueError | Thrown if the argument orig is None . |
SBMLResolver()
Creates a new SBMLResolver object.
def libsbml.SBMLFileResolver.__init__ | ( | self, | |
args | |||
) |
comp Resolves documents stored on a file system.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
In SBML, resolvers come into play with the SBML Level 3 Hierarchical Model Composition package (“comp”); this package includes features that allow a model to be composed from pieces that are external to a given SBML document, which implies the need to be able to identify and locate those external pieces. The identifiers used in “comp” are URIs (Uniform Resource Identifiers).
SBMLFileResolver is a class implementing the ability to resolve URIs to files. It works on the local file system only. It can resolve relative and absolute paths, and directories to be searched can be specified using the methodsSBMLFileResolver.addAdditionalDir() and SBMLFileResolver.clearAdditionalDirs().
This method has multiple variants; they differ in the arguments they accept.
__init__() SBMLFileResolver __init__(SBMLFileResolver c) SBMLFileResolver
Each variant is described separately below.
SBMLFileResolver()
Creates a new SBMLFileResolver object.
SBMLFileResolver(SBMLFileResolver c)
Copy constructor. Creates a copy of an SBMLFileResolver object.
c | the SBMLFileResolver object to copy. |
ValueError | Thrown if the argument orig is None . |
def libsbml.CompFlatteningConverter.__init__ | ( | self, | |
args | |||
) |
comp 'Flattens' a model, removing composition.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
This converter translates a hierarchical model defined with the SBML Level 3 Hierarchical Model Composition package to a so-called 'flattened' version of the same model. A 'flattened' model is one that results from interpreting the hierarchical structure and creating an equivalent model that does not use any Hierarchical Model Composition package constructs; all of the mathematics of the model remain as intended, but the hierarchical structure is removed. CompFlatteningConverter achieves this by performing the following actions on a model:
Each submodel is instantiated; that is, a copy of every Model object referenced by every Submodel object is created. This is a recursive process: if the instantiated Model itself has Submodel children, they are also instantiated.
The identifier of every component object in every Model that is instantiated is modified by prepending a prefix to it, to make the identifier unique in the overall flattened SBML model. The prefix consists of the Submodel object identifier, plus a small integer if necessary to ensure uniqueness, plus two underscore characters ('__'
). Typically, this results in a final identifier of the form SubmodelIdentifier__ObjectIdentifier, where ObjectIdentifier is the object's original identifier and SubmodelIdentifier__ is the prefix. The same process is applied to metaid (meta-identifier) values of every component object as well.
All deleted elements are removed from the model and all instantiated submodels.
All replaced elements are removed from the model and all instantiated submodels.
All references to replaced elements are changed to point to the replacement element instead.
All remaining elements are placed in a single Model object; this Model object is made the new child of the SBMLDocument container. The original Model, ModelDefinition, and ExternalModelDefinition objects are all deleted.
Note an implication of this process is that if conversion is successful, all old pointers to the SBMLDocument object's Model object as well as all of its children, will be rendered obsolete, and will no longer work.
'flatten comp': Possible values are 'True'
or 'False'
. Setting the option to True
(the default) means enable the flattening converter.
'abortIfUnflattenable': Possible values are 'all'
, 'requiredOnly'
(the default), or 'none'
. Controls what happens upon encountering an SBML Level 3 package with no flattener implementation.
'stripUnflattenablePackages': Possible values are 'True'
or 'False'
(the default). Controls whether the constructs of Level 3 packages with no flattener implementation are stripped from the output.
'basePath': The value must be a string representing the path where the converter should search for any ExternalModelDefinition objects. (Default value: '.', meaning, the current directory.)
'leavePorts': Possible values are 'True'
or 'False'
(the default). Controls what happens to Port constructs in the output.
'listModelDefinitions': Possible values are 'True'
or 'False'
(the default). Controls what happens to ModelDefinition and ExternalModelDefinition objects in the final output.
'True'
(the default) or 'False'
. Controls whether whether libSBML validates the model before attempting to flatten it. The following sections examine in detail the options understood by CompFlatteningConverter and their effects on the flattening process.
If other SBML Level 3 packages are used in the SBMLDocument, the same rules apply to each package's constructs if an implementation of the flattener exists for that Level 3 package. If no implementation exists, the behavior of this CompFlatteningConverter depends on the values of the options 'abortIfUnflattenable' and 'stripUnflattenablePackages'. Specifically:
The option 'abortIfUnflattenable' controls whether the flattening process is abandoned. The following are the possible values for this option and their meanings:
If the 'abortIfUnflattenable' option is set to 'all'
, then if any construct is found for a package that has no flattening algorithm available, the converter will abort, return failure, and avoid changing the original SBMLDocument object.
If 'abortIfUnflattenable' is set to 'requiredOnly'
(the default), then if any SBML Level 3 package construct is found for a package that is labeled 'required=true'
and for which no flattening algorithm is available, the converter will abort, return failure, and avoid changing the original SBMLDocument object. SBML Level 3 package constructs from packages set 'required=false'
for which no flattening algorithm is implemented will be ignored and the constructs will be kept or removed depending on the value of the 'stripUnflattenablePackages' option described below.
If 'abortIfUnflattenable' is set to 'none'
, constructs from all unflattenable SBML Level 3 packages will be ignored, and their constructs will be kept or removed depending on the value of the 'stripUnflattenablePackages' option.
The option 'stripUnflattenablePackages' controls whether SBML Level 3 package constructs are removed from the final flattened model. The following are the possible values for this option and their meanings:
If the option 'stripUnflattenablePackages' is set to 'True'
, and the option 'abortIfUnflattenable' has the value 'requireOnly'
or 'none'
, then CompFlatteningConverter will remove all constructs belonging to packages that lack a flattening converter. The XML namespace declaration for unflattenable SBML Level 3 packages will also be removed.
If the option 'stripUnflattenablePackages' is set to 'False'
(the default), CompFlatteningConverter will leave any package constructs that cannot be flattened due to the lack of a flattening implementation. These Level 3 package constructs will remain in the final model. Note that any package constructs from an instantiated Submodel object that was not a child of a retained component will be lost (because the SBML component where it was located was removed from the final, flattened model).
The following are other, general options offered by CompFlatteningConverter:
'
.').'False'
(the default), the flattened model will have no Port objects in it. Conversely, if 'leavePorts' is set to 'True'
, any Port objects not referenced by any Replacement or Deletion will be left in the resulting flattened Model.'False'
(the default), no ModelDefinition or ExternalModelDefinition objects will be present in the flattened SBMLDocument. If 'listModelDefinitions' is set to 'True'
, they will remain, although they will no longer be referenced by any Submodel in the flattened Model child of the SBMLDocument.'True'
(the default), the SBMLDocument will first be validated before flattening is attempted. If there are any validation errors, those errors will be logged with the SBMLDocument, which will remain otherwise unchanged, and the conversion process will return a failure code. Similarly, if the flattened Model is not valid, those validation errors will be added to the SBMLDocument, which will remain otherwise unchanged, and the conversion attempt will return failure. Conversely, if the option 'performValidation' is set to 'False'
, the SBMLDocument will be flattened regardless of any validation errors. The conversion may yet fail if insurmountable errors are encountered in the course of trying to flatten the model (for instance, if an element is replaced by something that does not exist), but no separate validation steps are performed.Note that if both the option 'leavePorts' and 'listModelDefinitions' are set to 'False'
(which they are by default), the Hierarchical Model Composition namespace will be removed from the resulting SBMLDocument.
In this section, we present a complete example of a program that can take an SBML model containing Level 3 Hierarchical Model Composition constructs and flatten it to a plain SBML Level 3 model. A version of this program is available in the libSBML distribution's examples/python/comp
directory as the program named flattenModel.py 'flattenModel.py'. The example XML models shown below are the same models as given in sections 4.1–4.2 in the specification document for SBML Level 3 Hierarchical Model Composition.
For brevity, we do not give the general scaffolding that a real program would have (such as inclusion of header files, command-line argument checks, additional error checks throughout the code, and so on), and focus instead on the parts relevant to an application using the libSBML 'comp' extension.
First, our program checks that this copy of libSBML has the 'comp' extension available. The process for doing that simply involves a call to the extension registry in libSBML:
Next, we read the SBML input file. For this example, we simply assume that the path to the file is given as the first argument to the program; a real program would perform more sophisticated command-line argument processing and error checking.
Continuing, we set up options for the call to the converter. The use of ConversionProperties and the general scheme behind conversion options is explained further below; for the purposes of this example, it is enough to know that the following are the basic lines of code needed to obtain a copy of a libSBML converter object that will invoke CompFlatteningConverter:
Now comes the actual invocation of CompFlatteningConverter. As always, it is critical to check for possible errors by checking the status code returned by the call; we do this in the code below too.
If successful, we simply write out the resulting flattened model to an output file which, for the purposes of this simple example, we assume is indicated by the second argument handed to the program on the command line by the user.
What is the result of the above on an actual model? Suppose we have the following SBML Level 3 model stored in a file named 'enzyme_model.xml'
:
<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1"
xmlns:comp="http://www.sbml.org/sbml/level3/version1/comp/version1" comp:required="true">
<model id="aggregate">
<comp:listOfSubmodels>
<comp:submodel comp:id="submod1" comp:modelRef="enzyme"/>
<comp:submodel comp:id="submod2" comp:modelRef="enzyme"/>
</comp:listOfSubmodels>
</model>
<comp:listOfModelDefinitions>
<comp:modelDefinition id="enzyme" name="enzyme">
<listOfCompartments>
<compartment id="compartment" spatialDimensions="3" size="1" constant="true"/>
</listOfCompartments>
<listOfSpecies>
<species id="S" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="E" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="D" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="ES" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
</listOfSpecies>
<listOfReactions>
<reaction id="J0" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="S" stoichiometry="1" constant="true"/>
<speciesReference species="E" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="ES" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
<reaction id="J1" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="ES" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="E" stoichiometry="1" constant="true"/>
<speciesReference species="D" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
</listOfReactions>
</comp:modelDefinition>
</comp:listOfModelDefinitions>
</sbml>
Also suppose we have the following SBML Level 3 model stored in a file called 'main.xml'
in the same directory as the file above. The model below imports the model 'enzyme'
from the model file above twice; this is used to create two submodels whose identifiers are 'A'
and 'B'
.
<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1"
xmlns:comp="http://www.sbml.org/sbml/level3/version1/comp/version1" comp:required="true">
<model>
<listOfCompartments>
<compartment id="compartment" spatialDimensions="3" size="1" constant="true">
<comp:listOfReplacedElements>
<comp:replacedElement comp:idRef="compartment" comp:submodelRef="A"/>
<comp:replacedElement comp:idRef="compartment" comp:submodelRef="B"/>
</comp:listOfReplacedElements>
</compartment>
</listOfCompartments>
<listOfSpecies>
<species id="S" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false">
<comp:listOfReplacedElements>
<comp:replacedElement comp:idRef="S" comp:submodelRef="A"/>
<comp:replacedElement comp:idRef="S" comp:submodelRef="B"/>
</comp:listOfReplacedElements>
</species>
</listOfSpecies>
<comp:listOfSubmodels>
<comp:submodel comp:id="A" comp:modelRef="ExtMod1"/>
<comp:submodel comp:id="B" comp:modelRef="ExtMod1"/>
</comp:listOfSubmodels>
</model>
<comp:listOfExternalModelDefinitions>
<comp:externalModelDefinition comp:id="ExtMod1" comp:source="enzyme_model.xml"
comp:modelRef="enzyme"/>
</comp:listOfExternalModelDefinitions>
</sbml>
Finally, invoking the example program developed the previous section on the file 'main.xml'
, we would obtain the following XML output as result a result
<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1">
<model>
<listOfCompartments>
<compartment id="compartment" spatialDimensions="3" size="1" constant="true"/>
</listOfCompartments>
<listOfSpecies>
<species id="S" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="A__E" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="A__D" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="A__ES" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="B__E" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="B__D" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
<species id="B__ES" compartment="compartment" hasOnlySubstanceUnits="false"
boundaryCondition="false" constant="false"/>
</listOfSpecies>
<listOfReactions>
<reaction id="A__J0" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="S" stoichiometry="1" constant="true"/>
<speciesReference species="A__E" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="A__ES" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
<reaction id="A__J1" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="A__ES" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="A__E" stoichiometry="1" constant="true"/>
<speciesReference species="A__D" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
<reaction id="B__J0" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="S" stoichiometry="1" constant="true"/>
<speciesReference species="B__E" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="B__ES" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
<reaction id="B__J1" reversible="true" fast="false">
<listOfReactants>
<speciesReference species="B__ES" stoichiometry="1" constant="true"/>
</listOfReactants>
<listOfProducts>
<speciesReference species="B__E" stoichiometry="1" constant="true"/>
<speciesReference species="B__D" stoichiometry="1" constant="true"/>
</listOfProducts>
</reaction>
</listOfReactions>
</model>
</sbml>
The final model is a concrete realization of the effective model defined by 'main.xml'
, with a single compartment and two reactions; the species 'S'
can either bind with enzyme 'E'
(from submodel 'A'
) to form 'D'
(from submodel 'A'
), or with enzyme 'E'
(from submodel 'B'
) to form 'D'
(from submodel 'B'
). In the flattened model above, note how the identifiers of components inside the ModelDefinition objects 'A'
and 'B'
of our file 'enzyme_model.xml'
have been rewritten as (for example) 'A__E'
'B__E'
, etc.
The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)
Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .
Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.
The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions'
:
In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:
Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package'
defined by that converter:
LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:
This method has multiple variants; they differ in the arguments they accept.
__init__() CompFlatteningConverter __init__(CompFlatteningConverter orig) CompFlatteningConverter
Each variant is described separately below.
CompFlatteningConverter(CompFlatteningConverter orig)
Copy constructor.
This creates a copy of a CompFlatteningConverter object.
orig | the CompFlatteningConverter instance to copy. |
ValueError | Thrown if the argument orig is None . |
CompFlatteningConverter()
Creates a new CompFlatteningConverter object.
def libsbml.SBaseRef.__init__ | ( | self, | |
args | |||
) |
comp Base class for references to objects.
The SBaseRef class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) as the principle way by which submodel elements may be referenced. The SBaseRef class is usually found as the base class of a Port, Deletion, ReplacedElement, or ReplacedBy class, but may appear as an child of one of the above classes if the parent object references a Submodel.
An SBaseRef object must reference an element using exactly one of the optional attributes of the class. Subclasses of SBaseRef may define additional optional attributes that are legal ways to reference an element.
SBaseRef objects may reference elements that do not live in the Model parent of the SBaseRef object. However, the SBaseRef class itself does not provide a method of determining which Model or Submodel is being referenced. The subclasses of SBaseRef provide methods for this instead.
Once the Model to which the SBaseRef object is referencing has been established, there are four optional attributes defined in the SBaseRef class that are each methods of referencing an element:
An SBaseRef object may have up to one subcomponent named 'sBaseRef', of type SBaseRef. This permits recursive structures to be constructed so that objects inside submodels can be referenced.
The form of such recursive references must be as follows. The highest-level SBaseRef object of such a chain (which will necessarily be an object of class Port, Deletion, ReplacedElement or ReplacedBy, because they are the only classes derived from the class SBaseRef) must refer to a Submodel object in the containing model. All child SBaseRef objects in the chain must refer to components inside the Model instance to which the Submodel refers.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) SBaseRef __init__(long level, long version) SBaseRef __init__(long level) SBaseRef __init__() SBaseRef __init__(CompPkgNamespaces compns) SBaseRef __init__(SBaseRef source) SBaseRef
Each variant is described separately below.
SBaseRef(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new SBaseRef with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
SBaseRef(SBaseRef source)
Copy constructor.
SBaseRef(CompPkgNamespaces compns)
Creates a new SBaseRef with the given CompPkgNamespaces object.
compns | the namespace to use |
def libsbml.Deletion.__init__ | ( | self, | |
args | |||
) |
comp Deletion of an object from a submodel.
The Deletion class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) to allow elements of submodels to be removed before instantiation. The Deletion object class is used to define a deletion operation to be applied when a submodel instantiates a model definition. Deletions may be useful in hierarchical model composition scenarios for various reasons. For example, some components in a submodel may be redundant in the composed model, perhaps because the same features are implemented in a different way in the new model. Deletions function as follows. When the Model to which the Submodel object refers (via the 'modelRef' attribute) is read and processed for inclusion into the composed model, each Deletion object identifies an object to remove from that Model instance. The resulting submodel instance consists of everything in the Model object instance minus the entities referenced by the list of Deletion objects.
As might be expected, deletions can have wide-ranging implications, especially when the object deleted has substantial substructure, as in the case of reactions. The following are rules regarding deletions and their effects.
The Deletion object class is subclassed from SBaseRef, and reuses all the machinery provided by SBaseRef. In addition, it defines two optional attributes, 'id' and 'name'. The 'id' attribute can be used to give an identifier to a given deletion operation. The identifier has no mathematical meaning, but it may be useful for creating submodels that can be manipulated more directly by other submodels. (Indeed, it is legitimate for an enclosing model definition to delete a deletion!)
The optional 'name' attribute is provided on Deletion for the same reason it is provided on other elements that have identifiers; viz., to provide for the possibility of giving a human-readable name to the object. The name may be useful in situations when deletions are displayed to modelers.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) Deletion __init__(long level, long version) Deletion __init__(long level) Deletion __init__() Deletion __init__(CompPkgNamespaces compns) Deletion __init__(Deletion source) Deletion
Each variant is described separately below.
Deletion(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new Deletion with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
Deletion(Deletion source)
Copy constructor.
Deletion(CompPkgNamespaces compns)
Creates a new Deletion with the given CompPkgNamespaces object.
def libsbml.ExternalModelDefinition.__init__ | ( | self, | |
args | |||
) |
comp A reference to an externally-defined model.
The ExternalModelDefinition class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) to define references to Model objects defined in other files.
ExternalModelDefinition objects are model definitions—in and of themselves, they are definitions of models but not uses of those models. The class provides a way to declare and identify them so that Model objects in the present SBML document can use them in Submodel objects.
ExternalModelDefinition contains two required attributes ('source' and 'id') and three optional attributes ('modelRef', 'md5' and 'name').
The 'id' attribute serves to provide a handle for the external model reference so that Submodel objects can refer to it. Crucially, it is not the identifier of the model being referenced; rather, it is an identifier for this ExternalModelDefinition object within the current SBML document. The 'id' attribute takes a required value of type SId, and must be unique across all Model and ExternalModelDefinition objects present in the document.
ExternalModelDefinition also has an optional 'name' attribute, of type 'string'. The 'name' attribute may be used to provide a human-readable description of the ExternalModelDefintion object.
The required attribute 'source' is used to locate the SBML document containing an external model definition. The value of this attribute must be of type anyURI. Since URIs may be either URLs, URNs, or relative or absolute file locations, this offers flexibility in referencing SBML documents. In all cases, the 'source' attribute value must refer specifically to an SBML Level 3 Version 1 document; prior Levels/Versions of SBML are not supported by this package. The entire file at the given location is referenced. The 'source' attribute must have a value for every ExternalModelDefinition instance.
ExternalModelDefinition's optional attribute 'modelRef', of type SIdRef, is used to identify a Model or ExternalModelDefinition object within the SBML document located at 'source'. The object referenced may be the main model in the document, or it may be a model definition contained in the SBML document's ListOfModelDefinitions or ListOfExternalModelDefinitions lists. Loops are not allowed: it must be possible to follow a chain of ExternalModelDefinition objects to its end in a Model object.
In core SBML, the 'id' on Model is an optional attribute, and therefore, it is possible that the Model object in a given SBML document does not have an identifier. In that case, there is no value to give to the 'modelRef' attribute in ExternalModelDefinition. If 'modelRef' does not have a value, then the main model (i.e., the <model>
element within the <sbml>
element) in the referenced file is interpreted as being the model referenced by this ExternalModelDefinition instance.
Finally, the optional 'md5' attribute takes a string value. If set, it must be an MD5 checksum value computed over the document referenced by 'source'. This checksum can serve as a data integrity check over the contents of the 'source'. Applications may use this to verify that the contents have not changed since the time that the ExternalModelDefinition reference was constructed.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) ExternalModelDefinition __init__(long level, long version) ExternalModelDefinition __init__(long level) ExternalModelDefinition __init__() ExternalModelDefinition __init__(CompPkgNamespaces compns) ExternalModelDefinition __init__(ExternalModelDefinition source) ExternalModelDefinition
Each variant is described separately below.
ExternalModelDefinition(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new ExternalModelDefinition with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
ExternalModelDefinition(ExternalModelDefinition source)
Copy constructor.
source | the object to copy. |
ExternalModelDefinition(CompPkgNamespaces compns)
Creates a new ExternalModelDefinition with the given CompPkgNamespaces object.
compns | the namespace to use. |
def libsbml.ModelDefinition.__init__ | ( | self, | |
args | |||
) |
comp A model used in model composition.
The Hierarchical Model Composition package (“comp”) allows multiple Model objects to be defined in a single SBMLDocument. While these new Model objects are not new SBML classes, they are given a new name, <modelDefinition>
, and reside in ListOfModelDefinition objects. In libSBML, this class inherits from the Model class, changing only the expected parent of the object, and the XML name.
An additional restriction is placed on the 'id' attribute of ModelDefinition objects: not only must it be unique across all such attributes of type SId within the ModelDefintion, it must also be unique across all Model, ModelDefinition, and ExternalModelDefinition objects in the same SBMLDocument.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) ModelDefinition __init__(long level, long version) ModelDefinition __init__(long level) ModelDefinition __init__() ModelDefinition __init__(CompPkgNamespaces compns) ModelDefinition __init__(Model source) ModelDefinition
Each variant is described separately below.
ModelDefinition(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new ModelDefinition with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
ModelDefinition(Model source)
Copy constructor from base Model object.
ModelDefinition(CompPkgNamespaces compns)
Creates a new ModelDefinition with the given CompPkgNamespaces object.
compns | the namespace to use |
def libsbml.Port.__init__ | ( | self, | |
args | |||
) |
comp An interface to be used in composition.
The Port class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) to allow a Model to define a standard interface between it and other models that might use it as a submodel. It derives from the SBaseRef class, and the elements defined there refer to elements in the same parent Model as the Port object. A Port object instance therefore uses those attributes to define a port for a component in a model. When other SBaseRef or SBaseRef-derived classes refer to a Port object using a 'portRef' attribute, the element being referenced is the element the Port object itself points to.
In the present formulation of the Hierarchical Model Composition package, the use of ports is not enforced, nor is there any mechanism to restrict which ports may be used in what ways—they are only an advisory construct. Future versions of this SBML package may provide additional functionality to support explicit restrictions on port use. For the present definition of Hierarchical Model Composition, users of models containing ports are encouraged to respect the modeler's intention in defining ports, and use the port definitions to interact with components through their ports (when they have ports defined) rather than interact directly with the components.
The required attribute 'id' is used to give an identifier to a Port object so that other objects can refer to it. The attribute has type PortSId and is essentially identical to the SBML primitive type SId, except that its namespace is limited to the identifiers of Port objects defined within a Model object. In parallel, the PortSId type has a companion type, PortSIdRef, that corresponds to the SBML primitive type SIdRef; the value space of PortSIdRef is limited to PortSId values.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) Port __init__(long level, long version) Port __init__(long level) Port __init__() Port __init__(CompPkgNamespaces compns) Port __init__(Port source) Port
Each variant is described separately below.
Port(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new Port with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
Port(Port source)
Copy constructor.
Port(CompPkgNamespaces compns)
Creates a new Port with the given CompPkgNamespaces object.
compns | the namespace to use |
def libsbml.ReplacedBy.__init__ | ( | self, | |
args | |||
) |
comp Indicates an object replaced by another.
The ReplacedBy class was introduced by the SBML Level 3 Hierarchical Model Composition
package (“comp”) to allow submodel elements to be 'canonical' versions of the element while still allowing the parent model to reference those elements. Whereas a ReplacedElement object indicates that the containing object replaces another, a ReplacedBy object indicates the converse: the parent object is to be replaced by another object. As is the case with ReplacedElement, the ReplacedBy class inherits from SBaseRef. It additionally defines one required attribute ('submodelRef'), defined in libSBML in the Replacing class.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) ReplacedBy __init__(long level, long version) ReplacedBy __init__(long level) ReplacedBy __init__() ReplacedBy __init__(CompPkgNamespaces compns) ReplacedBy __init__(ReplacedBy source) ReplacedBy
Each variant is described separately below.
ReplacedBy(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new ReplacedBy with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
ReplacedBy(ReplacedBy source)
Copy constructor.
ReplacedBy(CompPkgNamespaces compns)
Creates a new ReplacedBy with the given CompPkgNamespaces object.
compns | the namespace to use |
def libsbml.ReplacedElement.__init__ | ( | self, | |
args | |||
) |
comp Indicates an object replaces another.
The ReplacedElement class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) to allow submodel elements to be replaced, but still allow references to those elements to be valid. A ReplacedElement object is essentially a pointer to a submodel object that should be considered 'replaced'. The object holding the ReplacedElement instance is the one doing the replacing; the object pointed to by the ReplacedElement object is the object being replaced.
A replacement implies that dependencies involving the replaced object must be updated: all references to the replaced object elsewhere in the model are taken to refer to the replacement object instead. For example, if one species replaces another, then any reference to the original species in mathematical formulas, or lists of reactants or products or modifiers in reactions, or initial assignments, or any other SBML construct, are taken to refer to the replacement species, with its value possibly modified by either this object's 'conversionFactor' attribute or the relevant submodel's conversion factors. Moreover, any annotations that refer to the replaced species' 'metaid' value must be made to refer to the replacement species' 'metaid' value instead; and anything else that referred either to an object identifier (i.e., attributes such as the 'id' attribute whose types inherit from the SId primitive data type) or the meta identifier (i.e., the 'metaid' attribute or any other attribute that inherits from the ID primitive data type) must be made to refer to the replacement species object instead.
It is worth noting that local parameters (inside Reaction objects) pose an interesting edge case for these rules. In order to determine which element is pointed to by a <cn>
element within the <math>
element of a KineticLaw object, it is necessary to examine the local parameters of that kinetic law's parent Reaction object. Whether the <cn>
element is considered to point to something new, then, depends on whether it pointed to the local parameter and whether that local parameter was replaced, even if the text of the element matched the SId value of another element in the model. Note that local parameters may only effectively be replaced by global parameters, since references to its SId are only valid from within the Reaction element to which it belongs.
When referencing an element within the Submodel pointed to by the 'submodelRef' attribute (defined in libSBML in the Replacing class), any of the four attributes inherited from SBaseRef for the purpose may be used (portRef, idRef, unitRef, or metaIdRef), or a new optional attribute 'deletion' may be used. This attribute must be the identifier of a Deletion object in the parent Model of the ReplacedElement (i.e., the value of some Deletion object's 'id' attribute). When 'deletion' is set, it means the ReplacedElement object is actually an annotation to indicate that the replacement object replaces something deleted from a submodel. The use of the 'deletion' attribute overrides the use of the attributes inherited from SBaseRef: instead of using, e.g., 'portRef' or 'idRef', the ReplacedElement instance sets 'deletion' to the identifier of the Deletion object. In addition, the referenced Deletion must be a child of the Submodel referenced by the 'submodelRef' attribute.
The use of ReplacedElement objects to refer to deletions has no effect on the composition of models or the mathematical properties of the result. It serves instead to help record the decision-making process that lead to a given model. It can be particularly useful for visualization purposes, as well as to serve as scaffolding where other types of annotations can be added using the normal Annotation subcomponents available on all SBase objects in SBML.
As with the Submodel class, it may be that the units of the replaced element may not match the units of the replacement element. In this case, the optional 'conversionFactor' attribute may be used. This attribute, if present, defines how to transform or rescale the replaced object's value so that it is appropriate for the new contexts in which the object appears. This attribute takes a value of type SIdRef, and the value must refer to a Parameter object instance defined in the model. This parameter then acts as a conversion factor.
The value of the conversion factor should be defined such that a single unit of the replaced element multiplied by the conversion factor should equal a single unit of the replacement element, and the units of the conversion factor should be commensurate with that transformation. The referenced Parameter may be non-constant, particularly if a Species is replaced by a Species with a different 'hasOnlySubstanceUnits' attribute value, thus changing amount to concentration, or visa versa.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) ReplacedElement __init__(long level, long version) ReplacedElement __init__(long level) ReplacedElement __init__() ReplacedElement __init__(CompPkgNamespaces compns) ReplacedElement __init__(ReplacedElement source) ReplacedElement
Each variant is described separately below.
ReplacedElement(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new ReplacedElement with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
ReplacedElement(CompPkgNamespaces compns)
Creates a new ReplacedElement with the given CompPkgNamespaces object.
compns | the namespace to use |
ReplacedElement(ReplacedElement source)
Copy constructor.
def libsbml.Submodel.__init__ | ( | self, | |
args | |||
) |
comp A model instance inside another model.
The Submodel class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) as the principle way by which models are structured hierarchically. Submodels are instantiations of models contained within other models. They reference another Model that is to be instantiated within its parent Model, and additionally define how that Model is to be modified before instantiation.
The Submodel object class has a required attribute 'modelRef', which must reference another Model or ExternalModelDefinition object present in the SBML Document. This referenced Model is the model to be instantiated.
It also has a required attribute, 'id', to give the submodel a unique identifier by which other parts of an SBML model definition can refer to it, and an optional 'name' attribute of type string
. Identifiers and names must be used according to the guidelines described in the SBML specification.
The Submodel class also provides constructs that define how the referenced Model object is to be modified before it is instantiated in the enclosing model. If numerical values in the referenced model must be changed in order to fit them into their new context as part of the submodel, the changes can be handled through conversion factors. If one or more structural features in the referenced model are undesirable and should be removed, the changes can be handled through deletions. (For example, an initial assignment or reaction may not be relevant in its new context and should be removed.)
In some cases, the referenced Model may have been written with different units than the containing model. For most model elements, this is not a problem: it is already possible to have Species and Parameter objects with different units in a single model, for example, so in this case the resulting hierarchical model would be treated in exactly the same way as any other model with Species and Parameters with different units.
However, two units in SBML models are fixed and must not vary between SBML elements: time and extent. The units of time are set once per model, and affect the core elements of RateRule, KineticLaw, Delay, and the csymbols 'time' and 'delay'. Even if the model does not explicitly state what the units of time actually are, they are defined to be consistent across the model, and therefore might differ from the units of time across a parent model. To correct this imbalance, the optional attribute 'timeConversionFactor' may be used, which, if defined, must reference a constant parameter in the parent model. The value of the time conversion factor should be defined such that a single unit of time in the Submodel multiplied by the time conversion factor should equal a single unit of time in the parent model.
Extent is the unit in SBML that defines how the KineticLaw of a Reaction affects species quantities: kinetic laws are defined to be in units of extent/time. No other SBML core construct is defined in terms of extent. If the effective units of extent in a submodel differ from the effective units of extent in the parent model (regardless of whether either defined what those units actually are), the optional attribute 'extentConversionFactor' may be used, which, if defined, must reference a constant parameter in the parent model. The value of the extent conversion factor should be defined such that a single unit of extent in the Submodel multiplied by the extent conversion factor should equal a single unit of extent in the parent model.
If features of the referenced model must be removed, a Deletion should be added to the Submodel object. A Submodel may contain a child ListOfDeletions, which in turn may contain one or more Deletion items. Each Deletion references a single element of the referenced Model that must be removed before instantiating that Model as a submodel of the parent Model.
This method has multiple variants; they differ in the arguments they accept.
__init__(long level, long version, long pkgVersion) Submodel __init__(long level, long version) Submodel __init__(long level) Submodel __init__() Submodel __init__(CompPkgNamespaces compns) Submodel __init__(Submodel source) Submodel
Each variant is described separately below.
Submodel(Submodel source)
Copy constructor.
Submodel(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())
Creates a new Submodel with the given level, version, and package version.
level | the SBML Level |
version | the Version within the SBML Level |
pkgVersion | the version of the package |
Submodel(CompPkgNamespaces compns)
Creates a new Submodel with the given CompPkgNamespaces object.
compns | the namespace to use |
def libsbml.ListOfDeletions.clone | ( | self | ) |
comp A list of Deletion objects.
The ListOfDeletions is a container for the “comp” Submodel that defines elements to be removed before instantiation.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfDeletions object.
clone() ListOfDeletions
def libsbml.ListOfExternalModelDefinitions.clone | ( | self | ) |
comp A list of ExternalModelDefinition objects.
The ListOfExternalModelDefinitions is a container for the extended SBMLDocument that defines references to Models defined in external files.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfExternalModelDefinitions object.
clone() ListOfExternalModelDefinitions
def libsbml.ListOfModelDefinitions.clone | ( | self | ) |
comp A list of ModelDefinition objects.
The ListOfModelDefinitions is a container for the extended SBMLDocument that allows one to define multiple Models in a single file for use in Submodel objects.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfModelDefinitions object.
clone() ListOfModelDefinitions
def libsbml.ListOfPorts.clone | ( | self | ) |
The ListOfPorts is a container for the extended Model for Port objects for that Model.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfPorts object.
clone() ListOfPorts
def libsbml.ListOfReplacedElements.clone | ( | self | ) |
comp A list of ReplacedElement objects.
The ListOfReplacedElements is a container for any SBase object. It contains ReplacedElement objects, which point to elements the parent SBase object is to replace.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfReplacedElements object.
clone() ListOfReplacedElements
def libsbml.ListOfSubmodels.clone | ( | self | ) |
comp A list of Submodel objects.
The ListOfSubmodels is a container for the extended Model that contains Submodel objects to be instantiated in that Model.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.
Creates and returns a deep copy of this ListOfSubmodels object.
clone() ListOfSubmodels
def libsbml.SBMLResolverRegistry.getInstance | ( | ) |
comp Registry of all SBML resolvers.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.
LibSBML provides facilities for resolving SBML documents in various ways from a given URI. Resolvers are implemented as objects derived from the class SBMLResolver.
The resolver registry maintains a list of known resolvers and provides methods for discovering them. It is implemented as a singleton object of class SBMLResolverRegistry. Callers can use the method SBMLResolverRegistry.getNumResolvers() to find out how many resolvers are registered, then use SBMLResolverRegistry.getResolverByIndex() to iterate over each one;
Returns the singleton instance for the resolver registry.
getInstance() SBMLResolverRegistry
Prior to using the registry, callers have to obtain a copy of the registry. This static method provides the means for doing that.
def libsbml.CompExtension.getPackageName | ( | ) |
comp Base extension class for the package.
Returns the nickname of the SBML Level 3 package implemented by this libSBML extension.
getPackageName() string
def libsbml.Replacing.getSubmodelRef | ( | self | ) |
comp Convenience class.
The Replacing class does not exist officialy in the the Hierarchical Model Composition package (“comp”), but is implemented here as a convenience subclass of the ReplacedElement and ReplacedBy classes, since both of those classes define a 'submodelRef' attribute.
The required attribute 'submodelRef' takes a value of type SIdRef, which must be the identifier of a Submodel object in the containing model. The model referenced by the Submodel object establishes the object namespaces for the 'portRef', 'idRef', 'unitRef' and 'metaIdRef' attributes: only objects within the Model object may be referenced by those attributes.
Returns the value of the 'submodelRef' attribute of this SBaseRef.
getSubmodelRef() string