libSBML C API
libSBML 5.8.0 C API
|
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.