The Statistics Collector

Overview and Key Concepts

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.

Statistics Collector IDs

The Statistics Collector can generate a unique ID for any node in 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.

The data Variable

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.

Listening

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.

General Behavior

The Statistics Collector only executes logic in response to these specific occurences:

• The model is reset
• An event that the collector is listening to happens
• The values Statistics Collector's table are accessed
• The model gets to the warmup time (if the model uses a warmup time)

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:

• Remove all rows - All rows will be removed from the table.
• Reset to initial values - Columns that specify an initial value will be reset to that value. No rows are removed.
• Remove untracked rows - Rows that are not currently tracked are removed, while the rest are kept. The values in the remaining rows are unchanged.
• Remove untracked rows and reset to initial values - Rows that are not currently tracked are removed, while the rest are kept. The values in the remaining rows are set to the initial value, if one is specified.
• Do nothing - Nothing happens to any rows or columns.

Callbacks

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:

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, data.rowValue and data.rowValueIndex 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.

Row Tracking

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.

Events

For information on events, see the Event Listening page.

The Statistics Collector has the following events:

On Row Added

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:

On Row Updated

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:

Properties

The Statistics Collector has three tabs with various properties. The properties in these tabs will be explained in more detail in next sections.

The Event Listening Tab

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:

Event List

Lists the objects or timer events that the Statistics Collector will gather data from. The Statistics Collector can listen to:

• 3D objects
• Process flow activities and shared assets
• Tracked variables
• Groups
• Timer events

The following table explains the buttons on the event list:

Icon	Description
	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.

Object Event Details

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:

• Name - Use this box to edit the name of the event.
• Object - Displays the name and path of the object being listened to.
• Requirement - If the object should be selected by requirement, the Object property will be replaced with the Requirement property, which specifies the Object Requirement callback.
• Event - Lists the event on the object that is currently being listened to. Click this menu to select a different event.
• Parameters - This table shows the parameters that are available at the time this event fires. If a parameter is enabled, then it will be assigned to the specified label on the data object.
• Condition - Defines the Event condition callback, which determines whether or not the event that has happened should update the table.

Timer Event Details

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:

• Name - Use this box to edit the name of the event.
• First Time - Use this box to specify an offset time of the timer event. The event cycle begins at this time.
• Repeating - Use this checkbox to specify whether the event cycle will repeat.
• Repeat Time - Use this box to specify the duration of the repeat cycle. This value should greater than or equal to the largest time in the Event Times list.
• Event Times - Use this table to specify the sequence of events that will occur every repeat cycle. The default case is to have a single event at time zero, which means zero model units from the beginning of the event cycle.

Icon	Description
	Add a new event time
	Remove the selected event time
	Reorder the selected event time

Tracked Variable Event Details

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:

• Name - Use this box to edit the name of the event.
• Object - Displays the name and path of the tracked variable or the object being listened to.
• Event - Lists the event on the tracked variable or object that is currently being listened to. Click this menu to select a different event.
• Change Rule - Select the rule condition to apply when the event fires.
• Change Value - Use this box to define the value that should be used in seeing whether the selected rule has been satisified. If the rule is satisifed, the statistics collector process continues as normal. If it does not, then execution is halted, and the event will not update the table.
• Parameters - This table shows the parameters that are available at the time this event fires. If a parameter is enabled, then it will be assigned to the specified label on the data object.

Transient Event Details

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:

• Name - Use this box to edit the name of the event.
• Object - Displays the name and path of the tracked variable or the object being listened to.
• Requirement - If the object should be selected by requirement, the Object property will be replaced with the Requirement property, which specifies the Object Requirement callback.
• Event - Lists the event on the object that the collector will listen to. Click this menu to select a different event.
• Parameters - This table shows the parameters that are available at the time this event fires. If a parameter is enabled, then it will be assigned to the specified label on the data object.
• Condition - Defines the Event Condition callback, which determines whether or not the event that has happened should attach a listener to the transient object.
• Transient object - Defines the Transient Object callback, which should the transient object.
• Edit transient object event - Opens a popup that allows you to set properties of the transient event.

Transient Event Popup

The Transient Event popup has the following properties:

• Event - Select an event on a transient object. You will need to use the sampler to sample an object like the transient object. For example, if you want to listen to a token, you will need to sample a token. However, you can sample any object of the same type. The purpose is just to fill out the list of events and parameters for each event.
• Parameters - Specifies the parameters of the chosen event, whether those parameters will be assigned to the data variable, and what the dynamic property name will be on the data variable.
• Condition - Defines the Event Condition callback, which determines whether the event that has happened will update the table.

Event Data Labels

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:

• Label List - Lists the labels that have been created for this event.

Icon	Description
	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.

• Name - Use this box to change the name of the label.
• Value - Use this box to set the value of the label. This defines the Label Value callback. This value can be based on any of the enabled event parameters or previous labels.

The Data Recording Tab

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:

Rows

The Rows group has the following properties:

• Row Creation Mode

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.

• Row Value - Use this dropdown to select the value associated with each row in the table. If this value is an array, multiple rows could be updated or created (for each element in the array).
• Row Sorting - Use this property to specify how row should be ordered when they are created. This property is only available if the Row Mode is set to Unique Row Values:

  

  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.
• Edit row tracking options... - Opens a popup that allows you to specify which events stop tracking an item. If you are not sorting rows, then the popup will also allow you to choose whether or not to reuse untracked rows.
• Enumerated Rows - Use this property to specify a list of objects. Each object listed will get one row in the data table. If the object is a group then each object in the group will get its own row in the data table. This property is only available if the Row Mode is set to Enumerate Rows.

Icon	Description
	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.

• Row List - Displays the current list of objects in the Enumerated Rows list.

Columns

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:

• Column List - The column list shows the complete list of columns that the data table will include.

Icon	Description
	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.

• Name - Use this box to set the name of the column. This name appears in table views, charts, and exported files. The name should be unique among the other column names in the Statistics Collector. The name can have spaces but that is not recommended if you want to query the table using SQL (using a Calculated Table for example).
• Update - Use this box to set when the value of a column should update. For the Add Per Event row creation mode, the row is created and its values are calculated in one step, so this option does not apply. For the Unique Row Values and Enumerate Rows creation mode, it is possible (and likely) that a given row will be updated after it has been created, often many times. The three options for this property are as follows:
  1. By Event Dependency - The column will only be evaluated when certain events occur. Those events are specified in the Event/Column Dependency table.
  2. When Row is Added - The column will only be evaluated once per row, when the row is added.
  3. Always - This column will updated when it is required. This includes if it is being viewed in a table, or if a chart is viewing this table. It also includes when a query is run or when the table is accessed in FlexScript.
• Value - Use this box to specify what value should be placed in the data table. This value must either be a number or a string (text).
• Initial Value - Use this property what the value should initially be placed in the data table, before any updating events have occurred.
• Set Value - Defines the Column Set Value callback for column sets. The value returned from this field should be an array of names, or an array of two-element arrays containing a name and a value. The collector will create one column with the given name in the table.
• Storage Type - Use this box to specify the storage type of the value. If the value is text, this option should be set to String. For numbers, the Double option is best. The other two options (Float and Integer) require less memory, but have some restrictions:
  • Integer - Can only be used if the data can be represented by whole numbers between -2147483646 and 2147483647. For example, maybe the column shows Item Type or Part Type. Additionaly, if the model will not create more than two billion tokens or flowitems, then you can use this option for the IDs of tokens or flowitems. You should not use this option for IDs of persistent objects (for example, 3D objects).
  • Float - Should only be used to represented floating point numbers where less than 7 digits of precision is required. An example might be a weight label on a flowitem, or a staytime value. You should not use this option for FlexSim Time.
• Index Type - Use this box to specify the index type of the value. If you specify an option other than None, then an index will be added to the column, or to all columns of the Column Set. An index can greatly improve query performance. For more information, see the SQL Queries topic.
• Display Format - Use this property to specify how to display the data in this column. There are four options:
  • Raw - This option tells the table view and charts to show the raw data. This is the only option that accomodates string values.
  • Object - This option tells the table view and charts that the column contains persistent IDs (for example, 3D objects). This column will display the path for the object, rather than the ID number.
  • Date / Time - This option tells the table view and charts that the column contains a FlexSim Time. This column will display the date and time according to the Windows User preferences.
  • Percent - This option tells the table view and charts to display this value as a percent. The value is multiplied by 100, and a percent sign is added.

Edit Event/Column Dependencies...

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

The General tab has the following properties:

Process Flow Instance

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.

Object Format Depth

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.

On Warmup

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.

Store data on hard drive

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.

View Table

Click this button to open a view of the data table for this Statistics Collector.

Export Table

You can use this button to save a CSV file of this Statistics Collector's data table.

Connected Dashboard Charts

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.

Properties

Click this button to open the Properties window of the selected chart in the Connected Dashboard Charts list.