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

Detailed Description

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.

Public Member Functions

def __init__ (self, args)
 comp Indicates an object replaces another. More...
 
def clearReferencedElement (self)
 Removes the saved referenced element, if it had been saved earlier. More...
 
def clone (self)
 Creates and returns a deep copy of this ReplacedElement object. More...
 
def connectToChild (self)
 
def createSBaseRef (self)
 Creates a new, empty SBaseRef, adds it to this SBaseRef and returns the created SBaseRef. More...
 
def getConversionFactor (self)
 Returns the value of the 'conversionFactor' attribute of this ReplacedElement. More...
 
def getDeletion (self)
 Returns the value of the 'deletion' attribute of this ReplacedElement. 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 getIdRef (self)
 Returns the value of the 'idRef' attribute of this SBaseRef. More...
 
def getMetaIdRef (self)
 Returns the value of the 'metaIdRef' attribute of this SBaseRef. More...
 
def getNumReferents (self)
 Returns how many elements are being referred to by this ReplacedElement. More...
 
def getPortRef (self)
 Returns the value of the 'portRef' attribute of this SBaseRef. More...
 
def getReferencedElement (self)
 Returns the object pointed to by this element. More...
 
def getReferencedElementFrom (self, model)
 Finds the SBase object this ReplacedElement object points to, if any. More...
 
def getSBaseRef (self, args)
 Get the child sBaseRef of this sBaseRef. More...
 
def getSubmodelRef (self)
 comp Convenience class. More...
 
def getTypeCode (self)
 Returns the libSBML type code of this object instance. More...
 
def getUnitRef (self)
 Returns the value of the 'unitRef' attribute of this SBaseRef. More...
 
def hasRequiredAttributes (self)
 Returns true if getNumReferents() is exactly 1 and if the submodelRef is set. More...
 
def isSetConversionFactor (self)
 Predicate returning True or False depending on whether this ReplacedElement's 'conversionFactor' attribute has been set. More...
 
def isSetDeletion (self)
 Predicate returning True or False depending on whether this SBaseRef's 'deletion' attribute has been set. More...
 
def isSetIdRef (self)
 Predicate returning True or False depending on whether this SBaseRef's 'idRef' attribute has been set. More...
 
def isSetMetaIdRef (self)
 Predicate returning True or False depending on whether this SBaseRef's 'metaIdRef' attribute has been set. More...
 
def isSetPortRef (self)
 Predicate returning True or False depending on whether this SBaseRef's 'portRef' attribute has been set. More...
 
def isSetSBaseRef (self)
 Predicate for testing whether the sBaseRef for this SBaseRef is set. More...
 
def isSetSubmodelRef (self)
 Predicate returning True or False depending on whether this SBaseRef's 'submodelRef' attribute has been set. More...
 
def isSetUnitRef (self)
 Predicate returning True or False depending on whether this SBaseRef's 'unitRef' attribute has been set. More...
 
def performDeletion (self)
 DEPRECATED FUNCTION: DO NOT USE. More...
 
def performReplacement (self)
 DEPRECATED FUNCTION: DO NOT USE. More...
 
def removeFromParentAndDelete (self)
 Finds this SBaseRef's parent, which can either be a List or can be another SBaseRef, and tells it to remove this. More...
 
def renameSIdRefs (self, oldid, newid)
 Replaces all uses of a given SIdRef type attribute value with another value. More...
 
def saveReferencedElement (self)
 Finds and stores the referenced object. More...
 
def setConversionFactor (self, id)
 Sets the value of the 'conversionFactor' attribute of this ReplacedElement. More...
 
def setDeletion (self, id)
 Sets the value of the 'deletion' attribute of this ReplacedElement. More...
 
def setIdRef (self, id)
 Sets the value of the 'idRef' attribute of this SBaseRef. More...
 
def setMetaIdRef (self, id)
 Sets the value of the 'metaIdRef' attribute of this SBaseRef. More...
 
def setPortRef (self, id)
 Sets the value of the 'portRef' attribute of this SBaseRef. More...
 
def setSBaseRef (self, sBaseRef)
 Sets the sBaseRef definition of this SBaseRef to a copy of the given SBaseRef object instance. More...
 
def setSubmodelRef (self, id)
 Sets the value of the 'submodelRef' attribute of this SBaseRef. More...
 
def setUnitRef (self, id)
 Sets the value of the 'unitRef' attribute of this SBaseRef. More...
 
def unsetConversionFactor (self)
 Unsets the value of the 'conversionFactor' attribute of this ReplacedElement. More...
 
def unsetDeletion (self)
 Unsets the value of the 'deletion' attribute of this ReplacedElement. More...
 
def unsetIdRef (self)
 Unsets the value of the 'idRef' attribute of this SBaseRef. More...
 
def unsetMetaIdRef (self)
 Unsets the value of the 'metaIdRef' attribute of this SBaseRef. More...
 
def unsetPortRef (self)
 Unsets the value of the 'portRef' attribute of this SBaseRef. More...
 
def unsetSBaseRef (self)
 Unsets the child SBaseRef of this SBaseRef. More...
 
def unsetSubmodelRef (self)
 Unsets the value of the 'SubmodelRef' attribute of this SBaseRef. More...
 
def unsetUnitRef (self)
 Unsets the value of the 'unitRef' attribute of this SBaseRef. More...
 

Member Function Documentation

def libsbml.SBaseRef.clearReferencedElement (   self)
inherited

Removes the saved referenced element, if it had been saved earlier.

clearReferencedElement()
def libsbml.ReplacedElement.clone (   self)

Creates and returns a deep copy of this ReplacedElement object.

clone()   ReplacedElement
Returns
a (deep) copy of this ReplacedElement object
def libsbml.SBaseRef.connectToChild (   self)
inherited
connectToChild()
def libsbml.SBaseRef.createSBaseRef (   self)
inherited

Creates a new, empty SBaseRef, adds it to this SBaseRef and returns the created SBaseRef.

createSBaseRef()   SBaseRef
Returns
the newly created SBaseRef object instance.
def libsbml.ReplacedElement.getConversionFactor (   self)

Returns the value of the 'conversionFactor' attribute of this ReplacedElement.

getConversionFactor()   string
Returns
the value of the 'conversionFactor' attribute of this ReplacedElement.
def libsbml.ReplacedElement.getDeletion (   self)

Returns the value of the 'deletion' attribute of this ReplacedElement.

getDeletion()   string
Returns
the value of the 'deletion' attribute of this ReplacedElement.
def libsbml.SBaseRef.getElementByMetaId (   self,
  metaid 
)
inherited

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.SBaseRef.getElementBySId (   self,
  id 
)
inherited

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.ReplacedElement.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.SBaseRef.getIdRef (   self)
inherited

Returns the value of the 'idRef' attribute of this SBaseRef.

getIdRef()   string
Returns
the value of the 'idRef' attribute of this SBaseRef.
def libsbml.SBaseRef.getMetaIdRef (   self)
inherited

Returns the value of the 'metaIdRef' attribute of this SBaseRef.

getMetaIdRef()   string
Returns
the value of the 'metaIdRef' attribute of this SBaseRef.
def libsbml.ReplacedElement.getNumReferents (   self)

Returns how many elements are being referred to by this ReplacedElement.

getNumReferents()   int

A valid ReplacedElement will have exactly one. Possible referents are deletion, port, idRef, unitRef, and metaIdRef.

Returns
integer value between 0 and 5: the number of different ways this element points to its referent.
def libsbml.SBaseRef.getPortRef (   self)
inherited

Returns the value of the 'portRef' attribute of this SBaseRef.

getPortRef()   string
Returns
the value of the 'portRef' attribute of this SBaseRef.
def libsbml.SBaseRef.getReferencedElement (   self)
inherited

Returns the object pointed to by this element.

getReferencedElement()   SBase

If that element was previously found and set with 'saveReferencedElement', that element is returned; otherwise, 'saveReferencedElement' is called first, and the found element is returned.

def libsbml.ReplacedElement.getReferencedElementFrom (   self,
  model 
)

Finds the SBase object this ReplacedElement object points to, if any.

getReferencedElementFrom(Model model)   SBase
def libsbml.SBaseRef.getSBaseRef (   self,
  args 
)
inherited

Get the child sBaseRef of this sBaseRef.

getSBaseRef()   SBaseRef
Returns
the SBaseRef child of this SBaseRef, or None if none exists.
def libsbml.ReplacedElement.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_REPLACEDELEMENT
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.SBaseRef.getUnitRef (   self)
inherited

Returns the value of the 'unitRef' attribute of this SBaseRef.

getUnitRef()   string
Returns
the value of the 'unitRef' attribute of this SBaseRef.
def libsbml.Replacing.hasRequiredAttributes (   self)
inherited

Returns true if getNumReferents() is exactly 1 and if the submodelRef is set.

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

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

isSetConversionFactor()   bool
Returns
True if this ReplacedElement's 'conversionFactor' attribute has been set, otherwise False is returned.
def libsbml.ReplacedElement.isSetDeletion (   self)

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

isSetDeletion()   bool
Returns
True if this ReplacedElement's 'deletion' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.isSetIdRef (   self)
inherited

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

isSetIdRef()   bool
Returns
True if this SBaseRef's 'idRef' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.isSetMetaIdRef (   self)
inherited

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

isSetMetaIdRef()   bool
Returns
True if this SBaseRef's 'metaIdRef' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.isSetPortRef (   self)
inherited

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

isSetPortRef()   bool
Returns
True if this SBaseRef's 'portRef' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.isSetSBaseRef (   self)
inherited

Predicate for testing whether the sBaseRef for this SBaseRef is set.

isSetSBaseRef()   bool
Returns
True if the sBaseRef of this SBaseRef is set, False otherwise.
def libsbml.Replacing.isSetSubmodelRef (   self)
inherited

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

isSetSubmodelRef()   bool
Returns
True if this SBaseRef's 'submodelRef' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.isSetUnitRef (   self)
inherited

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

isSetUnitRef()   bool
Returns
True if this SBaseRef's 'unitRef' attribute has been set, otherwise False is returned.
def libsbml.SBaseRef.performDeletion (   self)
inherited

DEPRECATED FUNCTION: DO NOT USE.

Deletes the referenced object, plus any other elements that element points to through ReplacedElement or ReplacedBy children.

performDeletion()   int

Instead of calling this function directly, use 'CompModelPlugin::instantiateSubmodels' instead, which deals with all the intricacies of replacements and deletions, and gives you access to the non-flattened hierarchical form of the model.

def libsbml.Replacing.performReplacement (   self)
inherited

DEPRECATED FUNCTION: DO NOT USE.

To retain old functionality, this function calls performReplacementAndCollect, and then actually removes the now-redundant element.

performReplacement()   int

However, this can lead to doubly-deleted elements, as well as the incorrect interpretation of some models. The replacement function performReplacementAndCollect has been marked protected, in the hopes that people will instead simply use CompModelPlugin::instantiateSubmodels, which hides all the complexity while still allowing access to a non-flattened version of a hierarchical model.

def libsbml.SBaseRef.removeFromParentAndDelete (   self)
inherited

Finds this SBaseRef's parent, which can either be a List or can be another SBaseRef, and tells it to remove this.

removeFromParentAndDelete()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.ReplacedElement.renameSIdRefs (   self,
  oldid,
  newid 
)

Replaces all uses of a given SIdRef type attribute value with another value.

renameSIdRefs(string oldid, string newid)
In SBML, object identifiers are of a data type called SId. In SBML Level 3, an explicit data type called SIdRef was introduced for attribute values that refer to SId values; in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to an identifier', but the effective data type was the same as SIdRefin Level 3. These and other methods of libSBML refer to the type SIdRef for all Levels of SBML, even if the corresponding SBML specification did not explicitly name the data type.

This method works by looking at all attributes and (if appropriate) mathematical formulas in MathML content, comparing the referenced identifiers to the value of oldid. If any matches are found, the matching values are replaced with newid. The method does not descend into child elements.

Parameters
oldidthe old identifier
newidthe new identifier
def libsbml.Replacing.saveReferencedElement (   self)
inherited

Finds and stores the referenced object.

saveReferencedElement()   int

Finds the Submodel to which it refers, getting the instantiated Model inside that Submodel, calling 'getReferencedElementFrom' on that model, and storing the result.

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

Sets the value of the 'conversionFactor' attribute of this ReplacedElement.

setConversionFactor(string id)   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.ReplacedElement.setDeletion (   self,
  id 
)

Sets the value of the 'deletion' attribute of this ReplacedElement.

setDeletion(string id)   int

This method fails if the id is not a valid syntax for an SIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUE), or if the SBaseRef already points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED). A ReplacedElement must use exactly one method to point to a submodel element: deletion, port, idRef, unitRef, or metaIdRef.

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

Sets the value of the 'idRef' attribute of this SBaseRef.

setIdRef(string id)   int

This method fails if the id is not a valid syntax for an SIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUE), or if the SBaseRef already points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED). A sBaseRef must use exactly one method to point to a submodel element.

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

Sets the value of the 'metaIdRef' attribute of this SBaseRef.

setMetaIdRef(string id)   int

This method fails if the id is not a valid syntax for an IDREF (LIBSBML_INVALID_ATTRIBUTE_VALUE), or if the SBaseRef already points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED). An sBaseRef must use exactly one method to point to a submodel element.

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

Sets the value of the 'portRef' attribute of this SBaseRef.

setPortRef(string id)   int

Fails if the id is not a valid syntax for a PortSIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUE), or if the SBaseRef already points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED). An SBaseRef must use exactly one method to point to a submodel element.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.setSBaseRef (   self,
  sBaseRef 
)
inherited

Sets the sBaseRef definition of this SBaseRef to a copy of the given SBaseRef object instance.

setSBaseRef(SBaseRef sBaseRef)   int

This method fails if the added sBaseRef does not match the level/version/package of the parent object or if the added sBaseRef cannot be copied.

Parameters
sBaseRefthe SBaseRef object instance to use.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.Replacing.setSubmodelRef (   self,
  id 
)
inherited

Sets the value of the 'submodelRef' attribute of this SBaseRef.

setSubmodelRef(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.SBaseRef.setUnitRef (   self,
  id 
)
inherited

Sets the value of the 'unitRef' attribute of this SBaseRef.

setUnitRef(string id)   int

This method fails if the id is not a valid syntax for a UnitSIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUE), or if the SBaseRef already points to an element of the submodel using a different interface (LIBSBML_OPERATION_FAILED). A sBaseRef must use exactly one method to point to a submodel element.

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

Unsets the value of the 'conversionFactor' attribute of this ReplacedElement.

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

Unsets the value of the 'deletion' attribute of this ReplacedElement.

unsetDeletion()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.unsetIdRef (   self)
inherited

Unsets the value of the 'idRef' attribute of this SBaseRef.

unsetIdRef()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.unsetMetaIdRef (   self)
inherited

Unsets the value of the 'metaIdRef' attribute of this SBaseRef.

unsetMetaIdRef()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.unsetPortRef (   self)
inherited

Unsets the value of the 'portRef' attribute of this SBaseRef.

unsetPortRef()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.unsetSBaseRef (   self)
inherited

Unsets the child SBaseRef of this SBaseRef.

unsetSBaseRef()   int

Deletes the former SBaseRef child, if one existed.

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

Unsets the value of the 'SubmodelRef' attribute of this SBaseRef.

unsetSubmodelRef()   int
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
def libsbml.SBaseRef.unsetUnitRef (   self)
inherited

Unsets the value of the 'unitRef' attribute of this SBaseRef.

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