question

The column set is designed for cases where you need many similar columns, and it would be tedious to make 10 or 20 (or more) columns that are basically the same. Also, it can be used when the number of columns may change based on your model settings.

Here is a model with two examples:

columnsetdemo.fsm

In the first example, the stats collector makes a table that makes a new row every 10 seconds. On each row, it records the time of the event, as well as the content of each queue. Here is what the table looks like, after the model has run for a while:

You can do this without column sets. Column sets are nice, though, because now you can change the model, and the Statistics Collector will figure out how to change the table. It means you only have to configure the collector once, even if you change your model a bunch. So let's change the model. Delete Queue2, and change Queue3's name to QueueC. Now reset and run, and observe the new table:

So a column set is a way to configure the Statistics Collector during OnReset, to have an adjustable number of columns.

So how do they work? When you define a column set, you need to define the Set Values. This is a function that you define. It should return an array of values. Each value in that array can be a name/value pair (an array with 2 members). For each pair, the collector will make a column with the given name and value. Here is the code for the above table:

/**Make one column per queue in the group*/
StatisticsCollector collector = ownerobject(c);
Array result;
Array queues = Group("Queues").toFlatArray();
for (int i = 1; i <= queues.length; i++) {
	Object queue = queues[i];
	result.push([queue.name, queue]);
}
return result;

Notice that this code iterates through all the queues in the defined group, pushing the queue's name as the name of the column, and the queue as the value for the column.

But what is the point of having a value connected with each column? The answer is that you can use that value to set the value of each row in that column. In the example above, we got the current content of each Queue. I did this by using the Object Statistic popup, and configuring it like this:

Notice that the Object field is set to data.colValue. When the Statistics Collector evaluates the value for each cell, and that cell's column is part of a column set, then the collector will look up the value associated with that column, and make it available as data.colValue. In this way, each column's value can depend on some arbitrary value tied to that column.

StatisticsCollector1 bases the number of columns on the number of objects in a group. StatisticsCollector2, on the other hand, bases the number of columns on the number of rows in a global table. The code for the column set is shown here:

/**Get one state per row in the table*/
StatisticsCollector collector = ownerobject(c);
Array result;
Table states = Table("StateTable");
for (int i = 1; i <= states.numRows; i++) {
	string stateName = states[i]["State"];
	result.push(stateName);
}
return result;

Notice that instead making an array of name/value pairs, this code just makes an array of names. This will also work; it just means that data.colValue won't give back a value. In this second collector, however, the value of the cell doesn't depend on data.colValue. Instead, it uses data.colValueIndex, which is the index of the current column within its column set.

Hopefully, these two cases show how useful column sets can be. The plan is to use these features for the People module, so watch for examples in future releases of the People module.