The Statistics Collector is used to observe events in the model and to collect data about those events. That collected data is written to a table. Once in that table, the data can be viewed, used in a chart, or exported.
The Statistics Collector can be accessed from the Toolbox.
The Statistics Collector can generate a unique ID for any node in the the tree, which means it can generate a unique ID for 3D objects, Process Flow Activities, flowitems, tokens, and TrackedVariables. This is done (often through a pick option) by the static method StatisticsCollector.getID(). This function takes a treenode, and returns a positive whole number, stored in a double. The ID is stored internally, so that multiple calls to getID() with the same treenode will always yeild the same ID number.
There are two sets of IDs. One set is for tokens, flowitems, and all other nodes that are flagged to be destroyed on reset. This set of IDs is incremental, starting at 1. Each call to getID() with a new node will increment the ID. However, when the model is reset, the starting ID is reset to 1.
The second ID set is for all other nodes, which are assumed to be more persistent. The ID for these nodes is generated by creating a hash of the node's path. These IDs are consistent, even between scenario and replication runs in the Experimenter and Optimizer.
Many of the parameters for the Statistics Collector require code. Most of these code fields expose a variable called data. This variable is a special object, with its own properties and labels. Its purpose is to expose data that is associated with each row and column of the table produced by the Statistics Collector. It also exposes data about any event that causes a callback to be evaluated.
For more information about when the data variables is used, see the Callbacks section. For more information about the type and properties of the data variable, see the StatisticsCollector.CollectedData reference.
The Statistics Collector can listen to events. This is usually how the Statistics Collector updates the table. To listen to an event, you will need to specify an object, and a specific event on that object to listen to.
If you listen to a Group, the Statistics Collector will listen to all objects in that group. If you listen to a Process Flow block in an instanced flow, the Statistics Collector will listen to all instances of that flow, event instances that have not been attached yet.
In some cases, you may want to listen to all objects in the model that match some criteria. For example, you might want to listen to some event for all objects with a certain label value, or with a certain class type. In these cases, you can choose to listen by requirement. Instead of specifying a direct object reference to listen to, you can specify a test which will be run against all the objects in the model.
Occasionaly, you may need to listen to an event on an object that cannot be referenced at reset time. For example, you might want to listen to the OnChange of a TrackedVariable label on a flowitem or token. You might also want to listen to the OnEntering or OnExiting of a flowitem or token. To listen to these events, you will need to specify two events. The first event should be an event on something that is present on reset. For example, you might listen to the OnEntry of a queue. Using this event event, you must specify the transient object you wish to listen to. This might be the item that entered the queue, or a label on that item. Finally, you must specify the event to listen to on the transient object. In this way, you can listen to the event of an object that is not present on reset, or even long in to the model run.
Listening by requirement and listening to transient objects are not mutually exclusive. You might, for example, listen to the OnExit of all Source objects, so you can listen to the OnEntering of all flowitems.
The Statistics Collector only executes logic in response to these specific occurences:
When the model is reset, the Statistics Collector clears its table, removing all rows and columns. The collector then goes through the list of Columns (specified on the Data Recording Tab). For each column, the collector adds a column to its table. For each column set, the collector evaluates the Column Set Value callback, and creates one column in the table per returned value. Finally, the collector creates listeners for all events that the collector is listening to (specified on the Event Listening Tab). If any of those events use a requirement, the Object Requirement callback is evaluated for each object in the model. Once the object to listen to has been identified, the collector creates a listener on that object. The collector then determines which columns should be updated if that listener fires, which will evaluate column's Link Requirement callback.
When an event occurs, the collector will assign all enabled event parameters to the data variable, and then evaluate the event's Event Condition callback. If the condition fails, nothing else happens. If it succeeds, the collector proceeds. If the event is the first part of a transient event, the collector evaluates the Transient Object callback. The collector will put listeners on each transient object. If the event is not the first part of a transient event, then the collector will evaluate the Label Value callback for all labels. Then, based on the row mode, the collector will add rows and update columns. When it adds a row, the Row Sorting callbacks (if present) will be evaluated. Then, for all When Row is Added columns, the Column Value callback is evaluated. If the event that occurred is linked to any columns, the Column Value callback will be evaluated for each of the linked columns.
The values in a Statistics Collector's table can be accessed. This happens when a chart that references this collector paints, when a table view for this collector paints, or when the table is accessed through the Table() API, or through a query. When any of those things happen, the collector evaluates the Always columns, using the Column Value callback. for each row. In this way, those columns are "always" up to date.
When the model get to the warmup time, the Statistics Collector will use its On Warmup property to determine what to do. That property can be set to one of four options:
As the Statistics Collector runs its internal logic, it evaluates many callbacks. These are properties that can have a code value. The following table shows a list of all the callbacks used during the Statistics Collector's logic, along with a description, and what can be returned from those callbacks:
|Column Set Value||Called during OnReset. Determines how many columns the current Column Set will produce.||Returns an array of column names. The Statistics Collector
will create a column for each name. You can optionally
replace the name with a two-element array, where the
first value is the name, and the second is some value
you wish to associate with the column, later available
|Object Requirement||Called during OnReset. If you are listening to an event by requirement, this field is called once for every object in the model.||If the object should not be listened to, you can return a 0. If it should be listened to, you can return a 1. If you want to listen to a related node, such as a Tracked Variable label on the object, you can return that node, or an array of nodes, as well.|
|Link Requirement||Called when a listener is created, during on reset, or in response to the event that discovers a transient object. For each column, if it is linked to events by code, then this requirement is evaluated for the current column.||If the current event should update this column, return a 1. Otherwise, return a 0.|
|Event Condition||Called when an event that the collector is listening to occurs. If the condition passes, then the Statistics Collector proceeds with its logic, either to update the table, or to add listeners to a transient object. If it fails, the Statistics Collector will not execute any additional logic in response to the event.||Return a 1 to indicate that the condition passes, and a 0 otherwise.|
|Transient Object||Called when an event that the collector is listening to occurs, and that event is used to discover a transient object. This callback is used to determine what the transient object is, given the event parameters.||Return the object that has the transient event, or an array of objects.|
|Event Label||Called when an event occurs, and its condition passes. The collector will assign whatever value is returned to a label on the data variable. Event labels are evaluated in order, so that later Event Label callbacks can reference previous label values.||Return the value you want the data variable to have for the current label.|
|Row Sorting||Called when a new row is added to the table, and row sorting is being used. Each sort by value is used as a score for the row, and that score is used to sort the rows when new rows are added.||Return a number or text. If one row returns a number for this field, all rows should return a number. Likewise for text.|
|Column Value||Called when a cell in the table needs to be updated. Whatever value is returned from this callback will be placed in the table in the current row and column.||Return a value that matches the column type, and can be formatted according to the column format.|
|Initial Column Value||For columns that are updated by an event, this callback specifies what value to use when the row is added, but before any updating events occur. This callback can optionally be used at the warmup time to define a reset value for the column.||Return a value that matches the column type, and can be formatted according to the column format.|
The data variable is available within most callbacks. The following table shows which properties on the data variable are available during each callback:
In general, as many properties as possible are available
during each callback. For example, during row sorting,
are available, but
data.rowNumber is not, because
the sort has not finished.
The dynamic properties that are available will depend on when the callback is executed. At a minimum, the dynamic properties will include all enabled event parameters. Additional labels will only be available after the label callbacks have been evaluated. When the first part of a transient event occurs (the discovering event), those event paramaters are saved, and will be available as dynamic properties during the transient event.
When the Statistics Collector is using the Unique Values row mode, it keeps a list of row values. When an event occurs, the event will reveal a row value. If the collector does not have a row for that value, then it will add add a row for the value. When another event occurs that involves the same value, the collector will update the row for that value. In this way, the collector tracks each row value.
In some situations, it may be useful for the collector to stop tracking a row value. For any event you listen to, there is an option to stop tracking the row value after the event has updated the table. At this point, the row value becomes untracked. Its associated row becomes inactive, meaning that it cannot be updated any longer either by events happening, or by being observed (in the case of Always columns). If the row value is later encountered through an event, then a new row is added for that value, as if it had never been encountered before.
Once a row becomes inactive, you can choose whether or not that row can be reused by a new row value. When a new row is needed, the inactive row can be overwritten, instead of adding a new row. If you are using two Statistics Collectors together, where the second listens to the events of the first, you might consider using this option, to keep the first table smaller.
One of the warmup options for the Statistics Collectors will remove untracked rows. You can use this option to control which rows are removed at warmup time.
For information on events, see the Event Listening page.
The Statistics Collector has the following events:
This event fires when a new row is added to the Statistics Collector. This event does not fire if the Row Mode is set to Enumerate. If any columns have an update mode set to When Row is Added, those values will have been set before this event fires.
It has the following parameters:
|Row Number||int||The row number of the new row|
|Row Value||Variant||The value associated with the new row|
This event fires when one of the events that the Statistics Collector listens to updates one or more columns on a given row.
It has the following parameters:
|Row Number||int||The row number of the new row|
|Row Value||Variant||The value associated with the new row|
|Columns Updated||Array||An array containing one value per column. If the nth column was updated, then the nth value of the array will be 1. Otherwise, the value will be zero.|
|Previous Values||Array||An array containing one value per column. If the nth column was updated, then the nth value of the array will contain the value that was in the table before the update. Otherwise, the value is undefined, and should not be used.|
The Statistics Collector has three tabs with various properties. The properties in these tabs will be explained in more detail in next sections.
This tab allows you to specify a list of events that will add or update data in the StatisticsCollector's table. This tab also allows you to collect additional data about each event so that more data is available for recording.
The Event Listening tab has the following properties:
Lists the objects or timer events that the Statistics Collector will gather data from. The Statistics Collector can listen to:
The following table explains the buttons on the event list:
|Opens a menu to add a new event to the list. The Statistics Collector will gather data from this event during a simulation run.|
|Samples an object in the 3D model, a process flow, or toolbox to add it to the event list.|
|Duplicates the selected event from the event list.|
|Removes the selected event from the event list.|
|Reorders the selected event from the event list.|
You can use these properties to edit the details for the event that is currently selected in the Event List. The following properties only appear when a object event is selected in the Event List:
You can use these properties to edit the details for the event that is currently selected in the Event List. The following properties only appear when a timer event is selected in the Event List:
|Add a new event time|
|Remove the selected event time|
|Reorder the selected event time|
You can use these properties to edit the details for the event that is currently selected in the Event List. The following properties appear when a tracked variable event is selected in the Event List, or when listening to a tracked variable value on an object:
You can use these properties to define the event that is used to discover a transient object. The following properties appear when a transient event is selected in the Event List:
The Transient Event popup has the following properties:
You can use event data labels to collect additional data connected with the selected event. For example, if the event involves a flow item, you can assign a label value on the flow item to a label on the event object.
If all events in the collector will yield the same label value, you can add an event data label for all events, rather than for each event individually.
The Event Data Labels group has the following properties:
|Add a new event label, either for the current event, or for all events.|
|Remove the selected event label. Removing a shared label removes it for all events.|
|Reorders the labels in the list.|
The Data Recording tab allows you to specify how the data that has been collected (on the data object's labels) will be used in the data table. It allows you to specify how rows will be created, and how values in those rows will be added or updated.
The Data Recording tab has the following properties:
The Rows group has the following properties:
|Row Mode||Explanation||When to Use It|
|Add Per Event||Adds a row to the data table every time one of the events the Statistics Collector is listening for occurs. The data table will grow longer every time an event occurs.||This row mode might be best for timer events. It will create a row every
time the event timer fires and capture the data from the relevant objects at
that moment during the simulation run.
You could also use this row mode if you want to simply see a log of all the events that currently being recorded by the Statistics Collector.
|Unique Row Values||Adds a row for unique values. If the value is unique, it will create a new row. If the value is not unique, the data table will update or fill in values for certain columns on that row. When you choose this row mode, you will select the value that will be checked for uniqueness, such as a data event label.||This row mode is ideal for tracking a flow item or token as it moves through
a model or process flow. As the flow item or token causes events to fire, it can
update the columns in the row with new information as needed.
This row mode is also ideal for tracking unique values on a label. For example, it could create rows for each SKU number on an item's label, or it could create rows for each product type, etc.
|Enumerate Rows||Adds a row for each object that is specified in the Enumerated Rows list. When this row mode is selected, you can fill in the Enumerated Rows list with the objects that will make up the rows of the table. Adding a group will create one row for each group member.||This row mode is ideal when you have a fixed number of objects for which you want to collect information. For example, this could be ideal if you want to track object statistics like the object's total throughput.|
When a row is created, the expressions in this property are evaluated, and the results are cached. The cached values are compared to the other cached values for each row, using the sort direction (Ascending or Descending). The row is then placed in the correct position.
|Add an object to the enumerated list|
|Sample an object (or group) to add to the enumerated list|
|Remove the selected object from the list|
|Reorder the objects in the list. The order in the list defines the order in the table.|
This group of properties allows you to add columns to the Statistics Collector's data table. For each column these properties specify the value, update timing, storage type, and display format.
The Columns group has the following properties:
|Add a new column.|
|Duplicated the selected column from the list.|
|Remove the selected column from the list.|
|Reorder the columns in the list; the order of the columns in this list is the order of the columns in the data table.|
Click on this button to open the Event/Column Dependencies popup. This popup shows a list of the events in the Statistics Collector. When you select an event, you can choose which columns the event will update. If the Link event mode is set to By direct links, you can designate which columns will update for the current event by checking the box for that columns. If the Link event mode is set to By column requirement, then you can specify the code for the Link Requirement callback.
The General tab has the following properties:
This property only applies if one or more of the events for this Statistics Collector involve Process Flow Activities in Task Executor or Fixed Resource process flows. By default, this option specifies that the Statistics Collector should listen to all instances of that activity. In order to listen to fewer instances, you can use the sampler to set this value to a single object, or to a Group of objects. The Statistics Collector will only listen to the instance objects specified by this property. The remove button will reset this property to the default of All Instances.
This property applies to columns that use the Object format. The Object format displays a path to each object, and this property controls the maximum number of names that can appear in that path. If this property is 0, then the full path will be shown. If it is 1, then only the name of the object will be shown. If this property is 2, then the parent's name and the object's name will be shown as a partial path. As the value increases, the path will include nodes higher in the tree.
This property specifies how the Statistics Collector responds to the model warmup time, if the model has a warmup time. For more information, see the On Warmup paragraph.
If this box is checked, then this Statistics Collector will store its table data on the hard drive, in an internal file. Memory (RAM) use for the data table will be limited to 5 MB.
Click this button to open a view of the data table for this Statistics Collector.
You can use this button to save a CSV file of this Statistics Collector's data table.
This list shows all the dashboard charts that are drawing data from this Statistics Collector. If no charts require this collector, the list will be empty.
Click this button to open the Properties window of the selected chart in the Connected Dashboard Charts list.