Previous: Introduction
Up: User's Manual for the mpl Scientific Toolkit
Next: Command-Line Format of the mpl Programs
Previous Page: Introduction
Next Page: Command-Line Format of the mpl Programs

mpl Data Set Format

An mpl data set is an ordinary text file, such as might be created using a text editor. The lines of the file are read and processed one at a time, and no line may be longer than 1024 characters. The file format can be represented as follows, where exclamation points introduce comments: ! x and y scale labels:
x-scale-label
y-scale-label
! the ``title'' label:
title-label
! the ``topline'' label:
topline-label
number_of_points
x[0] y[0] [ [0] | [0] [0] ]
x[1] y[1] [ [1] | [1] [1] ]
.
.
.
The first four lines are descriptive text (as opposed to numeric data). The first line is generally the name of the abscissa (or ``x'' variable), while the second line is generally the name of the ordinate (or ``y'' variable); these lines will be used to label the x and y scales when the data set is plotted with mpl. The third and fourth lines will be placed at the bottom and top of the plot, respectively, when the data set is plotted with mpl; they are referred to as the ``title'' and ``topline'' labels, respectively. The conventional format for the first and second lines is <quantity-name> (<quantity-unit>); while this is not required, some programs detect this format in order to be able to alter the units automatically.

The fifth line contains the number of data points in the data set. It should be equal to or larger than the number actually in the data set. A warning will appear if this number is different from the actual number of points. (The program fixcount is available to count the points for you and put the right number on the fifth line of the data file.)

Every subsequent line contains one data point, each of which consists of two through four numbers. The first two values are x and y, respectively, and are required. The third and fourth values are optional (as indicated by the square brackets). If there are three values, the third is interpreted as the uncertainty (or ``sigma'') for the y value. If there are four values, the third is interpreted as the x uncertainty, and the fourth as the y uncertainty. The number of values that are taken from each line is established by the number of values given for the first data point. Thus, if the first data point contains only two values, then only the first two values of each subsequent data point are used. Similarly, if the first data point contains four values, then all subsequent data points are expected to contain four values.

The data set ends when the file ends, or when the number of points specified has been reached, whichever comes first.

The format of the data is very free. Any non-numeric ASCII character (i.e., any character other than a digit, a plus or minus sign, or a period) can be used as a separator between data elements on a single line. Spaces and tabs are preferred, but solely for aesthetic reasons. Any line beginning with an exclamation point is treated as a comment, and ignored.



Previous: Introduction
Up: User's Manual for the mpl Scientific Toolkit
Next: Command-Line Format of the mpl Programs
Previous Page: Introduction
Next Page: Command-Line Format of the mpl Programs

borland@aps.anl.gov
Thu Dec 23 15:13:43 CST 1993