libSBML Python API  5.11.0
libsbml.Submodel Class Reference
Inheritance diagram for libsbml.Submodel:
[legend]

Detailed Description

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.

Public Member Functions

def __init__ (self, args)
 comp A model instance inside another model. More...
 
def addDeletion (self, deletion)
 Adds a copy of the given Deletion object to the list of deletions. More...
 
def clearInstantiation (self)
 Delete the instantiated Model, if it exists. More...
 
def clone (self)
 Creates and returns a deep copy of this Submodel object. More...
 
def connectToChild (self)
 
def convertTimeAndExtent (self)
 Convert all references to time and extent in the instantiated Model, according to the timeConversionFactor and extentConversionFactor attributes. More...
 
def createDeletion (self)
 Creates a Deletion object, adds it to the end of the deletion objects list and returns a pointer to the newly created object. More...
 
def getDeletion (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def getElementByMetaId (self, metaid)
 Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or None if no such object is found. More...
 
def getElementBySId (self, id)
 Returns the first child element found that has the given id in the model-wide SId namespace, or None if no such object is found. More...
 
def getElementName (self)
 Returns the XML element name of this SBML object. More...
 
def getExtentConversionFactor (self)
 Returns the value of the 'extentConversionFactor' attribute of this Submodel. More...
 
def getId (self)
 Returns the value of the 'id' attribute of this Submodel. More...
 
def getInstantiation (self, args)
 Get the instantiated Model this Submodel contains rules to create. More...
 
def getListOfAllInstantiatedElements (self)
 
def getListOfDeletions (self, args)
 Returns the ListOf object that holds all deletions. More...
 
def getModelRef (self)
 Returns the value of the 'modelRef' attribute of this Submodel. More...
 
def getName (self)
 Returns the value of the 'name' attribute of this Submodel. More...
 
def getNumDeletions (self)
 Returns the number of deletions for this Submodel. More...
 
def getSubstanceConversionFactor (self)
 Returns an empty string, since 'substanceConversionFactor' is not a part of the comp spec. More...
 
def getTimeConversionFactor (self)
 Returns the value of the 'timeConversionFactor' attribute of this Submodel. More...
 
def getTypeCode (self)
 Returns the libSBML type code of this object instance. More...
 
def hasRequiredAttributes (self)
 Returns true if the 'submodel' attribute is set, and if getNumReferents() is exactly 1. More...
 
def instantiate (self)
 Find and create a local copy of the Model object referenced by this Submodel. More...
 
def isSetExtentConversionFactor (self)
 Predicate returning True or False depending on whether this Submodel's 'extentConversionFactor' attribute has been set. More...
 
def isSetId (self)
 Predicate returning True or False depending on whether this Submodel's 'id' attribute has been set. More...
 
def isSetModelRef (self)
 Predicate returning True or False depending on whether this Submodel's 'modelRef' attribute has been set. More...
 
def isSetName (self)
 Predicate returning True or False depending on whether this Submodel's 'name' attribute has been set. More...
 
def isSetSubstanceConversionFactor (self)
 Returns False, since 'substanceConversionFactor' is not a part of the comp spec. More...
 
def isSetTimeConversionFactor (self)
 Predicate returning True or False depending on whether this Submodel's 'timeConversionFactor' attribute has been set. More...
 
def performDeletions (self)
 Delete elements in the instantiated submodel, based on any Deletions from this Submodel's listOfDeletions. More...
 
def removeDeletion (self, args)
 This method has multiple variants; they differ in the arguments they accept. More...
 
def removeProcessingCallback (args)
 
def renameSIdRefs (self, oldid, newid)
 Renames the conversion factor attributes on this element if oldid matches. More...
 
def replaceElement (self, toReplace, replacement)
 Delete the element in question from the stored instantiated Model, and replace all references to it with references to the replacement object. More...
 
def setExtentConversionFactor (self, id)
 Sets the value of the 'extentConversionFactor' attribute of this Submodel. More...
 
def setId (self, id)
 Sets the value of the 'id' attribute of this Submodel. More...
 
def setModelRef (self, modelRef)
 Sets the value of the 'modelRef' attribute of this Submodel. More...
 
def setName (self, name)
 Sets the value of the 'name' attribute of this Submodel. More...
 
def setSubstanceConversionFactor (self, id)
 Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec. More...
 
def setTimeConversionFactor (self, id)
 Sets the value of the 'timeConversionFactor' attribute of this Submodel. More...
 
def unsetExtentConversionFactor (self)
 Unsets the value of the 'extentConversionFactor' attribute of this Submodel. More...
 
def unsetId (self)
 Unsets the value of the 'id' attribute of this Submodel. More...
 
def unsetModelRef (self)
 Unsets the value of the 'modelRef' attribute of this Submodel. More...
 
def unsetName (self)
 Unsets the value of the 'name' attribute of this Submodel. More...
 
def unsetSubstanceConversionFactor (self)
 Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec. More...
 
def unsetTimeConversionFactor (self)
 Unsets the value of the 'timeConversionFactor' attribute of this Submodel. More...
 

Member Function Documentation

def libsbml.Submodel.addDeletion (   self,
  deletion 
)

Adds a copy of the given Deletion object to the list of deletions.

addDeletion(Deletion deletion)   int
Parameters
deletionthe Deletion object to be added to the list of deletions. Fails if the added deletion is None, does not match the level/version/package of the parent object, or cannot be added to the list of deletions.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.clearInstantiation (   self)

Delete the instantiated Model, if it exists.

clearInstantiation()
def libsbml.Submodel.clone (   self)

Creates and returns a deep copy of this Submodel object.

clone()   Submodel
Returns
a (deep) copy of this Submodel object
def libsbml.Submodel.connectToChild (   self)
connectToChild()
def libsbml.Submodel.convertTimeAndExtent (   self)

Convert all references to time and extent in the instantiated Model, according to the timeConversionFactor and extentConversionFactor attributes.

convertTimeAndExtent()   int
def libsbml.Submodel.createDeletion (   self)

Creates a Deletion object, adds it to the end of the deletion objects list and returns a pointer to the newly created object.

createDeletion()   Deletion
Returns
a newly created Deletion object
def libsbml.Submodel.getDeletion (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

getDeletion(long n)   Deletion
getDeletion(string id)   Deletion

Each variant is described separately below.


Method variant with the following signature:
getDeletion(long n)

Returns the deletion with the given index. If the index is invalid, None is returned.

Parameters
nthe index number of the Deletion to get.
Returns
the nth Deletion in the ListOfDeletions.

Method variant with the following signature:
getDeletion(string id)

Returns the deletion with the given id. If the id is invalid, None is returned.

Parameters
idthe id of the Deletion to get.
Returns
the Deletion in the ListOfDeletions with the given id.
def libsbml.Submodel.getElementByMetaId (   self,
  metaid 
)

Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or None if no such object is found.

getElementByMetaId(string metaid)   SBase
Parameters
metaidstring representing the metaid of objects to find
Returns
a pointer to the SBase element with the given metaid.
def libsbml.Submodel.getElementBySId (   self,
  id 
)

Returns the first child element found that has the given id in the model-wide SId namespace, or None if no such object is found.

getElementBySId(string id)   SBase
Parameters
idstring representing the id of objects to find
Returns
a pointer to the SBase element with the given id.
def libsbml.Submodel.getElementName (   self)

Returns the XML element name of this SBML object.

getElementName()   string
Returns
the name of this element, as a text string.
def libsbml.Submodel.getExtentConversionFactor (   self)

Returns the value of the 'extentConversionFactor' attribute of this Submodel.

getExtentConversionFactor()   string
Returns
the value of the 'extentConversionFactor' attribute of this Submodel.
def libsbml.Submodel.getId (   self)

Returns the value of the 'id' attribute of this Submodel.

getId()   string
Returns
the value of the 'id' attribute of this Submodel.
def libsbml.Submodel.getInstantiation (   self,
  args 
)

Get the instantiated Model this Submodel contains rules to create.

getInstantiation()   Model

Calls instantiate() automatically if this operation has not yet been performed, and/or if the operation failed the last time it was called. Any modifictions that have been performed with performDeletions(), replaceElement(), or convertTimeAndExtent() function calls will be included.

Returns
the instantiated Model object: a clone of the original, modified according to the performDeletions() and replaceElement() functions that have been called. Returns None if any error is encountered.
def libsbml.Submodel.getListOfAllInstantiatedElements (   self)
getListOfAllInstantiatedElements()   SBaseList
def libsbml.Submodel.getListOfDeletions (   self,
  args 
)

Returns the ListOf object that holds all deletions.

getListOfDeletions()   ListOfDeletions
Returns
the ListOf object that holds all deletions.
def libsbml.Submodel.getModelRef (   self)

Returns the value of the 'modelRef' attribute of this Submodel.

getModelRef()   string
Returns
the value of the 'modelRef' attribute of this Submodel.
def libsbml.Submodel.getName (   self)

Returns the value of the 'name' attribute of this Submodel.

getName()   string
Returns
the value of the 'name' attribute of this Submodel.
def libsbml.Submodel.getNumDeletions (   self)

Returns the number of deletions for this Submodel.

getNumDeletions()   long
Returns
the number of deletions for this Submodel.
def libsbml.Submodel.getSubstanceConversionFactor (   self)

Returns an empty string, since 'substanceConversionFactor' is not a part of the comp spec.

getSubstanceConversionFactor()   string
Returns
an empty string
def libsbml.Submodel.getTimeConversionFactor (   self)

Returns the value of the 'timeConversionFactor' attribute of this Submodel.

getTimeConversionFactor()   string
Returns
the value of the 'timeConversionFactor' attribute of this Submodel.
def libsbml.Submodel.getTypeCode (   self)

Returns the libSBML type code of this object instance.

getTypeCode()   int
LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. In the Python language interface for libSBML, the type codes are defined as static integer constants in the interface class libsbml. Note that different Level 3 package plug-ins may use overlapping type codes; to identify the package to which a given object belongs, call the getPackageName() method on the object.
Returns
the SBML type code for this object: SBML_COMP_SUBMODEL
Warning
The specific integer values of the possible type codes may be reused by different Level 3 package plug-ins. Thus, to identifiy the correct code, it is necessary to invoke both getTypeCode() and getPackageName().
See also
getElementName()
getPackageName()
def libsbml.Submodel.hasRequiredAttributes (   self)

Returns true if the 'submodel' attribute is set, and if getNumReferents() is exactly 1.

hasRequiredAttributes()   bool
Returns
boolean: 'true' if the attributes are correctly set; 'false' if not.
def libsbml.Submodel.instantiate (   self)

Find and create a local copy of the Model object referenced by this Submodel.

instantiate()   int

Is recursive, in that if the instantiated Model contains any Submodel objects, those Submodels will themselves be instantiated. If an instantiated model previously existed, it is deleted and a new one is created. For this reason, call this function only once, or call Submodel.getInstantiation().

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.isSetExtentConversionFactor (   self)

Predicate returning True or False depending on whether this Submodel's 'extentConversionFactor' attribute has been set.

isSetExtentConversionFactor()   bool
Returns
True if this Submodel's 'extentConversionFactor' attribute has been set, otherwise False is returned.
def libsbml.Submodel.isSetId (   self)

Predicate returning True or False depending on whether this Submodel's 'id' attribute has been set.

isSetId()   bool
Returns
True if this Submodel's 'id' attribute has been set, otherwise False is returned.
def libsbml.Submodel.isSetModelRef (   self)

Predicate returning True or False depending on whether this Submodel's 'modelRef' attribute has been set.

isSetModelRef()   bool
Returns
True if this Submodel's 'modelRef' attribute has been set, otherwise False is returned.
def libsbml.Submodel.isSetName (   self)

Predicate returning True or False depending on whether this Submodel's 'name' attribute has been set.

isSetName()   bool
Returns
True if this Submodel's 'name' attribute has been set, otherwise False is returned.
def libsbml.Submodel.isSetSubstanceConversionFactor (   self)

Returns False, since 'substanceConversionFactor' is not a part of the comp spec.

isSetSubstanceConversionFactor()   bool
Returns
False.
def libsbml.Submodel.isSetTimeConversionFactor (   self)

Predicate returning True or False depending on whether this Submodel's 'timeConversionFactor' attribute has been set.

isSetTimeConversionFactor()   bool
Returns
True if this Submodel's 'timeConversionFactor' attribute has been set, otherwise False is returned.
def libsbml.Submodel.performDeletions (   self)

Delete elements in the instantiated submodel, based on any Deletions from this Submodel's listOfDeletions.

performDeletions()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.removeDeletion (   self,
  args 
)

This method has multiple variants; they differ in the arguments they accept.

removeDeletion(long index)   Deletion
removeDeletion(string sid)   Deletion

Each variant is described separately below.


Method variant with the following signature:
removeDeletion(long index)

Removes the deletion with the given index from the Submodel. A pointer to the deletion that was removed is returned. If no deletion has been removed, None is returned.

Parameters
indexthe index of the Deletion object to remove
Returns
the Deletion object removed. As mentioned above, the caller owns the returned object. None is returned if the given index is out of range.

Method variant with the following signature:
removeDeletion(string sid)

Removes the deletion with the given identifier from the Submodel. A pointer to the deletion that was removed is returned. If no deletion has been removed, None is returned.

Parameters
sidstring representing the identifier of the Deletion object to remove
Returns
the Deletion object removed. As mentioned above, the caller owns the returned object. None is returned if the given sid is not found.
def libsbml.Submodel.removeProcessingCallback (   args)
removeProcessingCallback(int index)
removeProcessingCallback(ModelProcessingCallback cb)
def libsbml.Submodel.renameSIdRefs (   self,
  oldid,
  newid 
)

Renames the conversion factor attributes on this element if oldid matches.

renameSIdRefs(string oldid, string newid)
def libsbml.Submodel.replaceElement (   self,
  toReplace,
  replacement 
)

Delete the element in question from the stored instantiated Model, and replace all references to it with references to the replacement object.

replaceElement(SBase toReplace, SBase replacement)   int

LIBSBML_INVALID_OBJECT means that this Submodel itself or one of the passed-in objects are invalid. LIBSBML_OPERATION_FAILED means that the routine failed for some othe reason.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.setExtentConversionFactor (   self,
  id 
)

Sets the value of the 'extentConversionFactor' attribute of this Submodel.

setExtentConversionFactor(string id)   int

Fails if the id is not a valid syntax for an SIdRef.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.setId (   self,
  id 
)

Sets the value of the 'id' attribute of this Submodel.

setId(string id)   int

Fails if the id is not a valid syntax for an SId.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.setModelRef (   self,
  modelRef 
)

Sets the value of the 'modelRef' attribute of this Submodel.

setModelRef(string modelRef)   int

Fails if the modelRef is not a valid syntax for an SIdRef.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.setName (   self,
  name 
)

Sets the value of the 'name' attribute of this Submodel.

setName(string name)   int

Fails if the name is empty.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.setSubstanceConversionFactor (   self,
  id 
)

Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec.

setSubstanceConversionFactor(string id)   int
Returns
integer value indicating success/failure of the operation. The possible return value is:
def libsbml.Submodel.setTimeConversionFactor (   self,
  id 
)

Sets the value of the 'timeConversionFactor' attribute of this Submodel.

setTimeConversionFactor(string id)   int

Fails if the id is not a valid syntax for an SIdRef.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.unsetExtentConversionFactor (   self)

Unsets the value of the 'extentConversionFactor' attribute of this Submodel.

unsetExtentConversionFactor()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.unsetId (   self)

Unsets the value of the 'id' attribute of this Submodel.

unsetId()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.unsetModelRef (   self)

Unsets the value of the 'modelRef' attribute of this Submodel.

unsetModelRef()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.unsetName (   self)

Unsets the value of the 'name' attribute of this Submodel.

unsetName()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Submodel.unsetSubstanceConversionFactor (   self)

Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec.

unsetSubstanceConversionFactor()   int
Returns
integer value indicating success/failure of the operation. The possible return value is:
def libsbml.Submodel.unsetTimeConversionFactor (   self)

Unsets the value of the 'timeConversionFactor' attribute of this Submodel.

unsetTimeConversionFactor()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are: