next up previous contents
Next: Printing Data Up: Saving and Loading Data Previous: Auxillary Function Values   Contents


Loading Unformatted Data

It is probable that users of dstool will occasionally generate data outside of dstool (via another software program). If desired, it is possible to load this data into dstool in order to view, print, or manipulate it. This can be done by selecting the Unformatted option from the Load Window. Doing so causes the load window to extend vertically, thereby revealing additional panel items which are used to control the loading of unformatted data. Refer to the User's Manual for more information about the Load Window and the meaning of each panel item.

An unformatted data file consists of an optional header, followed by a list of floating point numbers and integers. In many cases these numbers will be arranged in columns. Each line of the header must begin with the comment symbol # (the pound sign). As soon as dstool reads a line which does not begin with a pound sign, it will assume that it should begin to read data. A typical header looks something like the following:

# Written by Tom Jones, Sun Jun 16 19:20:43 EDT 1991
# This file contains fixed points for a time-indep 4D symplectic mapping.
# They were calculated using Maple.
# The parameters for this run are:  a = 0.3; b = -0.734; c = 1.24;
# These fixed points occur on the plane  w = 0.
# The variables contained here are x,y,z.
# Color is ON
# Symbols are ON
It is suggested that every data file has a header of the above type which identifies what the file contains and what relevant system parameters were at the time that the file was created.

When loading unformatted data, the user is given the option to load the data into an appropriate memory object. When the user chooses the memory object which will contain the unformatted data, dstool loads the data. It is assumed that the unformatted data is appropriate for the chosen data object. Furthermore, each file may contain at most one type of data. For example, if a data file contains trajectory data, then that same data cannot also contain fixed point data.

When loading unformatted data, dstool always reads the current values of the phase space variables, the parameters (visible in the Selected Point Panel), the plotting symbol and size (visible in the Defaults Panel), and the current plotting color. Unless these values are set by the unformatted data file being read, they are used as default values. For example, if the user is reading in fixed point data and does not set color or symbol information within the file, then the current color and symbol are used to plot the unformatted data. In this same example, if the user does not include information on parameter values, then the current parameters are used.

We've already looked at a sample header for an unformatted data file. The remainder of that same file might look something like the following:


		  5.6319926e-13 		 5.6319926e-13 		 -1.689818e-12 		 7 		 6 

0.485636829 0.852655 0.500015 23 11
-0.485636322 0.852655 0.500001 59 16
According to the header, the first three columns are the x, y, and z values of each fixed point. The fourth column contains color information and the last column contains symbol information. To load this file into dstool, the user would first set the parameter values a, b, and c, to reflect those parameter values specified in the header. The variable w should also be set to the value 0, since each of these fixed points occur in the plane w=0. Variables and parameters may be explicitly set in the Selected Point Panel. Since the particular set of equations being studied is time independent, the user may choose to ignore the variable time.

The user then selects the unformatted load option from the Load Window, types in a valid directory and filename, and proceeds to choose panels items which tell dstool that the file to be read contains fixed point data, color information, and symbol information. The user then tells dstool that it should expect to read the variables x, y, and z by selecting the appropriate rows of the variables list. See the User's Manual for more information on how to use the Load Window.

When the user finally presses the Load command button, dstool finds the specified file (provided the file exists and is readable), skips over the header, and reads the three fixed points from the file into fixed point memory objects. Associated with each memory object is optional color and symbol data. In the example above, the first fixed point is assigned color 7. This means that whenever a ``pick color'' colormap is in use, then the color of the fixed point will be the seventh color on whatever colormap is currently in use. (If a ``depth'' colormap is in use, then the color of the fixed point depends on its coordinates; if an alternating colormap is in use, the color of the fixed point will be whatever the current alternating color was when the fixed point was loaded.) Similarly, the second and third fixed points are assigned the twenty-third and fifty-ninth color, respectively, whenever a ``pick color'' colormap is in use.

Also associated with each memory object is a symbol. In the example above, the first fixed point was assigned symbol 6, the second was assigned symbol 11, and the third, symbol 16. The table below summarizes what integer is associated with each symbol.

Table 1.1: Integer codes for plotting symbols within dstool.
Integer Code Plotting Symbol
1 Small Dot
2 Medium Dot
3 Large Dot
4 Huge Dot
5 Small Triangle
6 Medium Triangle
7 Large Triangle
8 Huge Triangle
9 Small Cross
10 Medium Cross
11 Large Cross
12 Huge Cross
13 Small Box
14 Medium Box
15 Large Box
16 Huge Box

Additional comments about the way dstool reads unformatted data:

1.
The order that variables appear in the variable list (on the Load Window) is precisely the order in which dstool expects to encounter variables in a file. In the above example, since the variables x, y, and z were selected from the Load Window variable list, dstool will read the first number it encounters into an x position, the next number it meets into the y variable, and the third number it finds into the z variable position. If the user had mistakenly read in a file in which the first column contained values for the z variable, then dstool would mistakenly place these values into the x variable. The same is true for the order in which parameters appear on the parameter list.
2.
All variables are read before any parameters are read. In other words, if a user has specified that a file contains n variables and k parameters, then the first n numbers dstool encounters will be stuffed into the specified variable slots, and the next k numbers it finds will be assigned to the specified parameter values.
3.
Dstool will read color information (if any) only after reading all specified variables and parameters.
4.
Dstool will read symbol information (if any) only after reading all specified variables, parameters, and any color information.
5.
Although data files usually contain columns of data, this is not necessary. As long as there is white space (blanks or tabs) between pieces of data, dstool will assign the data correctly. Thus the data for the above example could also appear within its file as
5.6319926e-13   5.6319926e-13  -1.689818e-12  7  6  0.48563682
0.852655  0.500015  23   11  -0.485636322  0.852655
0.500001  59  16


next up previous contents
Next: Printing Data Up: Saving and Loading Data Previous: Auxillary Function Values   Contents
root
1998-11-02