Table

Overview

A Table is a set of cells that contain data arranged into rows and columns.
A model user can enter and/or change the data in the cells of a table either before or during a model run.

During a model run the model itself can record or change data in a table (using Routines).
Tables can be viewed on panels in your model and used to display inputs and outputs.
Tables may also be displayed Graphically as described in Table View Display.

There is no limit to the number of tables you can create when you build a model.
You can use tables to construct almost any arrangement for either feeding parameters into your model or reporting model behaviour.
A table is useful where you have a range of configuration settings used in a model run that would have to be repeated many times if they were input locally.
The table can become a centralized repository for interaction and other specifications that control the behaviour of your model. The figures are then easily accessed and changed during a parametric study.
You can collect a range of comparative statistics for a group of objects in a model and produce a file output that is the equivalent of a filtered overlay from the Log Display System.

Each table is given a name so it can be addressed by the model. Tables store their cell data as double precision values and you can use label lists to display text in the cells.

Using routines, values can be "put into" and "read from” a table by addressing the table by its name and using the Cell, Column, Row or Table Mode. Tables can be used for the same purposes as attributes in general. You can use the File Option of the Change Object to write the contents of a table to a file, or read data from a file into the table, during a model run.

Tables are created and edited in the Tables option under Data in the Menu Bar, or in the Tables Option of the Portal Object Edit Menu and the Portal Entry Object Edit Menu.

How to Create, Edit a Table

Click on a Portal Object or Click on the Menu Bar and Select Table
A list of Tables is provided.
Right Click to Edit an existing Table
Or click on the Add Table button to create a new Table
To the Add a New Table dialog, enter the following:
A Name (used when referencing the table in the Attribute Selection Dialog.
An optional longer Title (used in Views of that Table).
Size the Table - number of Rows and Columns.
The initial option Clear All at Start, removes all rows from the table each time a Model Run starts.
(This option can be changed later on)
The Table Editor Window Appears, which can be resized, and can remain visible during a model run if you want it to. The Table Editor has its own menu bar with Menu Items described below:

Addressing Tables inside a Model

Using routines, values can be entered into and read from a table by putting your Attribute Selection Dialog into a number of "Modes ", as follows:
Mode Description
Cell Mode The attribute referred to ("Constant", "Item" etc.) takes the role of an Index to a specific Row or Column of the table. To locate a cell in a table that has more than 1 column and row, you need two attribute references - one for the row, and one for the column index.
Table Mode A special mode where the where the table AS A WHOLE is referenced, rather than a single element.
Column Mode The attribute referred to is an Index to a specific Column of the table (All rows).
Row Mode The attribute referred to is an Index to a specific Row of the table (All columns).
Mapper Mode A special mode that applies to Table that Act as Mappers.
Property Mode You supply the Table Name, and the system returns to you either a row count or column count for that Table.

Sorting

Table rows may be sorted by the model user or by the model itself.
This Dialog enables you or a Model User to sort a table in a very flexible manner.
To specify a table sort, start by selecting the first column you wish to sort by.
Do this by clicking the <None> button. The Table Columns dialog shows the columns in the table so you can select one.
Once you have selected a column, two additional buttons appear.
“Incr” indicates you want to sort by increasing value. If you want to sort decreasing, click that button and it will toggle to “Decr”, meaning sort by decreasing value.
The “Numeric” button indicates the column should be treated as numbers during the sort. If the column contains labels, you may want to sort alphabetically instead. Click the “Numeric” button and it will toggle to “Alpha”.
You can specify additional columns for the sort by repeating this process (up to 8).

Mapper Behaviour

The Mapper enables interpolation of values for mappings which fall between the coordinates of the set points on the graph or mapping. This enables a flexible response to a range of inputs to mirror the reality occurring.
Typically many inputs produce a non-linear type of output.
For example the fuel consumption in a power station is non-linear in relation to increasing levels of power output. Furthermore different fuels relate to different levels of power output. Accordingly a family of mappings may be referred to in order to properly represent the power outputs resulting from a range of electricity generation strategies.
The x-coordinates usually represent units of time. However the mappings may in one column refer to time in days, in another column to weeks, and in another column to months or years. These options make the Mapper more powerful and much more flexible than the typical spreadsheet application.
The Mapper is of particular value in the development of Top Level and Strategic Models of Organizational Operation. Historical and/or Projected Relationships may be loaded in from spreadsheet applications.

Act as Mapper is a special setting for a Table (On by default) that enables the mapping, or translation, of values from one domain, (an X-Axis) to many possible ranges (Y-Axes). Many systems, or inputs typically produce a non-linear type of output. Performance of a system or system component can change over time, or depend on some condition of the system.
E.g. A crane lifting ore from a ship's hold :
Due to the need to push material into the centre of a hold, where it can be
reached by the crane, the loading time per " lift " will vary as follows:
Percent Full 10 20 40 60 80 100 (X-Axis)
Load Time 500 500 390 200 100 50 (Y-Axis)
In Planimate®, you can do this using tables, but they are limited in that they can only " step " from one relationship to another. In the above example, if you were using a table, the load time between 60-69% full would be 200 secs and between 70-80% full would be 100secs. This kind of stepping may not be what you really want.
A Mapper will "smooth out" the steps of such a relationship, because it interpolates values that fall between the set points on the X axis of the graph or mapping (i.e. column 1 of the table).
In the above example, using a mapper would mean that the load time at 70% full would be 150 secs.

A Table set to Act as a Mapper has special features

Column 1 of the mapper table is always the X-Axis of the mapped relationship.
The Value to be Mapped (i.e. given to the Mapper) becomes the X-Axis value.
Column 1's values must always be in ascending order... 1, 3, 5, 7, 9...etc.
Columns 2 and beyond represent the Y-Axes, which are the Returned Value .
You obtain Values from a Mapper by putting your Attribute Selection Dialog into the " Mapper " Mode.
The Attribute to remap is given to the Mapper. This value will be an attribute reference, because we expect it to vary.
Thus, using the above example of the ship's hold, if you wanted to obtain the load time for the next crane cycle, you would first set up an Attribute to be the measure how full the hold is (probably a Portal Attribute).
Then you would Create the Mapper, putting Percent Full values in Column 1.
Next, you would use either a Change Object "Set" calculation, or a scaled (or direct) reference in a Distribution Pattern Dialog , to obtain the delay time to be applied.
As the model runs, the Percent Full attribute is used as the Attribute to remap .
Each crane cycle decreases the Percent Full value. The Mapper uses it to interpolate between values in the X-Axis. The same interpolation is performed for the corresponding Y-Axis points, and this interpolated value is returned to you from the Mapper. The Mapper may be edited by means of an interactive graphical view .
The data may also be viewed as a Table, which may be imported/exported during edit or run-time.

Mapper Limitations in Use

The Mapper produces interpolated readings for intermediate points on a graph.
Accordingly it is important to ensure that the coordinates inputted properly represent the shape of the graph actually occurring, and that the modeller remains alert to possible distortions due to inappropriate interpolation.

Conditions Applying for Mappers to Remap Properly
The following conditions apply...
Successive values of 'x' must be increasing.
The SUM of <y1> to <yn> must equal 1.0
Unlike the CDF, only the values specified will be produced.
No interpolation is performed between values.

Dynamic Table referencing

Use of the “<Dynamic>” table reference feature enables the model to address a variety of different tables through the use of attribute referencing. Dynamic table referencing enables a table in an attref to be lookup up on-the-fly using names in a label list. This feature can thus be used to implement "3d" tables. You need to create a Label list that includes the names (not titles) of the tables you intend to reference.
You can access a dynamic table reference by moving to the bottom of the tables listing, and choosing the “Dynamic” option there. You are then prompted for a further attribute, and this attribute must be formatted to make use of the label list of table names, before the reference can work.
This feature may be of great use, however we strongly recommend that its use should be constrained. It is VERY indirect, and therefore there is a serious trade-off in using this feature. The trade-off is the lack of reference-tracking that can be done on the table operations – they can become effectively invisible to a direct attempt to trace them, and you have to find references to them in a roundabout way (by tracing the use of the label list of table names).

Export from Table to File

A button enables you to browse for the file. The last name used is stored in the model.
The file format will be Text and Tab delimited.
The following options are available for you to specify the structure and nature of your import data.
Option Description
Row Labels Import Data contains Row Labels (before column 1 data).
Col Labels Import Data contains Column Labels (before Row 1 data)
Formatted Output the data in its formatted state. This is normally what you would want. With this option off, the raw data values are written instead.

Manual Data Import/Export

During editing of a Model, you can import data from files into Tables, and into Label Lists.

Importing File Data into a Table

Refer to Import from Clipboard or File to Table for details of how to do this.

Exporting Table Data into a File

Refer to <Export from Table to File> for details of how to do this.
If the content of the file and the table do not match a warning dialog appears.

Importing File Data into a Label List

Refer to <Importing and Exporting Label Lists> for details of how to do this.

Exporting Label List Data into a File

Refer to <Importing and Exporting Label Lists> for details of how to do this.

Routine driven Data Import/Export

Planimate® enables reading and writing of raw data to and from an ASCII file. These events are triggered by an item passing through an appropriately configured Change Object.
By default, Data Files are tab separated ASCII files with the extension ".DAT ". However a range of options enable their format and contents to be flexibly configured.
Click on a Change Object in Object View to display a menu, from which you may select the option File.

File Transfer Mode

The File Transfer Mode “Read raw data file” is offered by default in a new Change Object. However there are a number of file operations other than just reading and writing that are supported by Planimate®.
Click on the Mode Option in the Menu to display and select other Modes, which are as follows:

• Read raw data file See Below for details.
• Write raw data file See Below for details.
• Execute command only No file operation is performed here, you are offered a field in which you can enter a system command.
• Play Sound Offers a field in which you can enter a reference to a .WAV file. When an Item passes through this Change Object, the sound will be played asynchronously. If you want the sound to be played synchronously, select the “Wait for File to Complete” option.
• Test / read file size This tests for the existence of a file, and deposits result into first attribute in the Data Targets list. It returns sizes of file (0..2Billion) or -1 if the file does not exist. This operation also sets the "Error Result" attribute to the file size.
• Save window image Offers a File Name with which the currently-visible panel will be saved, in the form of a bitmap image ( .BMP extension). This File operation can also be set to write to the clipboard. Supply a filename of just "-" (using the dynamic filename option and a label list) and instead of the bitmap being written to a file, it will be placed into the clipboard, from which the user can paste the image into a graphics application.
• Rename file Offers two fields for renaming files, from and to.
• Copy file Offers two fields for copying files, from and to.
• Delete file Offers a Field for naming the file to be deleted. An option enables you to reference an Attribute (formatted with a Label List) to supply the name of the file to be deleted.
• Fetch hyperlink Initiates a URL read from a change object - no content is actually read from the web server yet. The "from" spec can either be a file spec, in which case the URL is read from the first line of the file OR a direct URL reference. In either case INI file mappings are applied to the from file name/URL
• Create folder Offers a Field for naming the folder to be created. An option enables you to reference an Attribute (formatted with a Label List) to supply the name of the file to be deleted.
• Test/Read resource size This mode is similar to the Test File Size routine mode except it looks in Planimate® databases as well. In this mode, "Target File Attribute" names a file/resource. If the name doesn't include an extension, "RTF" is assumed. The file operation sets the first "Data Target" (if any exist) and the "Error Result" to the file size (in bytes) of the resource or -1 if the resource is not found. This is useful to test if RTF notes exist.
• Delete resource This is intended to be used to "clear out" RTF notes from a Planimate® database resource (.DB) file. This will remove the specified item from the runtime database (if set up) otherwise the model database is used (if available, not for a standalone EXE). If the name does not include an extension, "RTF" is assumed.
• Acquire file lock Refer to File Locking in Planimate® for details.
• Release file lock Refer to File Locking in Planimate® for details.

Reading Raw Data Files

Reading of Raw Data from a File is specified by entering details in the menu as shown.
Select the Mode Read Raw Data File from the File Transfer Options menu.
Choose the Target File from the File Access Options menu.
Select from the Options available, refer to File Transfer Options for details about options.
If you want to begin your File read other than at the start of the file, specify File Row and File Col offsets.
If you want to read a portion only of the File, specify the Limit Rows and Limit Cols ranges.
The above settings can make reference to numbers, or strings (labels) using the Attribute Value Selection Dialog.
If you wish to have a system command executed at the time of this file read, enter the command string in the Execute Option. Otherwise leave it blank.
Select the Target Attributes into which the data read from the file will be placed.
Tables will accept and read arbitrary length tables from a file. The table does not shrink if less data is loaded than required, but it will expand to fit total number of rows read.
Reading into a block offset is supported. The table is padded with rows to achieve the required block row offset. For example if a block read is started at table row 1000, an empty table will have rows 1...999 inserted before row 1000 (the first read row)

Writing Raw Data Files

In the File Access Options Menu, first choose the Mode you wish to use by selecting the mode option. The default mode is Write raw data file. The File Transfer Mode item picker dialog displays other options available under Mode. You then select the Target File option from the File Access Options menu. Either type in a file name of you choice, or from the files displayed in the browser that appears, choose one.
Next select Options in the File Access Options Menu, and the File Write Options list picker dialog appears. The File Write Targets menu then appears. Targets may be added by means of the Attribute Value Selection dialog that appears when " Add Target " is selected.

Selecting Data Targets

The File Transfer Targets menu enables you to use the Attribute Selection Dialog to set those attributes that will be written to when a file is read, or read from when a file is written.
Targets may be added by means of the Attribute Value Selection Dialog that appears when " Add New " is selected.
You may select any combination of Attributes, Table Cells, Columns, Rows or Entire Tables to be written into the file. The write targets may be changed by selecting the name again. The Attribute Value Selection Dialog enables the amendment of the selection, or it may be deleted by pressing the Delete Button.
You can change the order of the File Transfer Targets by using the Up and Dn buttons.
As you run the model, all types of attributes and complete tables, may be written to the selected file, and if specified, will be appended one below the other in the sequence selected in the File Transfer Targets Menu.

File Transfer Options

The following options - where appropriate - are made available for one or more of the File Transfer Types you can perform.

• Append to Existing File/Table Appends data below previous entries already written to the file in a File Write. Appends data below previous entries already in the Table Targets of a File Read.
• Formatted Values Format values as defined for the attributes: e.g. label texts are included, money entries are displayed as $1.00, time appears as 00:05 21.00, rates as /min etc. as appropriate.
• Accept Incomplete Tables (Reading Only) If the file data is targeted at a table that has more columns that in the file, the data will still be read into the columns that are there.
• Delete File After Read (Reading Only) Deletes a File after it is read into the Model.
• Wait for File to exist (Reading Only) Suspends the running model until the file exists, and can be read.
• Remove Trailing Spaces (Reading Only) Any text data that has training spaces will have those spaces removed before being placed into the data target.
• Remove enclosing 's (Reading Only) Removes enclosing single quotes and strips any junk outside of single quote pairs, first character must be ' for this to activate. The import filter treats quoted empty field the same as an unquoted empty field.
• Automatically Add labels (Reading Only) Any labels not already in the label list that the target column or attribute is formatted to will be added automatically, without asking the user to accept them.
• Read over Existing Table contents (Reading Only) With this option "on", Planimate® will not clear a table before reading into it. Instead, Planimate® will attempt to read the file based on the formats of the existing cells in the table. This is VERY useful combined with using cell specific formats in a table. The modeller can specify what format data should be read in on a cell-by-cell basis (including different label lists). With this option on, PL doesn't read data past the rows already present in the table.
• Write Titles as Well Places attribute names beside the entries, and titles, column and row headings for tables..
• Delimit Using Commas Use or assume use of Commas instead of Tabs to delimit values.
• Write without delimiters (Writing Only) Write a file output with no delimiters between cells.
• Write 4 digit years (Writing Only) Use 4 digit years, even if date format is just two.
• Show File Browser First Offer a File browser for the User or modeller to choose the name of the file to be written to or read from.
• Quote all Fields (Writing Only) Place Double Quotes around all fields in the table being written.
• Dynamic Filename Implement a placeholder for an attribute reference to be used to identify the file name under program control, rather than manually entered, or hard coded file names.
• Transpose Tables Transforms a table with 3 rows and 2 columns into a display of 2 rows and 3 columns.
• Minimise Command Window When a command requires the creation of a Command window, the window will be launched, but will be minimized.

Table Options

The Table Edit Window has a Menu Bar. Under Table in that menu bar, you can set options for the table, as follows:
Option Description

• Act as Mapper: Column Overlay Views of the table will use Column 1 values on the X-axis display. Table can also be used as a value Mapper - where a Mapper Mode reference is used.
• 'Show Row Label Numbers': Self Explanatory
• Show Col Label Numbers: Self explanatory.
• User Can Sort: In InterDyne model, the Model User can access a Table Sort Dialog when they click on the Title of a Table View.
• User Cannot Add/Delete Rows: Prevent an InterDyne Model User from performing row operations on a Table View.
• Delete/Clear All at Start: Remove all Rows from the Table each time a Model Run is started.
• Column Colours take Precedence: Where Row colours are being applied and a table has some columns with background colors set, the column colour will prevail.
• Index Colours from 1 not 0: Applies to Row colour column reference value interpretation. This option applies only for VERY old models. It is obsolete for newer Models, where colours are always indexed from zero.
• Second Title Row: Provides a Row, and editing location for an additional Column Title, below the first title.
• Clear Rows before Saving: All rows will be deleted from the Table whenever it is saved. (Keeps MDL file size down for shipping & archiving etc).
• User Edits don't set Data Modified flag: If values in this table are edited, the Model will not consider this a reason to prompt the User to save.
• Reset Cells to Default at Start: All Table Cell Properties will be reset to their default at the beginning of each Model Run.
• Retain on Paste/Replace: If the owning portal object is a target in a paste/replace operation, this table will not be overwritten, but will retain its existing values, formats and structures etc.
• Show Table's Comment when Empty: If the table has no rows, or no columns, or both, then a View of that table will display the comment for the table in the area where rows and columns would be seen.
• Lock Cell Formats: This option prevents table cell formats being copied (losing the existing format) when routine code assigns a table, row or column to another table, row or column.
  

Table Related System Attributes

Relating to the currently-referenced table in a routine operation.
Name Read / Write Description

• Table Rows R This gives access to the rows/column count for the table being referenced by the overall attribute reference. The advantage is that they can be used directly in a row or column index without having to use a separate temporary attribute and a separate routine line to set it.These attributes can determine a table from: direct references within an attref; dynamic table references; item table references (if item is available); implied (eg: a sort column attref in a sort knows the target table even though that table hasn't been directly specified in that attref
• Table Columns R As above.

Item Table References

Items can carry references to table in a model so it can be referenced anywhere in the model. An item table reference only allows reading of the table.
To use an item table reference, in the Item Edit menu, create a named table reference for the class, say called "test". From now on, when editing a routine with that item flow involved and you select a table, you will now have "<item> test" available, enabling use of the item's reference to supply the table as well as the original tables and <Dynamic>.
Field Description

• Name Name of the Item Table Reference.
• Comment A place for you to enter a comment to guide those who will follow you.

Import from Clipboard or File to Table

If you are importing from the Clipboard no file selection button is shown.
If you are importing from a file, a button enables you to browse for the file.
The last name used is stored in the model. The file format must be Text and Tab delimited.
The following options are available for you to specify the structure and nature of your import data.
Option Description

• Row Labels Import Data contains Row Labels (before column 1 data).
• Col Labels Import Data contains Column Labels (before Row 1 data)
• Auto Column Type Auto Column Type will automatically detect, and implement for a column, a special Column Unit type (like Time or Money).
• Append Rows Import Data will be appended to Existing Rows. Leave unchecked to remove existing rows before Importing this data.
• Resize Columns If the number of columns of data in the Import Data is different to the current Table, then add, or remove columns to suit the incoming data. (Careful - this does not go well with importing Col labels also).