Lifecycle Attributes

Home > Model Development Topics > Lifecycle Attributes

An entity can optionally include a pair of related built-in attributes, lifecycle_event and lifecycle_counter, which can be used to probe events in the entity.

Related topics

• Model Code

Topic contents

• Introduction and outline
• Activating lifecycle attributes
• Worked example 1 Activating lifecycle attributes in RiskPaths
• Lifecycle attribute maintenance
• Worked example 2 Event counts
• Worked example 3 Event counts by age
• Worked example 4 Descriptive statistics of age at an event

Introduction and outline

Content to follow.

Activating lifecycle attributes

The lifecycle attributes are not present by default. They can be created for a specific kind of entity using an option like:

options lifecycle_attributes = Person;

assuming that the model declares the Person entity. This statement causes the OpenM++ compiler to create, for the Person entity, the built-in attributes lifecycle_event and lifecycle_counter, and the supporting built-in classification LIFECYCLE_Person.

Lifecycle attributes are activated on an entity-by-entity basis. For example, assuming that the model also contains the Ticker entity, lifecycle attributes can be enabled for Ticker entities as well as Person entities using a second option statement like

options lifecycle_attributes = Ticker;

This statement would cause OpenM++ compiler to create, for the Ticker entity, the built-in attributes lifecycle_event and lifecycle_counter, and the supporting built-in classification LIFECYCLE_Ticker.

Model code should not contain clashing explicit declarations of lifecycle attributes or the supporting classification. If it does, a build error will ensure.

[back to topic contents]

Worked example 1

This section shows how to create and examine lifecycle attributes for the RiskPaths model. RiskPaths contains a single kind of entity, Person. Request the creation of lifecycle attributes for Person by adding the following statement to ompp_options.ompp:

options lifecycle_attributes = Person;

Build the model, open the UI, click the book icon, then click Symbol Reference. The browser should display something like:

Next, click the Attributes link under Lists. The browser should look like:

Scroll down if necessary or click the letter 'l' at the top of the Attributes list to see the two attributes lifecycle_counter and lifecycle_events.
Click the link for lifecycle_counter.
The browser should look like:

The built-in attribute lifecycle_counter created by the OpenM++ compiler has type short, which is a C++ integer type. The Symbol Reference shows that lifecycle_counter is currently unused in RiskPaths model code.

Return to the Attributes list by clicking the browser back button, or by clicking the Symbol Reference link, then the link to the Attributes list as before.

Next, click the link for lifecycle_event.
The browser should look like:

The built-in attribute lifecycle_event created by the OpenM++ compiler has type LIFECYCLE_Person, which is a classification created by the OpenM++ compiler to support lifecycle_event and its use in model code. Click the link LIFECYCLE_Person after Type:. The browser should look like:

The classification LIFECYCLE_Person created by the OpenM++ compiler has 8 enumerators, all with the prefix LC_Person_.
This prefix is intended to minimize the chance of a clash with other symbols in model code. The LC_ portion of the prefix is a mnemonic for 'lifecycle'.

The first enumerator LC_Person_enter_simulation notes when a Person entity enters the simulation. The remaining 7 enumerators note the occurrence of the 7 Person events in RiskPaths, in alphabetic order by event name.

This concludes worked example 1. Worked example 2 involves additional modifications to model code. To prepare for it, close the browser window for RiskPaths model documentation, the browser window for the RiskPaths UI, and the oms instance which supported the RiskPaths UI, if necessary.

[back to topic contents]

Lifecycle attribute maintenance

OpenM++ run-time code generated by the OpenM++ compiler maintains lifecycle attributes as follows:

1. When an entity is created via new, lifecycle_counter and lifecycle_event both have the value 0.
2. When the entity enters the simulation by a call to enter_simulation(), life_cycle_event is assigned the first enumerator, e.g. LC_Person_enter_simulation (which is 0, so no change), and lifecycle_counter is incremented (so it changes and has the value 1).
3. When an event in the entity occurs, life_cycle_event is assigned the corresponding enumerator for the event, and lifecycle_counter is incremented.
4. Self-scheduling events, e.g. self_scheduling_int(age) have no effect on life_cycle_event or life_cycle_counter.
5. When the entity exits the simulation by a call to exit_simulation(), the current value of life_cycle_event and life_cycle_counter do not change (although they may have been changed previously in an event which called exit_simulation(), e.g. MortalityEvent.

This means that

1. lifecycle_counter always changes whenever an event occurs in the entity.
2. lifecycle_event contains the enumerator corresponding to that event.
3. When an entity exits the simulation, lifecycle_event contains the most recent event which occurred in the entity.

Note that an event can occur with no change to lifecycle_event if the same event occurs in succession. But even if the same event occurs in succession, lifecycle_counter will change. So, for example, the self-scheduling derived attribute trigger_changes(lifecycle_counter) is guaranteed to note all events in the entity, whereas trigger_changes(lifecycle_event) may not.

Entity tables process increments only after all attribute changes in an event have completed. So, attribute values tabulated using lifecycle_counter or lifecycle_event reflect the values of attributes after all event-related model code has executed.

In models with entity links, an event in entity A can change the attributes of a different entity B. However, the value of lifecycle_counter and lifecycle_event in entity B do not change due to the event in entity A. They retain the values they had at the most recent event which occurred in entity B.

[back to topic contents]

Worked example 2

This example shows how to tabulate event counts by event.

Ensure that lifecycle attributes are enabled by the following statement in model code:

options lifecycle_attributes = Person;

In RiskPaths, copy/paste the following code to code/Tables.mpp:

table snapshot untransformed Person X01_Events //EN All Events
[ trigger_changes(lifecycle_counter) ]
{
    lifecycle_event //EN Event
  * {
        unit //EN N
    } //EN Statistic
};

Build and run the model, selecting the output table X01_Events.

The browser should look like:

The filter of this snapshot table trigger_changes(lifecycle_counter) is instantaneously true when any event occurs, and is false otherwise. The analysis dimension consists of the single expression unit, which sums increments whose values are always 1. The table thus counts events by event type.

[back to topic contents]

Worked example 3

This example shows how to tabulate event counts by event and another characteristic (integer age).

Ensure that lifecycle attributes are enabled by the following statement in model code:

options lifecycle_attributes = Person;

In RiskPaths, copy/paste the following code to code/Tables.mpp:

table snapshot untransformed Person X02_Events //EN Events by age
[ trigger_changes(lifecycle_counter) ]
{
    {
        unit //EN N
    } //EN Statistic
  * lifecycle_event //EN Event
  * self_scheduling_split(age,AGE_FERTILEYEARS) + //EN Age
};

Build and run the model, selecting the output table X02_Events.

The browser should look like:

This table is like example 2 except for an additional classification dimension and a minor permutation of dimension order. The table shows the evolution of event frequencies over the life course. As expected, the margin over age has the same total event counts as example 2.

[back to topic contents]

Worked example 4

This example shows how to tabulate descriptive statistics for an attribute (age) for occurrences of a specific event (.

Ensure that lifecycle attributes are enabled by the following statement in model code:

options lifecycle_attributes = Person;

In RiskPaths, copy/paste the following code to code/Tables.mpp:

table snapshot untransformed Person X03_Events //EN Selected statistics for age at FirstPregEvent
[ trigger_changes(lifecycle_counter) && (lifecycle_event == LC_Person_FirstPregEvent) ]
{
    {
        unit, //EN N
        sum(age) / unit, //EN Mean
        minimum(age), //EN Min
        P5(age),  //EN P5
        P25(age), //EN Q1
        P50(age), //EN Median
        P75(age), //EN Q3
        P95(age), //EN P95
        maximum(age) //EN Max
    } //EN Statistic for age at FirstPregEvent
};

Build and run the model, selecting the output table X03_Events.

The browser should look like:

The filter of this table restricts event snapshots to one specific kind of event.

[back to topic contents]