EventAssignment_t Class Reference

Detailed Description

An assignment to a variable by an SBML event.

Event_t contains an optional element called "listOfEventAssignments", of class ListOfEventAssignments_t. In every instance of an event definition in a model, the object's "listOfEventAssignments" element must have a non-empty list of one or more "eventAssignment" elements of class EventAssignment_t. The object class EventAssignment_t has one required attribute, "variable", and a required element, "math". Being derived from SBase_t, it also has all the usual attributes and elements of its parent class.

An Event_t object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The purpose of the EventAssignment_t object class is to define how variables are affected by an Event_t. In SBML Level 2, every Event_t object instance must have a nonempty list of event assignments; in SBML Level 3, the list of assignments is optional.

The operation of an Event_t is divided into two phases (regardless of whether a delay is involved): one phase when the event is triggered, and the other when the event is executed. EventAssignment_t objects are interpreted when an event is executed. The effects are described below.

The attribute "variable"

The EventAssignment_t attribute "variable" must be the identifier of an existing Compartment_t, Species_t, SpeciesReference_t, or Parameter_t instance defined in the model. In SBML Level 3 Version 2, this list was expanded to include identifiers of SBML Level 3 package variables that have both mathematical meaning and the ability to be assigned. When the event is executed, the value of the model component identified by "variable" is changed by the EventAssignment_t to the value computed by the "math" element; that is, a species' quantity, species reference's stoichiometry, compartment's size or parameter's value are reset to the value computed by "math".

Certain restrictions are placed on what can appear in "variable":

• The object identified by the value of the EventAssignment_t attribute "variable" must not have its "constant" attribute set to or default to true. (Constants cannot be affected by events.)

• The "variable" attribute must not contain the identifier of a reaction. In SBML Level 2 and SBML Level 3 Version 1, only species, species references, compartment and parameter values may be set by an Event_t. In SBML Level 3 Version 2, the "variable" attribute may also be the identifier of an SBML Level 3 package element with mathematical meaning and the ability to be assigned a value. This situation may only arise if the SBML package is present in the SBML document with a package:required attribute of true

• The value of every "variable" attribute must be unique among the set of EventAssignment_t structures within a given Event_t structure. In other words, a single event cannot have multiple EventAssignment_t objects assigning the same variable. (All of them would be performed at the same time when that particular Event_t triggers, resulting in indeterminacy.) However, separate Event_t instances can refer to the same variable.

• A variable cannot be assigned a value in an EventAssignment_t object instance and also be assigned a value by an AssignmentRule_t; i.e., the value of an EventAssignment_t's "variable" attribute cannot be the same as the value of a AssignmentRule_t' "variable" attribute. (Assignment rules hold at all times, therefore it would be inconsistent to also define an event that reassigns the value of the same variable.)

If the variable attribute of an EventAssignment_t object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level 3 package that the software does not support), the event assignment must be ignored–the object's value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

Note that the time of assignment of the object identified by the value of the "variable" attribute is always the time at which the Event_t is executed, not when it is triggered. The timing is controlled by the optional Delay_t in an Event_t. The time of assignment is not affected by the "useValuesFromTriggerTime" attribute on Event_t—that attribute affects the time at which the EventAssignment_t's "math" expression is evaluated. In other words, SBML allows decoupling the time at which the "variable" is assigned from the time at which its value expression is calculated.

The "math" subelement in an EventAssignment_t

The MathML expression contained in an EventAssignment_t defines the new value of the variable being assigned by the Event_t.

As mentioned above, the time at which the expression in "math" is evaluated is determined by the attribute "useValuesFromTriggerTime" on Event_t. If the attribute value is true, the expression must be evaluated when the event is triggered; more precisely, the values of identifiers occurring in MathML <ci> elements in the EventAssignment_t's "math" expression are the values they have at the point when the event triggered. If, instead, "useValuesFromTriggerTime"'s value is false, it means the values at execution time should be used; that is, the values of identifiers occurring in MathML <ci> elements in the EventAssignment_t's "math" expression are the values they have at the point when the event executed.

SBML Level/Version differences

Between Version 4 and previous versions of SBML Level 2, the requirements regarding the matching of units between an EvengAssignment's formula and the units of the object identified by the "variable" attribute changed. Previous versions required consistency, but in SBML Level 2 Version 4 and in SBML Level 3, unit consistency is only recommended. More precisely:

• In the case of a species, an EventAssignment_t sets the referenced species' quantity (concentration or amount of substance) to the value determined by the formula in the EventAssignment_t's "math" subelement. The units of the "math" formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units of the species.

• (SBML Level 3 only.) In the case of a species reference, an EventAssignment_t sets the stoichiometry of the reactant or product referenced by the SpeciesReference_t object to the value determined by the formula in the "math" element. The unit associated with the value produced by the "math" formula should be dimensionless, because reactant and product stoichiometries in reactions are dimensionless quantities.

• In the case of a compartment, an EventAssignment_t sets the referenced compartment's size to the size determined by the formula in the "math" subelement of the EventAssignment_t. The overall units of the formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units specified for the size of the compartment identified by the EventAssignment_t's "variable" attribute.

• In the case of a parameter, an EventAssignment_t sets the referenced parameter's value to that determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and Level 3) or must (in previous Versions of Level 2) be identical to the units defined for the parameter.

• (For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an EventAssignment_t sets the referenced object's value (as defined by that package) to the value of the formula in "math". The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute), or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units).

Note that the formula placed in the "math" element has no assumed units. The consistency of the units of the formula, and the units of the entity which the assignment affects, must be explicitly established just as in the case of the value of the Delay_t subelement. An approach similar to the one discussed in the context of Delay_t may be used for the formula of an EventAssignment_t.

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, the requirement that an EventAssignment_t have a "math" subelement was relaxed, making it optional. In this case, the EventAssignment_t remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event_t behaves as if it had no EventAssignment_t.

See also

Event_t

Examples:

printAnnotation.c, printMath.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
EventAssignment_t *	EventAssignment_clone (const EventAssignment_t *ea)
	Creates a (deep) copy of the given EventAssignment_t structure. More...
int	EventAssignment_containsUndeclaredUnits (EventAssignment_t *ea)
	Predicate returning 1 (true) or 0 (false) depending on whether the math expression of this EventAssignment_t contains parameters/numbers with undeclared units. More...
EventAssignment_t *	EventAssignment_create (unsigned int level, unsigned int version)
	Creates a new EventAssignment_t structure using the given SBML level and version values. More...
EventAssignment_t *	EventAssignment_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new EventAssignment_t structure using the given SBMLNamespaces_t structure. More...
void	EventAssignment_free (EventAssignment_t *ea)
	Frees the given EventAssignment_t structure. More...
UnitDefinition_t *	EventAssignment_getDerivedUnitDefinition (EventAssignment_t *ea)
	Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this EventAssignment_t. More...
const ASTNode_t *	EventAssignment_getMath (const EventAssignment_t *ea)
	Gets the mathematical formula stored in the given EventAssignment_t structure. More...
const XMLNamespaces_t *	EventAssignment_getNamespaces (EventAssignment_t *ea)
	Returns a list of XMLNamespaces_t associated with this EventAssignment_t structure. More...
const char *	EventAssignment_getVariable (const EventAssignment_t *ea)
	Gets the value of the "variable" attribute of this EventAssignment_t structure. More...
int	EventAssignment_isSetMath (const EventAssignment_t *ea)
	Predicate for testing whether the attribute "variable" of the given EventAssignment_t structure is set. More...
int	EventAssignment_isSetVariable (const EventAssignment_t *ea)
	Predicate for testing whether the attribute "variable" of the given EventAssignment_t structure is set. More...
int	EventAssignment_setMath (EventAssignment_t *ea, const ASTNode_t *math)
	Sets the "math" subelement content of the given EventAssignment_t structure to the given ASTNode_t. More...
int	EventAssignment_setVariable (EventAssignment_t *ea, const char *sid)
	Sets the attribute "variable" of the given EventAssignment_t structure to a copy of the given identifier string. More...
int	EventAssignment_unsetVariable (EventAssignment_t *ea)
	Unsets the attribute "variable" of the given EventAssignment_t structure. More...

Member Function Documentation

EventAssignment_t * EventAssignment_clone

(

const EventAssignment_t *

ea

)

Creates a (deep) copy of the given EventAssignment_t structure.

Parameters

ea	the EventAssignment_t to be copied.

Returns

a (deep) copy of ea.

int EventAssignment_containsUndeclaredUnits

(

EventAssignment_t *

ea

)

Predicate returning 1 (true) or 0 (false) depending on whether the math expression of this EventAssignment_t contains parameters/numbers with undeclared units.

Returns

1 (true) if the math expression of this EventAssignment_t includes parameters/numbers with undeclared units, 0 (false) otherwise.

Note

a return value of 1 (true) indicates that the UnitDefinition_t returned by the getDerivedUnitDefinition function may not accurately represent the units of the expression.

See also

EventAssignment_getDerivedUnitDefinition()

Examples:

printUnits.c.

EventAssignment_t * EventAssignment_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new EventAssignment_t structure using the given SBML level and version values.

Parameters

level	an unsigned int, the SBML Level to assign to this EventAssignment_t.
version	an unsigned int, the SBML Version to assign to this EventAssignment_t.

Returns

a pointer to the newly created EventAssignment_t structure.

Note

Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

EventAssignment_t * EventAssignment_createWithNS

(

SBMLNamespaces_t *

sbmlns

)

Creates a new EventAssignment_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns

SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this EventAssignment_t.

Returns

a pointer to the newly created EventAssignment_t structure.

Note

Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

void EventAssignment_free

(

EventAssignment_t *

ea

)

Frees the given EventAssignment_t structure.

Parameters

ea	the EventAssignment_t to be freed.

UnitDefinition_t * EventAssignment_getDerivedUnitDefinition

(

EventAssignment_t *

ea

)

Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this EventAssignment_t.

Returns

a UnitDefinition_t that expresses the units of the math expression of this EventAssignment_t.

Note that the functionality that facilitates unit analysis depends on the model as a whole. Thus, in cases where the structure has not been added to a model or the model itself is incomplete, unit analysis is not possible and this method will return NULL.

Note

The units are calculated by applying the mathematics from the expression to the units of the <ci> elements used within the expression. Where there are parameters/numbers with undeclared units the UnitDefinition_t returned by this function may not accurately represent the units of the expression.

See also

EventAssignment_containsUndeclaredUnits()

Examples:

printUnits.c.

const ASTNode_t * EventAssignment_getMath

(

const EventAssignment_t *

ea

)

Gets the mathematical formula stored in the given EventAssignment_t structure.

Parameters

ea	the EventAssignment_t structure to query.

Returns

the ASTNode_t tree stored in ea.

Examples:

printMath.c.

const XMLNamespaces_t * EventAssignment_getNamespaces

(

EventAssignment_t *

ea

)

Returns a list of XMLNamespaces_t associated with this EventAssignment_t structure.

Parameters

ea	the EventAssignment_t structure.

Returns

pointer to the XMLNamespaces_t structure associated with this structure

const char * EventAssignment_getVariable

(

const EventAssignment_t *

ea

)

Gets the value of the "variable" attribute of this EventAssignment_t structure.

Parameters

ea	the EventAssignment_t structure to query.

Returns

the identifier stored in the "variable" attribute of ea.

Examples:

printMath.c.

int EventAssignment_isSetMath

(

const EventAssignment_t *

ea

)

Predicate for testing whether the attribute "variable" of the given EventAssignment_t structure is set.

Parameters

ea	the EventAssignment_t structure to query.

Returns

1 (true) if the "variable" attribute of ea is set, 0 (false) otherwise.

Examples:

printMath.c.

int EventAssignment_isSetVariable

(

const EventAssignment_t *

ea

)

Predicate for testing whether the attribute "variable" of the given EventAssignment_t structure is set.

Parameters

ea	the EventAssignment_t structure to query.

Returns

1 (true) if the "variable" attribute of ea is set, 0 (false) otherwise.

int EventAssignment_setMath	(	EventAssignment_t *	ea,
		const ASTNode_t *	math
	)

Sets the "math" subelement content of the given EventAssignment_t structure to the given ASTNode_t.

The given math ASTNode_t is copied.

Parameters

ea	the EventAssignment_t to set.
math	the ASTNode_t to copy into ea.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

int EventAssignment_setVariable	(	EventAssignment_t *	ea,
		const char *	sid
	)

Sets the attribute "variable" of the given EventAssignment_t structure to a copy of the given identifier string.

Parameters

ea	the EventAssignment_t to set.
sid	the identifier of an element defined in this model that can vary over time.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE

Note

Using this function with an sid of NULL is equivalent to unsetting the "variable" attribute.

int EventAssignment_unsetVariable

(

EventAssignment_t *

ea

)

Unsets the attribute "variable" of the given EventAssignment_t structure.

Parameters

ea	the EventAssignment_t to set.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE