Stats (Statistical Summary)

Syntax:

stats {<ranges>} 'filename' {matrix | using N{:M}} {name 'prefix'} {{no}output}

This command prepares a statistical summary of the data in one or two columns of a file. The using specifier is interpreted in the same way as for plot commands. See plot for details on the index, every, and using directives. Data points are filtered against both xrange and yrange before analysis. See set xrange. The summary is printed to the screen by default. Output can be redirected to a file by prior use of the command set print, or suppressed altogether using the nooutput option.

In addition to printed output, the program stores the individual statistics into three sets of variables. The first set of variables reports how the data is laid out in the file: The array of column headers is generated only if option set datafile columnheaders is in effect.

The second set reports properties of the in-range data from a single column. This column is treated as y. If the y axis is autoscaled then no range limits are applied. Otherwise only values in the range [ymin:ymax] are considered.

If two columns are analysed jointly by a single stats command, the suffix "_x" or "_y" is appended to each variable name. I.e. STATS_min_x is the minimum value found in the first column, while STATS_min_y is the minimum value found in the second column. In this case points are filtered by testing against both xrange and yrange.

The third set of variables is only relevant to analysis of two data columns.

Keyword matrix indicates that the input consists of a matrix (see matrix); the usual statistics are generated by considering all matrix elements. The matrix dimensions are saved in variables STATS_size_x and STATS_size_y.

The index reported in STATS_index_xxx corresponds to the value of pseudo-column 0 ($0) in plot commands. I.e. the first point has index 0, the last point has index N-1.

Data values are sorted to find the median and quartile boundaries. If the total number of points N is odd, then the median value is taken as the value of data point (N+1)/2. If N is even, then the median is reported as the mean value of points N/2 and (N+2)/2. Equivalent treatment is used for the quartile boundaries.

For an example of using the stats command to annotate a subsequent plot, see stats.dem.

The stats command in this version of gnuplot can handle log-scaled data, but not the content of time/date fields (set xdata time or set ydata time). This restriction may be relaxed in a future version.

Name

It may be convenient to track the statistics from more than one file or data column in parallel. The name option causes the default prefix "STATS" to be replaced by a user-specified string. For example, the mean value of column 2 data from two different files could be compared by

stats "file1.dat" using 2 name "A"
stats "file2.dat" using 2 name "B"
if (A_mean < B_mean) {...}

Instead of providing a string constant as the name, the keyword columnheader or function columnheader(N) can be used to generate the name from whatever string is found in that column in the first row of the data file:

do for [COL=5:8] { stats 'datafile' using COL name columnheader }