Data plotting

Files of numerical data can be manipulated, analyzed, and plotted. The format for a data file is one or more floating-point numbers per line, with the same number of entries per line. A line in a data file that starts with a % is a comment.

Roughly, the basic plot command reads numbers from two (or three) columns of a specified file, treats them as coordinates, and plots the resulting points.

  plot("filename", STYLE, columns, [i_1], [i_2], [i_3], [F]);

The first argument is the name of the data file. The STYLE may be PATH, which joins the points in the order they appear, or any of the marker types in Table 2.1. Next comes the number of columns (entries per line); if there are fewer columns than expected in the file, nothing is plotted, while if there are more columns than expected, a warning is issued but the data is plotted. The remaining arguments are optional. The integers $i_k$ specify columns from which to extract data. The column entries are fed to the P-valued function F to obtain points. If F is omitted, it defaults to the Cartesian point constructor. If $i_3$ is omitted, the $i_1$ and $i_2$ columns are used to create points; by default, $i_1=1$ and $i_2=2$. For example, if mydata.dat contains 6 columns of numbers, then the respective commands

  plot("mydata.dat", DOWN, 6);
  plot("mydata.dat", BOX, 6, 2, 4, 5, sph);

plot the first two columns of mydata.dat, putting a `` $\bigtriangledown$'' at each point; and extract the second, fourth, and fifth columns of the file, treat them as spherical coordinates, and put a ``'' at each point.

For more elaborate (e.g., user-defined) analysis, data may be read into a FILEDATA structure. A FILEDATA is a C++ vector of columns, each column having as many entries as there are lines of data in the file. The snippet below reads data from a file, then plots the result.

  FILEDATA my_cols(6);          // vector of 6 columns
  read("mydata.dat", my_cols);  // read data from file
  ...                           // code to mangle data
  plot(my_cols, BOX, 2, 4, 5, sph);

The number of columns needn't be specified in the plot command, since it was provided when the data was read. The post-TYPE options are identical to the earlier plot command. The $j$th entry of the $i$th column is called my_cols.at(i).at(j).

ePiX implements simple numerical functions of a FILEDATA structure:

  avg(my_cols, i_1);     // arithmetic mean of the i_1 column
  var(my_cols, i_1);     // variance of the i_1 column
  covar(my_cols, i_1, i_2); 
  regression(my_cols, i_1, i_2);  // draw regression line

The covariance of two columns is obtained by subtracting the respective averages entry by entry, then taking the dot product. The regression line is the least-squares best fit for predicting column $i_2$ from column $i_1$.