libSBML C++ API
5.18.0
|
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.
"stripPackages": The value must be a string representing a comma-separated list of SBML Level 3 packages to be stripped before conversion. (Default value: empty string, meaning, no packages.)
"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 "requiredOnly"
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 option "stripPackages" controls whether SBML Level 3 package information is stripped from a model before conversion. Regardless of the above options, if an SBML package is listed in this comma-separated list, all constructs from that package will be removed from the model before the flattening algorithm is applied. This happens whether a flattening algorithm exists for that package or not, and applies to all referenced models, both local and external. In addition, the removal takes place before any validation is performed by libSBML.
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/c++/comp
directory as the program named flattenModel.cpp. 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. We also clean up the objects we allocated, to avoid leaking memory.
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 argument: 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.18.0:
Public Member Functions | |
virtual CompFlatteningConverter * | clone () const |
Creates and returns a deep copy of this CompFlatteningConverter. More... | |
CompFlatteningConverter () | |
Creates a new CompFlatteningConverter object. More... | |
CompFlatteningConverter (const CompFlatteningConverter &orig) | |
Copy constructor. More... | |
virtual int | convert () |
Performs the conversion. More... | |
virtual ConversionProperties | getDefaultProperties () const |
Returns the default properties of this converter. More... | |
virtual SBMLDocument * | getDocument () |
Returns the SBML document that is the subject of the conversions. More... | |
virtual const SBMLDocument * | getDocument () const |
Returns the SBML document that is the subject of the conversions. More... | |
const std::string & | getName () const |
Returns the name of this converter. More... | |
virtual ConversionProperties * | getProperties () const |
Returns the current properties in effect for this converter. More... | |
virtual SBMLNamespaces * | getTargetNamespaces () |
Returns the target SBML namespaces of the currently set properties. More... | |
virtual bool | matchesProperties (const ConversionProperties &props) const |
Returns true if this converter matches the given properties. More... | |
virtual int | setDocument (const SBMLDocument *doc) |
Sets the SBML document to be converted. More... | |
virtual int | setDocument (SBMLDocument *doc) |
Sets the SBML document to be converted. More... | |
virtual int | setProperties (const ConversionProperties *props) |
Sets the configuration properties to be used by this converter. More... | |
virtual | ~CompFlatteningConverter () |
Destroy this CompFlatteningConverter object. More... | |
CompFlatteningConverter::CompFlatteningConverter | ( | ) |
Creates a new CompFlatteningConverter object.
CompFlatteningConverter::CompFlatteningConverter | ( | const CompFlatteningConverter & | orig | ) |
Copy constructor.
This creates a copy of a CompFlatteningConverter object.
orig | the CompFlatteningConverter instance to copy. |
|
virtual |
Destroy this CompFlatteningConverter object.
|
virtual |
Creates and returns a deep copy of this CompFlatteningConverter.
Reimplemented from SBMLConverter.
|
virtual |
Performs the conversion.
This method causes CompFlatteningConverter to do the actual conversion work, that is, to convert the SBMLDocument object set by SBMLConverter::setDocument() and with the configuration options set by SBMLConverter::setProperties().
Reimplemented from SBMLConverter.
|
virtual |
Returns the default properties of this converter.
A given converter exposes one or more properties that can be adjusted in order to influence the behavior of the converter. This method returns the default property settings for CompFlatteningConverter. It is meant to be called in order to be able to programmatically discover all the settings for the converter object.
"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.
"stripPackages": The value must be a string representing a comma-separated list of SBML Level 3 packages to be stripped before conversion. (Default value: empty string, meaning, no packages.)
"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. Reimplemented from SBMLConverter.
|
virtualinherited |
Returns the SBML document that is the subject of the conversions.
|
virtualinherited |
Returns the SBML document that is the subject of the conversions.
|
inherited |
Returns the name of this converter.
|
virtualinherited |
Returns the current properties in effect for this converter.
A given converter exposes one or more properties that can be adjusted in order to influence the behavior of the converter. This method returns the current properties for this converter; in other words, the settings in effect at this moment. To change the property values, you can use SBMLConverter::setProperties(const ConversionProperties *props).
|
virtualinherited |
Returns the target SBML namespaces of the currently set properties.
SBML namespaces are used by libSBML to express the Level+Version of the SBML document (and, possibly, any SBML Level 3 packages in use). Some converters' behavior is affected by the SBML namespace configured in the converter. For example, in SBMLLevelVersionConverter (the converter for converting SBML documents from one Level+Version combination to another), the actions are fundamentally dependent on the SBML namespaces targeted.
NULL
if none are set.
|
virtual |
Returns true
if this converter matches the given properties.
Given a ConversionProperties object props
, this method checks that props
possesses an option value to enable the CompFlatteningConverter. If it does, this method returns true
.
props | the properties to match. |
true
if the properties props
would match the necessary properties for CompFlatteningConverter type of converter, false
otherwise. Reimplemented from SBMLConverter.
|
virtualinherited |
Sets the SBML document to be converted.
doc | the document to use for this conversion. |
doc
is 'const', it is immediately cast to a non-const version, which is then usually changed by the converter upon a successful conversion. This variant of the setDocument() method is here solely to preserve backwards compatibility. Reimplemented in SBMLReactionConverter, and SBMLRateOfConverter.
|
virtualinherited |
Sets the SBML document to be converted.
doc | the document to use for this conversion. |
Reimplemented in SBMLReactionConverter, and SBMLRateOfConverter.
|
virtualinherited |
Sets the configuration properties to be used by this converter.
props | the ConversionProperties object defining the properties to set. |