Copyright © 1995-2001 MZA Associates Corporation
The trf toolbox is a group of Matlab m-file functions that provide access to data stored in trf files. With the trf toolbox, the user loads data resulting from a tempus execution into Matlab for visualization and analysis.
To open trf files users invoke the trfopen command. The trfopen command returns a Matlab data structure called a trf_handle. trf_handles are subsequently used to select and load data from the file.
Users are not typically interested in all of the data stored in a trf file. Furthermore, trf files are often too large to have their entire contents loaded into a Matlab session. Therefore, it is often necessary to restrict the data that is to be loaded to a subset of the total amount of data in the file. The approach to doing this will vary depending on the circumstances. In some cases, users will be interested in loading all of the data from a particular run. In others, users will want to load the data corresponding to a particular variable name for all runs.
The most powerful way of selecting which data is to be loaded is using the trfsel function. trfsel provides the user with an interactive graphical user interface that allows full flexibility in choosing the data to be loaded. trfsel assists the user in both selecting and loading the data.
For repetitive tasks where a command procedure or m-file function works better than a GUI, the functions trfload and trfrack are provided. Both functions allow the user to specify wildcard strings, which must appear in the names of the runs or variables to be loaded. trfload is flexible in that it loads data from different runs no matter what the actual data structure or contents. trfrack is more restrictive in that all data loaded from different runs must be the same size and stored for the same sample times. However, trfrack returns data in a packed array, which is easier to manipulate with Matlab functions.
trf toolbox functions load data into two types of Matlab data structures, trf_handle and trf_rack. The first, a trf_handle is the most general since it can be used to successively trim down run and variable selections. In addition, trf_handle has no restrictions on the specific size and contents of the data from run-to-run. On the other hand, trf_rack structures limit the size and contents of the data, but are more convenient for plotting and analyzing data from different runs.
To properly use trf toolbox functions, the user must have the file system locations of the to the function mfiles in his Matlab path. This is typically taken care of automatically. The documentation that follows can also be obtained by typing help "function name" at the Matlab prompt.
trfsel is executed using one of three command invocation formats:
[trfhs] = trfsel(trfh)
[trfrk1, trfrk2, ...] = trfsel(trfh)
[trfrkcell] = trfsel(trfh, 1)
where trfh is a trf_handle and the output arguments are documented in the trfsel reference page. Once provided a valid input trf_handle, trfsel displays a window containing a list of the current runs and the variables available for the first run. For example, in Figure 1 the user has specified a trf_handle with fifty runs where the first run has eight variables.
Figure 1: An Example of the Initial trfsel GUI Window
In this window, the user selects the particular variables from the particular runs that he would like to load. Table 1 describes the various elements of the GUI window:
Table 1: trfsel GUI Window Elements
|
Element |
Description |
|
Title Bar |
Lists the name of the file with which the input trf_handle is associated. |
|
Number of Runs |
Lists the total number of runs in the trf file. |
|
Lists the total number of variables contained in the selected run. |
|
|
Lists the names of all of the runs available in the trf file. Clicking on a particular run with the left mouse button causes the Available Variables selection box to display the variables for that run. The names of runs for which variables have been selected are preceded by a plus sign. The names of runs for which no variables have been selected are preceded by a minus sign (see Figure 2). Only one run may be selected at a time unless the Select All Runs button has been pressed. |
|
|
Lists all variables available for the selected run (or all runs when the Select All Runs button has been pressed). The names of variables that have been selected are preceded by a plus sign. The names of variables that have not been selected are preceded by a minus sign. To select a particular variable click on it with the left mouse button. To deselect a selected variable, click on it again. The selection status of a run is changed when the non-selected variable of a run is selected and when the last selected variable is deselected. |
|
|
Select All Runs |
Causes only variables that are common to all runs to be displayed. In this case, the Available Runs selection box is disabled and all future variable selections are assumed to apply to all runs (see Figure 3). An additional consequence is that all previous selections are ignored. Use of this button is necessary to enable a trf_rack return type. |
|
Select All Variables Deselect All Variables |
Causes all variables for the currently selected run (or all runs when Select All Runs has been pressed) to be selected. This button toggles between Select All and Deselect All. |
|
Causes all selected data to be loaded. The GUI terminates while returning results in a trf_handle. |
|
|
Load & Rack |
Causes all selected data to be loaded and racked. The GUI terminates while returning loaded results in trf_rack structures. This option is only available when the user has used Select All Runs. |
|
Done |
Without loading data, the GUI terminates and returns a trf_handle containing only the selected runs and variables. |
|
Cancel |
The GUI terminates, setting all return values to the null matrix. |
Figure 2: A trfsel GUI Window in which some variables are selected
Figure 3: A trfsel GUI window in which Select All Runs has been pressed
