User Guide: C++ : Tables

11. Tables

A table is used to gather statistics on a sequence of discrete values such as interarrival times, service times, or response times. Data values are "recorded" in a table to include them in the statistics. A table does not actually store the recorded values; it simply updates the statistics each time a value is included. (see section 11.6, "Moving Windows", for the only exception to this rule.)

The statistics maintained by a table include the minimum, maximum, range, mean, variance, standard deviation, and coefficient of variation. Optional features for a table allow the creation of a histogram, the calculation of confidence intervals, and the computation of statistics for values in a moving window.

First-time users of tables should focus on the following three sections, which explain how to set up tables, record values, and produce reports. Subsequent sections describe the more advanced features of tables.

11.1. Declaring and Initializing a Table

A pointer to a dynamic table is declared in a CSIM program as follows:

Dynamic Example: table *td;

Before a table can be used, it must be initialized by invoking the table constructor:

Prototype: table::table(char* name);
Static Example: table ts("response times");
Dynamic Example: td = new table("response times");

The table name is used only to identify the table in the output reports. Up to 80 characters in the name will be stored by CSIM. A newly created table contains no values and all the statistics are zero.

A table can be initialized as a permanent table using the permanent_table function.

Prototype: permanent_table::permanent_table(char*
name)
Dynamic Example: td = new permanent_table("response
times");

The information in a permanent table is not cleared when the reset function is called, and a permanent table is not deleted when rerun is called. In all other ways, a permanent table is exactly like any other table. Permanent tables are often used to gather data across multiple runs of a model. As a general rule, do not make a table permanent unless you have a specific reason for doing so.

11.2. Tabulating Values

A value is included in a table using the record function.

Prototype: void table::tabulate(double value)
Dynamic Example: td->tabulate(1.0);

Tables are designed to maintain statistics on data of type double. Data of other types, such as integer, must be cast to type double in the call to record.

The record() method is equivalent to the tabulate() methods:

Prototype: void table::record(double value)
Dynamic Example: td->record(1.0);

11.3. Producing Reports

Reports for tables are most often produced by calling the report procedure, which prints reports for all statistics gathering objects. A report can be generated for a specified table at any time by calling the report_table method.

Prototype: void table::report(void)
Static Example: ts.report();

Reports can be produced for all existing tables by calling the report_tables function.

Prototype: void report_tables(void)
Example: report_tables();

The report for a table will include the table name and all statistics, as illustrated below. If the table is empty, a message to that effect is printed instead of the statistics.

A summary report for all tables can be generated by calling the table_summary function.

Prototype: void table_summary(void)
Example: table_summary();

The report that is produced contains one line for each table and includes only a subset of the statistics. If a table is empty, no statistics will appear in the last three columns.

11.4. Histograms

A histogram can be specified for a table in order to obtain more detailed information about the recorded values. The mode and other percentiles can often be estimated from a histogram. A histogram is specified for a table by calling the table_histogram function.

Prototype: void table::add_histogram(long nbucket,
double min, double max)
Static Example: ts.add_histogram(10, 0.0, 10.0);

The number of buckets in the histogram will be nbucket. The smallest value in the first bucket will be min; the largest value in the last bucket will be max. All buckets will have the same width of (max-min)/nbucket. An underflow bucket and an overflow bucket will automatically be created if needed to hold values less than min or greater than max.

Usually, a histogram is specified for a table immediately after the table is initialized. Additional calls can be made to add_histogram to change the characteristics of the histogram, but only if the table is empty.

A report for a table having a histogram will include an additional section as illustrated below. For each bucket in the histogram, the following information will be displayed: the smallest value the bucket can hold, the number of values in the bucket, the proportion of all values that are in the bucket, the proportion of all values in the bucket and all preceding buckets, and a bar whose length corresponds to the proportion of values in the bucket.

If leading or trailing buckets contain no values, the lines in the report for these buckets will not be printed. This allows the histogram to be output as compactly as possible without losing any information.

CSIM must save information for each bucket in a histogram. Consequently, the storage requirements for a table that has a histogram are proportional to the number of buckets.

11.5. Confidence Intervals

CSIM can automatically compute confidence intervals for the mean of the data in any table. The confidence interval calculations are enabled by calling the table_confidence function.

Prototype: void table::confidence(void)
Static Example: ts.confidence();

If confidence intervals have been requested, the report for a table will have an additional section, as illustrated below.

Chapter 16, "Confidence Intervals and Run Length Control" describes confidence intervals in detail and explains how to interpret the information in this report.

11.6. Moving Windows

By default, all values recorded in a table are included in the statistics. If a moving window is specified for a table, only the last n values are used in computing the statistics, where n is called the window size. A moving window is specified for a table using the moving_window method.

Prototype: void table::moving_window(long n)
Static Example: ts.moving_window(1000);

Usually, a table's moving window is specified immediately after the table is initialized. Additional calls can be made to table_moving_window to change the table's window size. It is an error to specify a moving window for a table that is not empty.

If a table has a window size of n, the last n values recorded in the table must be saved by CSIM. Consequently, the storage requirements for a table having a moving window are proportional to its window size.

11.7. Inspector Methods

All statistics maintained by a table can be retrieved during the execution of a model or upon its completion. The attributes of a table (i.e., its name and moving window size) can also be retrieved.

The following inspector methods retrieve information about the confidence interval associated with a table:

The following inspector methods retrieve information about the run length control associated with a table:

Although most statistics are mathematically undefined if there is no data, the corresponding inspector methods return a value of zero if the table is empty.

The following inspector methods retrieve information about the histogram associated with a table.

The number of buckets in a histogram does not include the underflow or overflow buckets. Bucket number 0 is the underflow bucket; bucket number 1+histogram_num( ) is the overflow bucket. If a histogram has not been specified for a table, the above inspector methods all return zero values.

The inspector methods that retrieve information about the results of run-length control are described in section 16.3.

11.8. Renaming a Table

The name of a table can be changed at any time using the set_name method.

Prototype: void table::set_name(char *new_name)
Static Example: ts.set_name("elapsed time");

Only the first 80 characters of the table's name are stored

11.9. Resetting a Table

Resetting a table causes all information maintained by the table to be reinitialized. All optional features selected for the table (e.g., histogram, confidence intervals, moving window) remain in effect and are also reinitialized.

The reset function is usually used to reset all statistics gathering tools at once. A specific table can be reset using the reset_table function.

Prototype: void table::reset(void)
Static Example: ts.reset();

Although permanent tables are not reset by the reset function, they can be reset explicitly by calling reset_table.

11.10. Deleting a Table

When a dynamic table is no longer needed, its storage can be reclaimed using the delete_table function.

Example: delete td;

Once a table has been deleted, it must not be further referenced. If enhancements (either histogram, confidence intervals, or moving window) have been defined for a table, the each of these enhancements is also deleted when the corresponding table is deleted.

Next Section