Skip to content

ReplacedElement

An element of a submodel which the element carrying it takes the place of.

A replacement is the glue of a composed model. The element which carries the replaced element stays, the element it names disappears, and every reference to the one that disappeared points at the one that stays. Two submodels are connected by letting one element of the containing model replace an element of each: the three become one.

Each replaced element names the submodel it reaches into and one element inside it, by port, identifier, unit identifier or meta id, and reaches deeper with a nested reference. It may carry a conversion factor which rescales the replaced value, and instead of naming an element it may name a deletion, which records that the element takes the place of something the submodel lost.

The report lists the replacements of an element in its inspector, links the submodel and the element inside it, and shows every replacement as an element of its own.

Attributes

attribute type required meaning specification
submodelRef SIdRef required the submodel which holds the replaced element comp 3.6.2
deletion SIdRef optional the deletion of the submodel whose element this element takes the place of comp 3.6.2
conversionFactor SIdRef optional the parameter which rescales the replaced value to the scale of this element comp 3.6.2
portRef PortSIdRef optional the port of the submodel whose element is replaced comp 3.7.1
idRef SIdRef optional the element which is replaced, by its identifier comp 3.7.1
unitRef UnitSIdRef optional the unit definition which is replaced comp 3.7.1
metaIdRef IDREF optional the element which is replaced, by its meta id comp 3.7.1
sBaseRef SBaseRef optional the reference which reaches into a submodel of the named submodel comp 3.7.2

Every element of a model also carries the common attributes of SBase.

submodelRef

The reference names a submodel of the model which carries the replacement. It is required, and it says which model the other references are resolved in: only elements of the model that submodel instantiates can be named.

  • 1010308 (error): The value of a 'comp:submodelRef' attribute on <replacedElement> and <replacedBy> objects must always conform to the syntax of the SBML data type SId.
  • 1021004 (error): The value of a 'comp:submodelRef' attribute on a <replacedElement> object must be the identifier of a <submodel> present in the <replacedElement> object's parent Model.

deletion

The reference names a deletion of the named submodel and takes the place of the four references: instead of an element which is replaced, the replacement names an element which was removed. It changes nothing about the composed model and nothing about its mathematics; it records the decision that this element is what the submodel lost, so that a reader, and a tool which draws the model, can follow it.

  • 1010309 (error): The value of a 'comp:deletion' attribute on <replacedElement> objects must always conform to the syntax of the SBML data type SId.
  • 1021001 (error): A <replacedElement> object must point to another object; that is, a <replacedElement> object must always have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021002 (error): A <replacedElement> object can only point to one other object; that is, a given <replacedElement> object can only have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021005 (error): The value of a 'comp:deletion' attribute on a <replacedElement> object must be the identifier of a <deletion> present in the <replacedElement> object's parent Model.
  • 1021011 (error): If a <replacedElement> uses the 'comp:deletion' attribute, then it should not also use the 'comp:conversionFactor' attribute.

conversionFactor

The reference names a parameter of the model which carries the replacement. One unit of the replaced element multiplied by the factor is one unit of the replacing element, which is how a submodel written in millimole is used by a model written in mole. The factor applies to every reference to the replaced element, and the factors of nested replacements multiply.

A replacement cannot carry a conversion factor and a deletion at the same time: what is deleted has no value left to convert.

Default: the value of the replaced element is taken over unchanged, apart from the conversion factors of the submodel.

  • 1010310 (error): The value of a 'comp:conversionFactor' attribute on <replacedElement> objects must always conform to the syntax of the SBML data type SId.
  • 1010501 (warning): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, the units of the replaced element, multiplied by the units of any applicable conversion factor, should equal the units of the replacement element.
  • 1021006 (error): The value of a 'comp:conversionFactor' attribute on a <replacedElement> object must be the identifier of a <parameter> present in the <replacedElement> object's parent Model
  • 1021011 (error): If a <replacedElement> uses the 'comp:deletion' attribute, then it should not also use the 'comp:conversionFactor' attribute.

portRef

The replacement names a port of the model the submodel instantiates, and the element behind that port is what is replaced. It is the first choice of the specification, because the port is the interface the other model offers.

  • 1020701 (error): The value of a 'comp:portRef' attribute on an <sBaseRef> object must be the identifier of a <port> object in the <model> referenced by that <sBaseRef>.
  • 1020706 (error): The value of a 'comp:portRef' attribute on an SBaseRef object must always conform to the syntax of the SBML data type SId.
  • 1021001 (error): A <replacedElement> object must point to another object; that is, a <replacedElement> object must always have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021002 (error): A <replacedElement> object can only point to one other object; that is, a given <replacedElement> object can only have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.

idRef

The identifier is resolved in the model the named submodel instantiates. It is the choice for an element which no port exposes.

  • 1020702 (error): The value of a 'comp:idRef' attribute on an <sBaseRef> object must be the identifier of an object contained in (that is, within the SId namespace of) the <model> referenced by that <sBaseRef>. This includes objects with 'id' attributes defined in packages other than SBML Level 3 Core or the Hierarchical Model Composition package.
  • 1020707 (error): The value of a 'comp:idRef' attribute on an SBaseRef object must always conform to the syntax of the SBML data type SId.
  • 1021001 (error): A <replacedElement> object must point to another object; that is, a <replacedElement> object must always have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021002 (error): A <replacedElement> object can only point to one other object; that is, a given <replacedElement> object can only have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.

unitRef

Unit identifiers live in a namespace of their own. The units which SBML reserves cannot be replaced.

  • 1020703 (error): The value of a 'comp:unitRef' attribute on an <sBaseRef> object must be the identifier of a <unitDefinition< object contained in the <model> referenced by that <sBaseRef>.
  • 1020708 (error): The value of a 'comp:unitRef' attribute on an SBaseRef object must always conform to the syntax of the SBML data type SId.
  • 1021001 (error): A <replacedElement> object must point to another object; that is, a <replacedElement> object must always have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021002 (error): A <replacedElement> object can only point to one other object; that is, a given <replacedElement> object can only have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.

metaIdRef

This is the way to replace an element which carries no identifier of its own.

  • 1020704 (error): The value of a 'comp:metaIdRef' attribute on an <sBaseRef> object must be the value of a 'comp:metaid' attribute on an element contained in the <model> referenced by that <sBaseRef>.
  • 1020709 (error): The value of a 'comp:metaIdRef' attribute on an SBaseRef object must always conform to the syntax of the XML data type ID.
  • 1021001 (error): A <replacedElement> object must point to another object; that is, a <replacedElement> object must always have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.
  • 1021002 (error): A <replacedElement> object can only point to one other object; that is, a given <replacedElement> object can only have a value for one of the attributes 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef' or 'comp:deletion'.

sBaseRef

A replacement which names a submodel of the instantiated model carries a nested reference which names the element inside it, so that an element of a sub-submodel can be replaced.

  • 1020705 (error): If an <sBaseRef> object contains an <sBaseRef> child, the parent <sBaseRef> must point to a <submodel> object, or a <port> that itself points to a <submodel> object.
  • 1020710 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, an SBaseRef object may only contain a single <sBaseRef> child.
  • 1020711 (warning): The 'sbaseRef' spelling of an SBaseRef child of an SBaseRef object is considered deprecated, and 'sBaseRef' should be used instead.

Validation rules

  • 1010501 (warning): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, the units of the replaced element, multiplied by the units of any applicable conversion factor, should equal the units of the replacement element.
  • 1020710 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, an SBaseRef object may only contain a single <sBaseRef> child.
  • 1020714 (error): Any one SBML object may only be referenced in one of the following ways: referenced by a single <port> object; referenced by a single <deletion> object; referenced by a single <replacedElement>; be the parent of a single <replacedBy> child; be referenced by one or more <replacedBy> objects; or be referenced by one or more <replacedElement> objects all using the 'deletion' attribute. Essentially, once an object has been referenced in one of these ways it cannot be referenced again.
  • 1021003 (error): A <replacedElement> object must have a value for the required attribute 'comp:submodelRef', and a value for one, and only one, of the following attributes: 'comp:portRef', 'comp:idRef', 'comp:unitRef', 'comp:metaIdRef', or 'comp:deletion'. It may also have a value for the optional attribute 'comp:conversionFactor'. No other attributes from the HierarchicalModel Composition namespace are permitted on a <replacedElement> object.
  • 1021010 (error): No two <replacedElement> objects in the same Model may reference the same object unless that object is a <deletion>
  • 1021201 (error): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, the SBML class of the replacement element must match the SBML class of the replaced element, with two exceptions: an element of a derived class may replace an object of its base class (for base classes other than SBase), and any SBML class with mathematical meaning may replace a <parameter>. A base class may not replace a derived class, however, nor may a <parameter> replace some other SBML element with mathematical meaning.
  • 1021202 (error): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, if the replaced element has the 'id' attribute set, the replacement !element must also have the 'id' attribute set.
  • 1021203 (error): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, if the replaced element has the 'metaid' attribute set, the replacement element must also have the 'metaid' attribute set.
  • 1021204 (error): If one element replaces another, whether it is the target of a <replacedBy> element, or whether it has a child <replacedElement>, if the replaced element has an identifier attribute from some other SBML package set, the replacement element must also have that same identifier attribute set.
  • Submodel: the instantiation of another model inside this model
  • ReplacedBy: the element of a submodel which takes the place of the element carrying it
  • Deletion: an element which is removed from a submodel before it is instantiated
  • Hierarchical Model Composition (comp): the package which builds a model out of other models

Specification

SBML Level 3 Package: Hierarchical Model Composition, Version 1 Release 3, Section 3.6.2 (Smith et al. 2015, J Integr Bioinform 12(2):268).