2.12.1.9 using

The most common datafile modifier is using.

Syntax:

      plot 'file' using {<entry> {:<entry> {:<entry> ...}}} {'format'}

If a format is specified, each datafile record is read using the C library's 'scanf' function, with the specified format string. Otherwise the record is read and broken into columns. By default the separation between columns is whitespace (spaces and/or tabs), but see `datafile separator`.

Each <entry> may be a simple column number that selects the value from one field of the input fit, an expression enclosed in parentheses, or empty.

If the entry is an expression in parentheses, then the function column(N) may be used to indicate the value in column N. That is, column(1) refers to the first item read, column(2) to the second, and so on. The special symbols $1, $2, ... are shorthand for column(1), column(2) ... The function `valid(N)` tests whether the value in the Nth column is a valid number.

In addition to the actual columns 1...N in the input data file, gnuplot presents data from several "pseudo-columns" that hold bookkeeping information. E.g. $0 or column(0) returns the sequence number of this data record within a dataset.

An empty <entry> will default to its order in the list of entries. For example, `using ::4` is interpreted as `using 1:2:4`.

If the using list has but a single entry, that <entry> will be used for y and the data point number (pseudo-column $0) is used for x; for example, "`plot 'file' using 1`" is identical to "`plot 'file' using 0:1`". If the using list has two entries, these will be used for x and y. See style and fit for details about plotting styles that make use of data from additional columns of input.

'scanf' accepts several numerical specifications but `gnuplot` requires all inputs to be double-precision floating-point variables, so "%lf" is essentially the only permissible specifier. A format string given by the user must contain at least one such input specifier, and no more than seven of them. 'scanf' expects to see white space—a blank, tab ("\t"), newline ("\n"), or formfeed ("\f")—between numbers; anything else in the input stream must be explicitly skipped.

Note that the use of "\t", "\n", or "\f" requires use of double-quotes rather than single-quotes.

— USING_EXAMPLES —

This creates a plot of the sum of the 2nd and 3rd data against the first: The format string specifies comma- rather than space-separated columns. The same result could be achieved by specifying `set datafile separator ","`.

      plot 'file' using 1:($2+$3) '%lf,%lf,%lf'

In this example the data are read from the file "MyData" using a more complicated format:

      plot 'MyData' using "%*lf%lf%*20[^\n]%lf"

The meaning of this format is:

      %*lf        ignore a number
      %lf         read a double-precision number (x by default)
      %*20[^\n]   ignore 20 non-newline characters
      %lf         read a double-precision number (y by default)

One trick is to use the ternary `?:` operator to filter data:

      plot 'file' using 1:($3>10 ? $2 : 1/0)

which plots the datum in column two against that in column one provided the datum in column three exceeds ten. `1/0` is undefined; `gnuplot` quietly ignores undefined points, so unsuitable points are suppressed. Or you can use the pre-defined variable NaN to achieve the same result.

In fact, you can use a constant expression for the column number, provided it doesn't start with an opening parenthesis; constructs like `using 0+(complicated expression)` can be used. The crucial point is that the expression is evaluated once if it doesn't start with a left parenthesis, or once for each data point read if it does.

If timeseries data are being used, the time can span multiple columns. The starting column should be specified. Note that the spaces within the time must be included when calculating starting columns for other data. E.g., if the first element on a line is a time with an embedded space, the y value should be specified as column three.

It should be noted that `plot 'file'`, `plot 'file' using 1:2`, and `plot 'file' using ($1):($2)` can be subtly different: 1) if file has some lines with one column and some with two, the first will invent x values when they are missing, the second will quietly ignore the lines with one column, and the third will store an undefined value for lines with one point (so that in a plot with lines, no line joins points across the bad point); 2) if a line contains text at the first column, the first will abort the plot on an error, but the second and third should quietly skip the garbage.

In fact, it is often possible to plot a file with lots of lines of garbage at the top simply by specifying

      plot 'file' using 1:2

However, if you want to leave text in your data files, it is safer to put the comment character (#) in the first column of the text lines. Feeble using demos.

If gnuplot is built with configuration option –enable-datastrings, then additional modifiers to using can specify handling of text fields in the datafile. See `datastrings`, `using xticlabels`, title.

— USING TITLE —

If gnuplot is built with configuration option –enable-datastrings, then the first entry of a column of the input data file can be used as a string to provide the plot title in the key box. The column containing specified is independent of the column[s] used for the plot itself.

   plot 'data' using 1:($2/$3) title column(N)

In this case the entry in the first row of column N will be used for the key entry of the plot constructed from dividing column 2 by column 3. The entry in the first row of columns 2 and 3 will be ignored.

— XTICLABELS —

If gnuplot is built with configuration option –enable-datastrings, then a column of the input data file can be used to label axis tic marks. The format of such a plot command is

  plot 'datafile' using <xcol>:<ycol>:xticlabels(<labelcol>) with <plotstyle>

Tic labels may be read for any of the plot axes: x x2 y y2 z. The `ticlabels(<labelcol>)` specifiers must come after all of the data coordinate specifiers in the using portion of the command. For each data point which has a valid set of X,Y[,Z] coordinates, the text field found in column <labelcol> is added to the list of xtic labels at the same X coordinate as the point it belongs to. `xticlabels(<labelcol>)` may be shortened to `xtic(<labelcol>)`.

Example:

      splot "data" using 2:4:6:xtic(1):ytic(3):ztic(6)

In this example the x and y axis tic labels are taken from different columns than the x and y coordinate values. The z axis tics, however, are generated from the z coordinate of the corresponding point.

— X2TICLABELS —

See `plot using xticlabels`.

— YTICLABELS —

See `plot using xticlabels`.

— Y2TICLABELS —

See `plot using xticlabels`.

— ZTICLABELS —

See `plot using xticlabels`.