#### 3.27.1.1 matrix

Gnuplot can interpret matrix input in two different ways. The first of these assumes a uniform grid of x and y coordinates, and assigns each value in the input matrix to one element of this uniform grid. This is the default for ascii data input, but not for binary input. Example commands for plotting uniform matrix data:

         splot 'file' matrix using 1:2:3          # ascii input
         splot 'file' binary general using 1:2:3  # binary input

In a uniform grid matrix the z-values are read in a row at a time, i. e.,

        z11 z12 z13 z14 ...
        z21 z22 z23 z24 ...
        z31 z32 z33 z34 ...

and so forth.

For ascii input, a blank line or comment line ends the matrix, and starts a new surface mesh. You can select among the meshes inside a file by the index option to the ‘splot‘ command, as usual.

The second interpretation assumes a non-uniform grid with explicit x and y coordinates. The first row of input data contains the y coordinates; the first column of input data contains the x coordinates. For binary input data, the first element of the first row must contain the number of data columns. (This number is ignored for ascii input). Both the coordinates and the data values in a binary input are treated as single precision floats. Example commands for plotting non-uniform matrix data:

         splot 'file' nonuniform matrix using 1:2:3  # ascii input
         splot 'file' binary matrix using 1:2:3      # binary input

Thus the data organization for non-uniform matrix input is

          <N+1>  <y0>   <y1>   <y2>  ...  <yN>
           <x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
           <x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
            :      :      :      :   ...    :

which is then converted into triplets:

          <x0> <y0> <z0,0>
          <x0> <y1> <z0,1>
          <x0> <y2> <z0,2>
           :    :     :
          <x0> <yN> <z0,N>

          <x1> <y0> <z1,0>
          <x1> <y1> <z1,1>
           :    :     :

These triplets are then converted into ‘gnuplot‘ iso-curves and then ‘gnuplot‘ proceeds in the usual manner to do the rest of the plotting.

A collection of matrix and vector manipulation routines (in C) is provided in ‘binary.c‘. The routine to write binary data is

          int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)

An example of using these routines is provided in the file ‘bf_test.c‘, which generates binary files for the demo file ‘demo/binary.dem‘.

Usage in ‘plot‘:

        plot `a.dat` matrix
        plot `a.dat` matrix using 1:3
        plot 'a.gpbin' {matrix} binary using 1:3

will plot rows of the matrix, while using 2:3 will plot matrix columns, and using 1:2 the point coordinates (rather useless). Applying the every option you can specify explicit rows and columns.

Example – rescale axes of a matrix in an ascii file:

        splot `a.dat` matrix using (1+$1):(1+$2*10):3

Example – plot the 3rd row of a matrix in an ascii file:

        plot 'a.dat' matrix using 1:3 every 1:999:1:2

(rows are enumerated from 0, thus 2 instead of 3).

Gnuplot can read matrix binary files by use of the option binary appearing without keyword qualifications unique to general binary, i.e., array, record, ‘format‘, or filetype. Other general binary keywords for translation should also apply to matrix binary. (See general for more details.)