Detailed Description

comp Indicates an object replaces another.

The ReplacedElement_t class was introduced by the SBML Level 3 Hierarchical Model_t Composition (“comp”) package to allow submodel elements to be replaced, but still allow references to those elements to be valid. A ReplacedElement_t object is essentially a pointer to a submodel object that should be considered 'replaced'. The object holding the ReplacedElement_t instance is the one doing the replacing; the object pointed to by the ReplacedElement_t 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_t 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_t object, it is necessary to examine the local parameters of that kinetic law's parent Reaction_t 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_t element to which it belongs.

When referencing an element within the Submodel_t pointed to by the "submodelRef" attribute (defined in libSBML in the Replacing_t class), any of the four attributes inherited from SBaseRef_t 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_t object in the parent Model_t of the ReplacedElement_t (i.e., the value of some Deletion_t object's "id" attribute). When "deletion" is set, it means the ReplacedElement_t 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_t: instead of using, e.g., "portRef" or "idRef", the ReplacedElement_t instance sets "deletion" to the identifier of the Deletion_t object. In addition, the referenced Deletion_t must be a child of the Submodel_t referenced by the "submodelRef" attribute.

The use of ReplacedElement_t 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_t objects in SBML.

As with the Submodel_t 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_t 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_t may be non-constant, particularly if a Species_t is replaced by a Species_t with a different "hasOnlySubstanceUnits" attribute value, thus changing amount to concentration, or visa versa.

Public Member Functions
ReplacedElement_t *	ReplacedElement_clone (ReplacedElement_t *re)
	Returns a copy of the given ReplacedElement_t structure. More...

ReplacedElement_t *	ReplacedElement_create (unsigned int level, unsigned int version, unsigned int pkgVersion)
	Creates a new ReplacedElement_t structure using the given SBML `level` and `version`, and the `pkgVersion` package version. More...

void	ReplacedElement_free (ReplacedElement_t *re)
	Frees the given ReplacedElement_t structure. More...

char *	ReplacedElement_getConversionFactor (ReplacedElement_t *re)
	Takes a ReplacedElement_t structure and returns its conversionFactor. More...

char *	ReplacedElement_getDeletion (ReplacedElement_t *re)
	Takes a ReplacedElement_t structure and returns its deletion. More...

char *	ReplacedElement_getSubmodelRef (ReplacedElement_t *re)
	Takes a ReplacedElement_t structure and returns its submodelRef. More...

int	ReplacedElement_hasRequiredAttributes (ReplacedElement_t *re)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for the given ReplacedElement_t structure have been set. More...

int	ReplacedElement_isSetConversionFactor (ReplacedElement_t *re)
	Predicate returning `1` (true) or `0` (false) depending on whether the given ReplacedElement_t structure's conversionFactor is set. More...

int	ReplacedElement_isSetDeletion (ReplacedElement_t *re)
	Predicate returning `1` (true) or `0` (false) depending on whether the given ReplacedElement_t structure's deletion is set. More...

int	ReplacedElement_isSetSubmodelRef (ReplacedElement_t *re)
	Predicate returning `1` (true) or `0` (false) depending on whether the given ReplacedElement_t structure's submodelRef is set. More...

int	ReplacedElement_setConversionFactor (ReplacedElement_t re, const char conversionFactor)
	Sets the conversionFactor of the given ReplacedElement_t to a copy of `conversionFactor`. More...

int	ReplacedElement_setDeletion (ReplacedElement_t re, const char deletion)
	Sets the deletion of the given ReplacedElement_t to a copy of `deletion`. More...

int	ReplacedElement_setSubmodelRef (ReplacedElement_t re, const char submodelRef)
	Sets the submodelRef of the given ReplacedElement_t to a copy of `submodelRef`. More...

int	ReplacedElement_unsetConversionFactor (ReplacedElement_t *re)
	Unsets the "conversionFactor" attribute of the given ReplacedElement_t structure. More...

int	ReplacedElement_unsetDeletion (ReplacedElement_t *re)
	Unsets the "deletion" attribute of the given ReplacedElement_t structure. More...

int	ReplacedElement_unsetSubmodelRef (ReplacedElement_t *re)
	Unsets the "submodelRef" attribute of the given ReplacedElement_t structure. More...

Member Function Documentation

ReplacedElement_t * ReplacedElement_clone ( ReplacedElement_t * re )

Returns a copy of the given ReplacedElement_t structure.

Parameters

re	the ReplacedElement_t structure to copy.

Returns: a (deep) copy of the ReplacedElement_t.

ReplacedElement_t * ReplacedElement_create	(	unsigned int	level,
		unsigned int	version,
		unsigned int	pkgVersion
	)

Creates a new ReplacedElement_t structure using the given SBML level and version, and the pkgVersion package version.

Parameters

level	an unsigned int, the SBML Level to assign to this ReplacedElement_t.
version	an unsigned int, the SBML Version to assign to this ReplacedElement_t.
pkgVersion	an unsigned int, the SBML 'comp' package Version to assign to this ReplacedElement_t.

Returns: a pointer to the newly created ReplacedElement_t structure.

void ReplacedElement_free ( ReplacedElement_t * re )

Frees the given ReplacedElement_t structure.

Parameters

re	the ReplacedElement_t structure to free.

char * ReplacedElement_getConversionFactor ( ReplacedElement_t * re )

Takes a ReplacedElement_t structure and returns its conversionFactor.

Parameters

re	the ReplacedElement_t whose conversionFactor is sought.

Returns: the conversionFactor of the given ReplacedElement_t, as a pointer to a string.

char * ReplacedElement_getDeletion ( ReplacedElement_t * re )

Takes a ReplacedElement_t structure and returns its deletion.

Parameters

re	the ReplacedElement_t whose deletion is sought.

Returns: the deletion of the given ReplacedElement_t, as a pointer to a string.

char * ReplacedElement_getSubmodelRef ( ReplacedElement_t * re )

Takes a ReplacedElement_t structure and returns its submodelRef.

Parameters

re	the ReplacedElement_t whose submodelRef is sought.

Returns: the submodelRef of the given ReplacedElement_t, as a pointer to a string.

int ReplacedElement_hasRequiredAttributes ( ReplacedElement_t * re )

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for the given ReplacedElement_t structure have been set.

Note: The required attributes for a ReplacedElement_t structure are that it uses exactly one attribute to refer to its target, and that the submodelRef is set.

int ReplacedElement_isSetConversionFactor ( ReplacedElement_t * re )

Predicate returning 1 (true) or 0 (false) depending on whether the given ReplacedElement_t structure's conversionFactor is set.

Parameters

re	the ReplacedElement_t structure to query.

Returns: 1 (true) if the "conversionFactor" attribute of the given ReplacedElement_t structure is set, 0 (false) otherwise.

int ReplacedElement_isSetDeletion ( ReplacedElement_t * re )

Predicate returning 1 (true) or 0 (false) depending on whether the given ReplacedElement_t structure's deletion is set.

Parameters

re	the ReplacedElement_t structure to query.

Returns: 1 (true) if the "deletion" attribute of the given ReplacedElement_t structure is set, 0 (false) otherwise.

int ReplacedElement_isSetSubmodelRef ( ReplacedElement_t * re )

Predicate returning 1 (true) or 0 (false) depending on whether the given ReplacedElement_t structure's submodelRef is set.

Parameters

re	the ReplacedElement_t structure to query.

Returns: 1 (true) if the "submodelRef" attribute of the given ReplacedElement_t structure is set, 0 (false) otherwise.

int ReplacedElement_setConversionFactor	(	ReplacedElement_t *	re,
		const char *	conversionFactor
	)

Sets the conversionFactor of the given ReplacedElement_t to a copy of conversionFactor.

Parameters

re	the ReplacedElement_t structure to set.
conversionFactor	the conversionFactor to assign to the given ReplacedElement_t's "conversionFactor" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with the name set to NULL is equivalent to unsetting the "conversionFactor" attribute.

int ReplacedElement_setDeletion	(	ReplacedElement_t *	re,
		const char *	deletion
	)

Sets the deletion of the given ReplacedElement_t to a copy of deletion.

Parameters

re	the ReplacedElement_t structure to set.
deletion	the deletion to assign to the given ReplacedElement_t's "deletion" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with the name set to NULL is equivalent to unsetting the "deletion" attribute.

int ReplacedElement_setSubmodelRef	(	ReplacedElement_t *	re,
		const char *	submodelRef
	)

Sets the submodelRef of the given ReplacedElement_t to a copy of submodelRef.

Parameters

re	the ReplacedElement_t structure to set.
submodelRef	the submodelRef to assign to the given ReplacedElement_t's "submodelRef" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with the name set to NULL is equivalent to unsetting the "submodelRef" attribute.

int ReplacedElement_unsetConversionFactor ( ReplacedElement_t * re )

Unsets the "conversionFactor" attribute of the given ReplacedElement_t structure.

Parameters

re	the ReplacedElement_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int ReplacedElement_unsetDeletion ( ReplacedElement_t * re )

Unsets the "deletion" attribute of the given ReplacedElement_t structure.

Parameters

re	the ReplacedElement_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int ReplacedElement_unsetSubmodelRef ( ReplacedElement_t * re )

Unsets the "submodelRef" attribute of the given ReplacedElement_t structure.

Parameters

re	the ReplacedElement_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Detailed Description

Public Member Functions

Member Function Documentation