39.3 Tracking Events by Patient with Trackers

Trackers offer a simple way for any number of events to be recorded while simulating individual trials through a microsimulation model (either a Markov or a Discrete Event microsimulation).

Trackers are created for each trial in the model by setting the tracker equal to the initial value used for all patients. The tracker can then be modified in any way at any node, changing the value of the tracker only for that individual.

For example, a tracker could do any of these things, and more.

  • Record whether an event has ever happened

  • Record how many times an event has happened

  • Record when an event last happened

Trackers act like memory for a trial or individual patient allowing details about prior events to be easily recalled, updated and reported.

There are some important differences between Trackers and Variables as summarized in the table below.

Item Trackers Variables
Value scope

Applies to an individual trial

Applies to the entire cohort
Analysis type

Requires microsimulation

No restrictions

When are definitions/modifications executed?

Immediately at the node where the tracker modification is found

Only when the variable is referenced in a required calculation (i.e., payoff, reward, probability, etc.)

Initial value

Required at the starting point for each trial

Does not exist

39.3.1  Creating, Defining and Using Trackers

Trackers are created and defined in a similar way the regular variables described in the variables section (Variables: Named Model Values); however, you create and edit trackers in the Trackers and Tracker Modifications Views rather than their equivalent Variable views.

Trackers also differ from variables in the way they are evaluated during analyses. This will be discussed further within this section but it is summarized in the table above.

One quick way to create and define a tracker is by right-clicking on a node that requires a tracker modification. This forces you to select the appropriate node where the tracker should be modified.

Open the Health Care tutorial example model, MicrosimulationCancerModel - Distributions.trex. This has a tracker which counts the number of adverse events which occur: the tracker is named t_AE.

To create and define a tracker:

  • Right-click on a node where you want to create the tracker. In this model its the Metastases > Survive Background Mortality > Adverse Event node.

  • Choose Define Tracker > New Tracker from the context menu.

  • In the Add/Change Tracker dialog (first image below), enter a name and other properties of the tracker and click OK to save it. In this model, the tracker name is t_AE. The properties show the default intial value equals 0, which applies appropriately in this case.

  • In the Define Tracker dialog (second image below), enter the tracker modification (i.e. how you want it to be calculated at this node) and click OK to save it. In this model the tracker modification would be t_AE + 1 telling the tracker to "count" each time it gets to this node.

Add/change tracker dialogue (as in the figure above):

The initial value is the value of the tracker at the beginning of each trial. Once a trial has finished, the next trial will start the model with its tracker set to the initial value. In most cases, the default value of 0 is appropriate. An example of an exception case is: If you want to record the _stage value when a certain transition occurs. If the initial value is zero, there will be no way to distinguish between the case where the transition occurred at _stage 0 and the case where the transition never occurred. An initial value of -1 would distinguish between those cases.

The evaluation priority value determines the order in which to evaluate trackers at a node. This only impacts analysis results if you have a tracker that is updated and used in another tracker modification at the same node. In such a case, you might want to ensure that the updated tracker value is set before being used in the other tracker modification. The priority can be set for each tracker; however, the priority is only used if the appropriate Tree Preferences option is set in the Other Calc Settings category.

When you select OK in the Add/change tracker dialogue, the Tracker modifications dialogue will open.

Tracker modification dialogue:

To change (or delete) an existing tracker modification, simply right-click on the desired event node and choose the variable from the Define Variable list. Or, use the Tracker Modifcation view described in the next few sections.

If you are modifying a tracker that already exists, you will only see the second dialog.

Be aware: Modifications of a tracker at the root node of the tree will be ignored. However, you can make the root node of the tree a label node and place the tracker modifications to the right of that node. This achieves the same outcome, without having the tracker modified at the root node.

How the Tracker is displayed {T} Tracker_Name:

When TreeAge Pro displays a tracker modification in the tree view or Define Variable window, it appears with the prefix “{T}”. You should not type the {T} prefix when referring to the tracker in formulas. This is just a display property to distinguish that "its a tracker".

39.3.2  Trackers in simulation output

When we run a microsimulation, the values of the trackers at the end of the simulation for each trial will be captured in the output. This makes trackers a simple way for any number of events to be recorded while simulating individuals' “runs” through a microsimulation model.

In the Health Care tutorial example model, MicrosimulationCancerModel - Distributions.trex, the tracker t_AE counts the number of adverse events which occur. In addition, the tracker t_firstAE_stage records when the first adverse event happens. To see the values of the trackers in the microsimulation output, we need to run the model.

To run a microsimulation at Markov node Tx 1:

  • Select the Markov node, labeled Tx 1. (We are running microsimulation just for one strategy).

  • Choose Analysis > Monte Carlo Simulation > Trials (Microsimulation) from the menu. OR

  • Select the single dice from the tool bar.

  • Enter the number of trials, 10,000. Select Begin.

The microsimulation output will show the Expected Values for the active payoffs (Costs and Effectiveness) for Tx 1 (the top strategy) and all the statistics associated with those values aggregated for the payoffs over 10,000 trials.

The report we are interested in is the All Data report (which is explained in more details in the section about Running Microsimulation and Interpreting the Results). For our purposes, we just need to understand that the final values of the payoffs (active and non-active), trackers and distributions are given in the All Data report per trial.

To the RHS of the main Monte Carlo Simulation Dashboard, expand Data Reports > All Data. The All Data Report as shown in the figure below.

The report shows the payoffs (active and inactive) accumulated for each trial, where the iteration column shows the trial number. The final value of the trackers is also presented so we can see the number of Adverse Events in the column t_AE and the time of the first Adverse Event in the column t_firstAE_stage. Those trials who did not have an Adverse Event still show a value in the t_firstAE_stage column of -1.0 (the initial value).

To see when (i.e at what time), during the simulation, the tracker values have been updated the model can use Patient Tracking which is explained in more detail in the section Patient Tracking Reporting for Microsimulation.

Average tracker values can also optionally be displayed for each strategy. This option is selected in the Trackers View described later in this section.

39.3.3  Referencing trackers in calculations

Once the model includes trackers, we can report and investigate their values. In addition, we can use the trackers in calculations. Trackers have many applications as inputs to formulas calculating transition probabilities, rewards, individual patient-level distributions, termination conditions, or any other numerical expression. In other words, the trackers are not limited to recording events; they can also be used to affect future transitions, events, rewards, etc.

In the Health Care tutorial example model, MicrosimulationCancerModel - Distributions.trex, the tracker t_AE tracks the number of adverse events and impacts the probability of death, pAE_Death, depending on the number of adverse events.

Examine the following:

  • Table tDeathAE: The index column in the table is the number of adverse events and the value column is the probability of death from an adverse event.

  • Variable pAE_Death: This variable references the table using the index = t_AE. We can see that as the number of adverse events increase, the probability increases. The definition of the variable is: pAE_Death = tDeathAE[ t_AE ]

Once model calculations require trackers in order to be calculated correctly, the model should be analyzed only with microsimulation. Expected value analyses (i.e., roll back, n-way sensitivity analysis, Markov cohort analysis) will ignore the trackers and will probably yield incorrect results. In this model, trackers only impact probabilities, but they could impact cost and utility as well. (Once your model includes trackers, any attempt to run Expected Value calculations will provide you with a warning).

39.3.4  Trackers Views and Properties

This section describes the views and dialogs related to creating and managing trackers in your model.

Trackers View

The Trackers View is used to manage tracker properties. Tracker properties apply to the entire tree (as opposed to the Tracker Modifications View which is node specific). The Trackers View is a tree-level view rather than a node-level view. This view functions in a manner similar to the Variables View, except it is used for trackers.

To open the Trackers View, choose Views > Trackers from the toolbar.

Below is an image of the Trackers View in the Health Care tutorial example model, MicrosimulationCancerModel - Distributions.trex.

The main grid contains a list of the tree's trackers along with a few of the key tracker properties. The properties can be edited within the grid. If you change the tracker name, all references to that tracker within the tree will be modified as well.

Note the option to "Show in Rankings". If selected, the average tracker value for each strategy will be included in Rankings reports.

The Trackers View toolbar provides additional functions.

The functions associated with the icons are presented below from left to right/top to bottom.

  1. Edit tracker

  2. Add new tracker

  3. Add multiple new trackers

  4. Delete selected tracker

  5. Convert tracker to variable

  6. Copy tracker

  7. Paste tracker

  8. Edit in Excel

  9. Generate Trackers Report

  10. Highlight

  11. Find reference in tree

  12. Filter Text/Clear

  13. Show Categories Tree/Group Variables by Category

These functions are described briefly here. Since the functions are nearly identical to the functions for editing regular variables, please refer to the Variables: Named Model Values section for more details.

Edit tracker: Edit the properties of an existing tracker via the Add/Change Tracker Dialog.

Add new tracker: Create a new tracker and enter its properties via the Add/Change Tracker Dialog.

Add new trackers: Specify the number of new trackers and then enter their properties via the Add/Change Tracker Dialog.

Delete selected tracker: Delete the tracker(s) selected in the view's grid.

Convert tracker to variable: Convert the selected tracker to a regular variable.

Copy tracker: Select the row with the tracker(s) you wish to copy. Click the copy icon to copy the tracker(s) into the clipboard. See the Variables View for details about copying/pasting. Note that this only copies the tracker entity with its initial value, but no tracker modifications in the model.

Paste tracker: Copy tracker(s) (as above from another model) and click the paste icon to paste the tracker into the active model. See the Variables View for details about copying/pasting.

Edit in Excel: Use the Excel Module to edit tracker properties in Excel.

Generate trackers report: Generate a report on trackers in the model.

Highlight: Highlight the tracker within the model in the Tree Diagram Editor.

Find reference in tree: Select a tracker and search within the model for that tracker.

Filter text/clear: Filter the list of trackers to show only tracker names that match the Filter Text.

Group trackers by categories: Group the trackers by category in the view's grid.

Tracker Modifications View

The Tracker Modifications View is used to manage tracker modifications at different nodes within the tree. Tracker modifications are created at specific nodes, meaning the Tracker Modifications View is a node-level view. The contents of the view reflect the context of the selected node. This view functions in a manner similar to the Variables View, except it is used for trackers.

To open the Tracker Modifications View, choose Views > Tracker Modifications from the toolbar.

Below is an image of the Tracker Modifications View from the Health Care tutorial example model, MicrosimulationCancerModel - Distributions.trex, with the Adverse Event node selected.

There are two tracker modifications presented in the Tracker Modifications view.

The functions within this view work almost identically to the Variables Definitions View. Please refer to that section for more details.

Note tracker modifications cannot be inherited; that functionality from the Variable Definitions View is not included in the Tracker Modifications View.

To copy/paste Tracker definitions: you can select one or more tracker modifications at a node, right-click and choose Control+X to cut or Control+C to copy the tracker modification into the clipboard. Then select another node and right click on "Defined" in the view then choose Control+V to paste the tracker modification at the currently selected node. For Mac, use Command+X, Command+C, and Command+V for the same actions.

Add/Edit Tracker Modification Dialog

The Add/Edit Tracker Modification Dialog is used to edit tracker modifications at a specific node. The dialog is described earlier in this Tracker Section under the heading Creating, Defining and Using Trackers.

39.3.5  Trackers: Assigning Patient Characteristics via Bootstrapping

In the previous section, we considered an example of Bootstrapping. Bootstrapping is where characteristics of the heterogeneous population can be populated using real-world patient data. This has an advantage over distributions because the full set of patient characteristics is tied to a real person, so the appropriate data correlations are maintained.

To recap, Bootstrapping is implemented in TreeAge Pro with the following steps:

  1. Load the real-world data into a table with each row representing a real patient and each column representing a different patient characteristic. The index of the table should be 1, 2, 3… N, where N is the last row in the table.

  2. Create a uniform distribution that returns only integers between 1 and N.

  3. Create tracker moodifications (or variable definitions as in the previous section) which assign each characteristic by pulling data from the table.

    1. The table row would come from the distribution defined above (an integer between 1 and N).

    2. The table column is set for each patient characteristic.

Open the Healthcare tutorial example, MicrosimulationCancerModel - Bootstrap With Trackers.trex, and examine the distribution distProfile. The distribution generates a new profile number from a Uniform Distribution.

In the table, each column is assigned a different patient characteristic, in this case tumor type (Col 1) and start age (Col 2). The profile number is used to reference a row in the table tProfileData.

The model uses the entries of the table to populate trackers in the model for a given trial. Consider the tracker definitions which have to occur at the start of each Strategy (Tx 1 and Tx2).

  • t_StartAge = tProfileData[distProfile;2]

  • t_TumorType = tProfileData[distProfile;1]

The Tracker modifications must occur at each Strategy node. This is because Tracker modifications cannot happen at the root node (unlike the same example with Variables) because the trackers are set to their initial value at the root node.

The benefit of using Trackers for the patient characteristics is that Trackers are reported in the Microsimulation output.

The All Data report shows (if you scroll to the far right), which value was selected from the uniform distribution distProfile. The first trial had distProfile = 2, and therefore corresponding values of t_tumorType = 2 and t_startAge = 45. This allows data verification of the input values when the anlysis is over via the output values.

With the characteristics included in the output data consistently across strategies, you can use filtering to examine subgroups within the overall hetergeneous cohort.

39.3.6  Tracker Modification Location and Timing

  • A node’s tracker modifications occur after that node is selected in a random walk (i.e., after any logic or probabilities for the branch and its siblings have been evaluated), and after rewards (state or transition) are accumulated at that node. If you need the tracker updated first to be used in calculations of cost, utility, etc., we recommend updating the tracker at a label node, then performing the subsequent calculations at the next node to the right.

  • Modifications at a Markov node will be evaluated once at the start of _stage 0, when a trial starts the Markov process.

  • Modifications at an absorbing state are only evaluated for the first cycle that the trial exists in the absorbing state.

  • Modifications at the root node of the tree will be ignored. However, you can make the root node of the tree a label node and place the tracker modifications to the right of that node. This achieves the same outcome, without having the tracker modified at the root node.

39.3.7  Tracker Modifications that Reference Other Trackers

If you have more than one tracker modification at a particular node, the modifications will be applied in reverse alphabetical order. To avoid errors and confusion, if {T} TrackerB is dependent upon the value of {T} TrackerA, it is recommended that they be defined at successive nodes. Simply move the dependent tracker modification to a node to the right.

This is accomplished by inserting a single branch to the right of the existing event, and moving the dependent tracker modification to that node. The node between the dependent modifications can be changed to a label node, as shown below.

39.3.8  Trackers and Expected Value Calculations

While expected value (EV) analysis is not recommended for trees in which trackers are referenced in probability or reward calculations, this type of analysis is not disabled. Since tracker modifications are only meaningful within simulation trials, TreeAge Pro generally ignores them during EV calculations, including Monte Carlo PSA. Outside of simulation trials, the values of trackers will be equal to their initialization value.

One exception to this rule is when an expected value analysis makes a call to the Node() function which in turn runs a set of microsimulation trials at another location in the tree. See the information on the Node() function in the Tools and Functions for Complex Trees and Advanced Markov Model topics section.

A more efficient replacement for recursive variable definitions is another possible application of trackers in expected value calculations of regular trees. In Tree Preferences, under Other Calc Settings, there is a preference that must be turned on for tracker modifications to work like recursive variable definitions during regular, non-microsimulation analyses.

In light of the potential for error, it is advisable to limit analysis of trees that require trackers to microsimulation only. For the purposes of EV analyses like roll back or one-way sensitivity analysis, it may be desirable to either use the advanced Node() linking function or to develop a modified version of the model in which calculations do not depend on trackers.