Appendix C. Surface and contour plots

The plot command discussed in this book creates graphs that show how one variable (y) behaves as a function of another one (x). But what if you want to show how some quantity depends on two independent variables? In other words, how can you best visualize a single “output” variable as a function of two “input” variables? That’s basically the problem cartographers have: show a quantity (the elevation above sea level or the type of ground cover) as a function of two coordinates (the position on the surface). In gnuplot, you have essentially the same options cartographers have:

• Create a rendering of a raised surface. Cartographers call this a relief map; I’ll refer to it as a surface plot.
• Create a contour plot by looking straight down onto the coordinate plane and using contour lines (similar to the ones found on topographic maps) to indicate the elevation (or whatever the dependent variable represents).
• Use color to create a false-color plot (what is colloquially known as a heatmap).

Surface and contour plots are treated in this appendix; false-color plots are the topic of appendix D. Surface and contour plots are created using gnuplot’s splot command (short for “surface plot”). It’s a close relative of the familiar plot command; most of what you already know will carry over directly.

Neither surface nor contour plots deal very well with noise. This means it can be difficult to use either of them with real data—smooth functions are easier, and that’s why most of the examples in this appendix show functions only. We turn to data later in this appendix and discuss the different file formats available. (Also keep in mind that false-color plots may be a better approach for noisy data altogether.)

C.1. Surface plots

Surface plots (and contour plots) are created using the splot command. Its syntax is very similar to the syntax for the plot command. The differences are largely due to the need to handle one additional dimension, which I’ll refer to as the z direction.

Here’s an example of the splot command in action (also see figure C.1—if your plot doesn’t look anything like figure C.1, keep reading; I’ll tell you about the options you need to adjust manually to get a satisfactory result shortly):

splot [-2:2][-2:2]
    exp(-(x**2 + y**2))*cos(x/4)*sin(y)*cos(2*(x**2+y**2))

Figure C.1. Creating three-dimensional plots using the splot command: splot [-2:2][-2:2] exp(-(x**2 + y**2))*cos(x/4)*sin(y)*cos(2*(x**2+y**2))

You can see how the function must depend on two variables, x and y. Corresponding to the two variables, there are two brackets to limit the plot range. A third bracket can be added to restrict the plot range in the new, “vertical” z direction.

C.1.1. The splot command

Most of the additional options applicable to the plot command are available for the splot command as well. You can also plot data from a file (see section C.4 later in this appendix) and use many of the directives familiar from plot:

• The title option is available to place a descriptive string into the key.
• The using directive now requires three arguments to pick out the columns used for the x, y, and z directions, respectively.
• Similarly, you have to add a third bracket if you want to restrict the z range: splot [xmin:xmax][ymin:ymax][zmin:zmax] ....
• Plotting styles are selected in the usual form through the with option. Not all the styles described in chapter 6 are available with splot. Only points, lines, linespoints, and impulses can be used with splot; in particular, this means none of the styles drawing error bars are available.

Although we don’t show an example here, nothing prevents you from plotting several functions (or data sets) simultaneously using splot: for example, splot f(x,y), g(x,y).

In addition to using, you can use index and every to plot only parts of a file. The smooth directive (see chapter 3) isn’t available for splot, but you can apply data transformations as part of the using directive, as discussed in section 3.3. Furthermore, the dgrid3d option provides a way to calculate and plot a smooth approximation to a noisy data set when using splot (see section C.5).

Style, decorations, and axes when using splot

Global options can be used with splot in the same way as with plot. Both set style function and set style data have the desired effect. In addition to the familiar xrange and yrange options (see section 8.2), there’s a zrange option to control the plot range globally.

Arrows and labels (but not objects) can be placed onto a three-dimensional graph without problems. Just remember to provide a third value to each coordinate for the z value (for example, set label "text" at -2,-3,1).

In contrast to plot, graphs generated with splot can have only a single coordinate system. Therefore, all the options used to control the secondary coordinate system (see section 8.1) have no meaning for graphs generated with splot. Also, the axes directive can’t be used with splot. We’ll study tic marks and axes in more detail later, when we discuss ways to choose the viewpoint for a graph created with splot in section C.2.

C.1.2. Special options for surface plots

There are three options specific to the appearance of a surface plot: set surface, set hidden3d, and set isosamples.

The set surface option

The set surface option turns rendering of the surface on or off. For surface plots, this is of course not useful; but the splot command is also used to generate contour and false-color plots, where an explicitly drawn surface is not desired.

By default, the surface is shown, but it can be switched off using the following command:

unset surface

Switch the surface back on using set surface.

The set hidden3d option

In figure C.1, the surface is opaque : parts closer to the observer obscure parts of the surface further back. By default, this effect is off, and only a transparent wire mesh of the surface is drawn. Figure C.2 demonstrates what a plot looks like if no opaque surface is drawn.

Figure C.2. The same plot as in figure C.1, but without the opaque surface effect. Use set hidden3d to enable the drawing of an opaque, nontransparent surface.

To switch to an opaque surface rendering, use the set hidden3d option. You’ll probably want to make opaque surfaces the default—for example, by including the following line in your gnuplot startup file (see section 12.5):

set hidden3d

The hidden3d option can take a number of optional arguments. The most important of these are offset and trianglepattern:^[1]

¹

There are a few further options to hidden3d, most of which deal with certain edge cases that may arise when making a surface plot containing undefined points or points outside of the z range. Check the standard gnuplot reference documentation if this is relevant to you.

set hidden3d [ [no]offset {int:offset} ] [ trianglepattern {int:mask} ]

You can use the offset keyword to control the color and line type that are used for the bottom side of the surface. As you know, gnuplot will cycle through all available plot styles for each new data set (see section 9.3). Through the integer argument to offset, you can control how far the internal style counter should be advanced from the style used for the top side of the surface. By default, gnuplot chooses the next available style. An argument of zero (set hidden3d offset 0) draws both sides of the surface in the same style. The same effect is achieved through the nooffset keyword.

Using the trianglepattern keyword, you can control which lines are drawn to connect neighboring grid points. The argument to trianglepattern is an integer, which is interpreted as a bitmask (see table C.1).

Table C.1. Values used in the mask to the set hidden3d option

Bit position	Value	Description
0	1	Lines parallel to the x axis
1	2	Lines parallel to the y axis
2	4	Diagonal lines, from southwest to northeast

You can select any combination of bits. The default is 3, so that the surface is made up of rectangular surface elements. When you use a value of 7, diagonal lines are also drawn, so that the surface appears to be made out of triangles. Figure C.3 compares different settings of this option.

Figure C.3. Comparing different values of isosamples and hidden3d trianglepattern. Except for the values of those two options, these graphs are identical to figure C.1.

Sampling frequency for plotting functions with splot

In section 3.1, you learned to use the set samples option to control the number of points where gnuplot evaluates a function (of a single variable) in order to plot it. When plotting a function of two variables using splot, things are a bit more complicated.

If hidden3d is on, so that the surface is opaque, then set isosamples controls the number of evaluation points, and these points are connected with straight lines to form the surface. If hidden3d is off, so that the surface is transparent, then set isosamples still controls the number of grid points, but set samples controls the number of evaluation points for each line in the grid.

The set isosamples command takes one or two integer values, which specify the number of grid points in the x and y direction, respectively. If only a single value is provided, it’s used for both directions:

set isosamples {int:xlines} [, {int:ylines} ]

By default, functions are evaluated on a 10×10 grid, which is too coarse to give a good, smooth appearance of the plotted curve. I find values of around 30 to be ideal—using an even finer grid brings little additional smoothness but leads to grid lines overlapping each other unfavorably. You probably want to include the following line in your gnuplot startup file:

set isosamples 30

Figure C.4 shows the same function plotted in figure C.1, but now plotted with the default setting of set isosamples 10.

Figure C.4. The isosamples option controls the number of nodes used to draw the surface. Here, we use the default value of set isosamples 10, whereas in figure C.1, we used a much finer grid of set isosamples 30.

Tip

Gnuplot’s default value of 10 for the set isosamples option is much too small to give attractive graphs. Choosing a moderately higher number (such as 30) will lead to much better results.

Special rules apply to the pseudofile ++ (see section 4.5). In this case, the number of grid points used for drawing the surface is controlled by set samples for the x direction and by set isosamples for the y direction. To obtain behavior from the pseudofile ++ that is equivalent to a regular function plot, you need to assign the same value to set samples and set isosamples, as in the following example:

f(x,y) = exp(-(x**2 + y**2))*cos(x/4)*sin(y)*cos(2*(x**2+y**2))
set samples 30
set isosamples 30
splot [-2:2][-2:2] "++" u 1:2:(f($1, $2)) w l

Finally, let me remind you that set samples and set isosamples are only relevant when plotting functions and have no effect when plotting data from a file.

C.2. View point and coordinate axes

With three-dimensional plots, there’s a new problem that doesn’t exist with regular, two-dimensional plots: they can be viewed from different positions and under different angles. You must therefore choose a view point. Closely related is the issue of coordinate axes: you need to provide a clear frame of reference so that the viewer can understand from which position the graph is seen. And finally, you have to provide a scale and tic marks if you want to convey quantitative information. Let’s look at all of that.

C.2.1. Borders and base plane

A regular (two-dimensional) plot has four borders that you can modify using the set border option, as you’ve seen in section 9.5.2. For a surface plot, you can imagine the entire surface embedded in a cube. You can use the set border option to switch each individual edge of this cube on or off.

Borders

The set border command takes an integer argument, which is interpreted as a 12-bit bitmask; each bit turns one of the edges on or off. Table C.2 shows the bit positions for each edge of the surrounding cube.

Table C.2. The values of the mask used in the set border option. The red lines are the ones switched on by the corresponding bit in the mask.

The default value is 31 when you use splot, turning on the four sides of the base and the leftmost vertical axis. (No matter what’s specified in the set border option, borders other than the base are drawn only if set surface is true.)

You can place labels along the borders of the plot in the usual fashion using set xlabel, set ylabel, and (only for splot) set zlabel. In all graphs in this appendix, I’ve made sure to use explicit labels on both the x and the y axes.

Tip

There is no “obvious” view point for surface plots; it often makes sense to choose a different view point for each function or data set. Because of this, it is essential that you tell the reader which axis is which by using explicit labels on all axes.

Tic marks are drawn independently of the borders—see chapter 8 for all the options available to control the drawing and placement of tics. Just keep in mind that the secondary coordinate system (x2tics and so on) isn’t available; instead, there’s an additional set of options to control the appearance of tic marks in the z direction (ztics and so forth).

The base plane

By default, the plotted surface is elevated a certain distance above the base plan of the surrounding box. You can control this elevation through the xyplane option:

set xyplane [ at {flt:zvalue} | {flt:frac} ]

There are two ways you can use set xyplane to fix the position of the base relative to the plot surface. You can specify an explicit z value at which the base plan should be drawn, using the keyword at together with xyplane:

set xyplane at 0.1

This is the easiest way to fix the location of the base plane if you use an explicit plot range in the vertical direction.

If the z range is dynamically chosen, it doesn’t make sense to specify a fixed location for the base plane; instead, its position should be chosen as a fraction of the total apparent height of the figure. This is precisely what set xyplane without the at keyword does: it allows you to control the elevation of the plot surface above the base plane as a fraction of the total z range.

A few examples may help to clarify. The command

set xyplane 0

puts the base plane right at the low end of the z range. Choosing

set xyplane 0.5

elevates the plotted surface by half the total z range (or half the apparent height of the plot) above the base plane. Using negative arguments to set xyplane lifts the base plane so that it intersects with the plot surface. For example, the command

set xyplane -0.5

places the base plane at the middle of the z range.

The following formula can be used to convert between the two models. It tells you the z value at which the base plane will be drawn, given the fractional parameter f and the z range [zmin:zmax]:

z = zmin - f * ( zmin - zmax )

C.2.2. View point

When creating surface plots using splot, you can control one aspect of the graph that has no equivalent in two-dimensional plots: the view point—that is, the location (relative to the graph) from which the observer appears to be regarding the plotted surface. You can set the view point in two ways: either programmatically with the set view option, or interactively using the mouse.

Using the mouse

The more convenient way to adjust the viewing angle is of course using the mouse! Grab the plotted surface (by left-clicking into the plot window), and drag it to its desired position. This requires a reasonably fast computer (and works much better if the surfaces are opaque—when hidden3d is true). When you hold down the Ctrl key while dragging with the mouse, only the box surrounding the graph is shown: this may facilitate this process on slow computers or for surfaces containing many points.

Holding down the middle mouse button and moving the mouse zooms the graph: moving the mouse left to right increases the size of the entire graph (and vice versa). Moving the mouse upward stretches the graph in the z direction only; moving the mouse downward shrinks the graph in the z direction. Again, you can suppress rendering of the actual plot surface when dragging by holding down the Ctrl key while moving the mouse. Finally, holding down the Shift key together with the middle mouse button lets you move the base plane of the plot (this is equivalent to set xyplane).

Using set view

The set view command gives you exactly the same capabilities, but in a non-interactive fashion. The set view option takes up to four optional arguments:

set view [{flt:theta} [, {flt:phi} [, {flt:scale} [, {flt:z_scale}]]]]

The first two arguments are the angles (in degrees) of the view point around the horizontal and the vertical axes, respectively. (In spherical coordinates, these are the polar and azimuthal angles.) The angles are restricted to values from 0 to 360. (See figure C.5.) Figure C.6 demonstrates how a graph can appear from different view points.

Figure C.5. The angles used when setting the view point with set view

Figure C.6. Different view points. Compare to figure C.1, where the same function is shown with set view 45,50.

The third and fourth parameters correspond to the zooming effect I’ve already mentioned in the context of mouse interactions. Both default to 1.0: choosing smaller scale factors results in a smaller graph on the canvas. (In particular, the scale factor is the inverse of the radial component in spherical coordinates.)

Unit length and aspect ratio

You can also use set view to fix the length of the x and y axis units. (The set view command therefore does for splot what set size does for plot—see section 9.5.1.)

The command set view equal xy creates a graph within which the (visual) length of one x axis unit equals the length of one y axis unit. The graph is scaled so that it’s guaranteed to fit on the canvas.

The command set view equal xyz also sets the z axis unit to the same visual length, but in this case, there is no guarantee that the graph will fit on the canvas! The command set view noequal removes the constraint between the axis units.

Bird’s-eye view

The special command set view map places the observer right above the plotted surface so they perceive just the base plane of the plot as a regular, two-dimensional plot. This is the proper view for contour plots (see section C.3) and for false-color plots (see appendix D).

But set view map is not just a convenient shorthand for set view 0, 180, 1.425, 1. It also enables set size for splot. In particular, you can use set size square and set size ratio -1 to influence the appearance of contour plots and heatmaps.

It’s possible to append the keyword scale together with a numerical factor to scale the resulting graph on the canvas. The following code snippet turns on map view and also shrinks the graph to half its default size:

set view map scale 0.5

C.3. Contour lines and contour plots

You can add contour lines to a plot generated using splot. Contour lines can be a great help when it comes to associating specific z values with surface plots. They can also be used by themselves to make contour plots.

Use the set contour option to enable contour lines:

set contour [ base | surface | both ]

By default, contour lines are only plotted on the bottom of the box surrounding the surface plot. But contours can also be drawn on either the plot surface or on both (base and surface), through the use of the appropriate options to set contour (as in figure C.7).

Figure C.7. Adding contour lines at the base and on the surface using set contour both and set cntrparam levels incremental -0.3,0.1,0.4. The function is the same as in figure C.1.

C.3.1. Contour plots

Contour lines are almost more useful by themselves than in combination with surface plots: a contour plot shows only the contour lines, from the bird’s-eye perspective. Figure C.8 is yet another representation of the function from figure C.1—this time as a contour plot. Listing C.1 summarizes the commands necessary to go from a three-dimensional surface plot to a flat contour plot.

Figure C.8. The function from figure C.1, plotted in contour view. See listing C.1 for the commands.

The quality of the resulting plot depends strongly on the choices for set isosamples and set samples. The former controls the number of nodes at which the function is evaluated, and the latter controls the number of line segments used to draw the contours. Higher resolution is obviously better, but it requires more computational power. (Values from 30 to 300 for either seem to work well in practice.)

Listing C.1. Commands to switch to a contour view—see figure C.8

C.3.2. Customizing contour lines and their labels

As you can see in figure C.8, gnuplot assigns a new line type from the predefined sequence of types to each new contour (see section 9.3). To customize the assignment of colors to contours, you need to redefine the appropriate style using set linetype. It’s also possible to use only a single line type for all contours, using the command set cntrlabel onecolor.

A word of warning: gnuplot’s commands for customizing contour plots aren’t very polished. Most actions are achieved through two commands—set cntrparam and set cntrlabel—but each is responsible for several, only vaguely related tasks, distinguished by various suboptions. Also, and in contrast to usual gnuplot usage, these commands don’t allow you to combine multiple suboptions into a single invocation.

Frequency and spacing of contours

To influence the frequency and spacing of contour lines, use set cntrparam levels. The different ways to do this are reminiscent of the options used to place tic marks along the axes (see section 8.3.4):

set cntrparam levels [ auto [{int:n}]
                       | discrete {flt:z0} [, {flt:z1} [, ...]]
                       | incremental
                            {flt:start}, {flt:inc} [, {flt:end}] ]

When using auto, approximately five uniformly spaced contour lines are drawn. You can pass an integer argument to auto to change the number of contour lines that are generated. All these settings are approximate, because gnuplot attempts to place contour lines at round numbers.

Using discrete, you can control exactly where contour lines are placed. The discrete suboption takes a comma-separated list of z values as an argument, at which contours should be drawn. All z values for which contours should be shown must be specified in a single call to set cntrparam levels discrete; you can’t add individual contour lines to autogenerated ones. Finally, you can fix a starting z value and an increment (and optionally an end value) through the incremental keyword.

Contour labels

By default, gnuplot automatically generates an entry in the key (see section 7.4) for each contour line. The formatting of these labels can be customized using set cntrlabel format. The format string can contain any of the familiar conversion specifiers (see section 8.3.3):

set cntrlabel [format "str:format"] [font "str:font"]

It’s also possible to place the labels directly onto the graph, rather than grouping them into a separate key, but (at the time of this writing) support for this feature is still rudimentary. To place labels onto the graph, use the with labels style together with the splot command. This will draw only the labels; if you want both contours and labels, you need to plot the function of data twice in the same command: once with lines and once with labels.

Two parameters control the number and placement of labels that are drawn for each contour line: set samples and set cntrlabel. By default, a label is placed at every 20th line segment—hence a larger value of set samples means more labels. You can modify the number and position of labels using

set cntrlabel [start {int:segment}] [interval {int:segment}]

Using the interval keyword, you can change the frequency of labels: a higher number means more line segments are drawn between consecutive labels. Unfortunately, values higher than 100 are silently truncated to 100. The argument to the start keyword determines at which line segment (starting from some arbitrary origin) the first label is drawn. Changing this value, you can slide all labels in the graph along their contours.

It’s currently not possible to shift or rotate labels. Feel free to experiment, but you may be better off using explicit labels (using set label; see section 7.3.3) to annotate a contour plot on the graph.

Smoothing contour lines

The set cntrparam command can also control how contours are generated—this may be useful at times, for example if you want to graph noisy data. The relevant sub-options are as follows:

set cntrparam [ linear | cubicspline | bspline ]

set cntrparam [ points {int:q} ]
set cntrparam [ order {int:q} ]

To draw contours, gnuplot determines a set of points (called nodes) at which the function (or data) has the same z value. Through the first set of keywords, you can choose how these points are connected: linear (the default) uses straight lines; cubicspline uses a smooth curve, which is guaranteed to pass exactly through the nodes; and bspline uses a curve that’s guaranteed smooth but isn’t guaranteed to pass through the nodes exactly. For “crumply” surfaces, or low resolutions (that is, few grid points), one of the spline options may give significantly better results than the default.

You can specify two additional parameters that are relevant to the way splines are drawn (they have no meaning for linear mode). The points option controls the number of points for which the interpolation between any two neighboring nodes is evaluated when drawing the contour. More points again mean smoother curves. With order, you can set the order of the spline to be used (this option is only relevant for bspline). The order must be an integer between 2 and 10. The greater the order, the smoother the contour. Note that both points and order require separate calls to set cntrparam—they can’t be combined with the type of curve (linear, cubicspline, or bspline) in the same call.

C.4. Plotting data from a file using splot

Everything we’ve done so far has involved the plotting of functions only. Can gnuplot use data from a file to generate surface and contour plots? Of course it can!

Gnuplot supports two data file formats to work with splot. For data files in other formats, or for data that’s not on a grid, check the dgrid3d option described in section C.5.

C.4.1. Grid format

If the data file is in grid format, each line must contain both x and y coordinates, as well as the z value that is to be plotted. Data must be organized into data blocks, which are separated from each other by a single blank line. Each block must contain all data points for a single row of data points, parallel to the x axis (in other words, within each data block, the x coordinate stays constant, but the y coordinate runs). The following listing shows a short example file demonstrating this format. The corresponding plot is in figure C.9.

Figure C.9. The data from listing C.2 plotted using splot "grid" u 1:2:3 w linesp

Listing C.2. Simple data file suitable for splot—see figure C.9 (file: grid)

# x     y     z
  0    -1    10
  0     0    10
  0     1    10

  1    -1    10
  1     0     5
  1     1    10

  2    -1    10
  2     0     1
  2     1    10

  3    -1    10
  3     0     0
  3     1    10

Keep in mind one very important restriction: all data blocks must contain the same number of data points. If the number of data points isn’t the same in all data blocks, or if even a single data point is missing or invalid, splot can’t draw a surface.

This is a formal requirement, only: there’s no constraint that the data values (that is, the x and y coordinates) form a regular grid. Small deviations of the x and y positions from regularity are fine, but the plot may look strange or may not be very useful if the underlying grid is too distorted.

As mentioned when we first introduced the splot command earlier in this appendix, many of the directives familiar from the plot command are available when plotting gridded data using splot. In particular, you can have different data sets in a single file, separated from each other by double blank lines (as discussed in chapter 3). You can then select a specific such set using index. The every directive can be used to pick out subsets of each data set. Finally, the using directive can be used to choose the data columns for x, y, and z values and to apply data transformations in the usual fashion (see section 3.3).

Missing data

It’s instructive to see what gnuplot does with a defective file that doesn’t follow this format. Figure C.10 shows the results of the splot command for a file that’s the same as in listing C.2, except that the last entry (the point at (3,1,10)) has either been replaced with the not-a-number marker NaN or been omitted entirely.

Figure C.10. The splot command requires all data points to be supplied on a regular grid, with none missing. This figure shows what happens when the last point (at x=3, y=1) has been replaced with a not-a-number marker or omitted entirely. See listing C.2 for the original data file. The splot command is the same as in figure C.9.

If gnuplot finds a not-a-number marker (as defined by set datafile missing—see section 4.3.4), it can still draw a complete surface, just omitting the panels that touch the invalid data point. But if the data point is missing entirely, then no surface can be drawn. Instead, the splot command connects all points in one data block consecutively, but doesn’t connect data points separated (in the file) by a single blank line—this is exactly what the plot command does when it encounters single blank lines in a file. But in addition, splot staggers the plots for successive data blocks (front to back) and thus gives the illusion of optical depth. But cross lines (parallel to the x axis) are only drawn when the data in the input file fulfills the requirements of regular, gridded data blocks, as discussed earlier.

C.4.2. Matrix format

The matrix format is an alternative file format for data on a regular, rectangular grid. It’s more compact, because it doesn’t store the (redundant) information on x and y coordinates for every data point—only the z values at the grid locations are kept. There are two permissible matrix formats: one that stores the coordinates of the grid points (without duplication) together with the z value, and a super-compact format that does away with the grid coordinates altogether.

Table C.3 shows the general structure of both formats. In the general matrix format, the first row contains the x coordinates of the grid points, and the first column contains the y coordinates. The entry in the top-left corner is ignored but must contain a numeric value. In the compact format, the coordinates aren’t stored explicitly. Instead, when reading a file in the compact format, gnuplot assumes that the coordinate values consist of pairs of positive integers, starting at (0, 0).

Table C.3. The matrix formats

	General: nonuniform matrix	Compact: matrix
Structure	NA x0 x1 x2 x3 ... y0 z00 z01 z02 z03 y1 z10 z11 z12 z13 y2 z20 z21 z22 z23 y3 z30 z31 z32 z33 ... ...	z00 z01 z02 z03 ... z10 z11 z12 z13 z20 z21 z22 z23 z30 z31 z32 z33 ... ...
Example	0 0 1 2 3 -1 10 10 10 10 0 10 5 1 0 1 10 10 10 10	10 10 10 10 10 5 1 0 10 10 10 10

Upon reading a file in matrix format, gnuplot internally transforms the contained information into a three-column grid format, with the x coordinates in the first column, the y coordinates in the second, and the data values in the third. These columns can then be selected in a regular using specifier.

Tip

Keep in mind that a file in matrix format is internally transformed into the equivalent grid format. Construct a using specifier as you would for a file in grid format.

A worked example

Let’s say that the two example files in table C.3 are called matrix and packedmatrix, respectively. Then the following three commands are equivalent:

The only difference is the appearance of the new keywords matrix (indicating a file in packed matrix format) and nonuniform matrix (for a file in general matrix format: that is, including coordinate information in the first row and column).

A special consideration applies to files in the packed matrix format, because the integer pairs that gnuplot supplies instead of coordinate values must be transformed into true locations. As long as the grid points lie on a regular, rectangular grid, this can always be accomplished through a simple linear transformation, involving the coordinate value of the origin and the lattice spacing, as shown in the listing.

C.5. Smooth surfaces

Surface plots can be fun, but things can go wrong in practice—in particular, when you’re graphing data (as opposed to plotting smooth functions):

• Data is scattered (not on a regular grid), so that no regular surface can be drawn.
• Data is sparse, so that the surface consists only of a few elements and is therefore not easy to recognize.
• Data is noisy, so that the surface appears overly bumpy.
• The data file isn’t in a suitable format.

C.5.1. The set dgrid3d facility

Gnuplot provides a slick little facility that takes arbitrary input data and generates a smooth interpolation onto a two-dimensional grid: the dgrid3d option. If dgrid3d is on, splot doesn’t plot the raw data. Instead, it reads the data and then generates an approximation to this data for every point of a regular grid. The number of grid points and some aspects of the interpolation algorithm can be controlled through set dgrid3d:

set dgrid3d [ {int:nx} [, {int:ny} [, {int:q} ] ] ]

set dgrid3d [ {int:nx} [, {int:ny} ] ]
            [ splines
              | gauss | cauchy | exp | box | hann
                  [ {flt:dx} [, {flt:dy} ] ] ]

By default, dgrid3d is disabled. When it’s enabled, three-dimensional data read from a file is always treated as a scattered data set. A grid with dimensions derived from a bounding box of the scattered data and size as specified by the nx and ny parameters is created for plotting and contouring. The grid is equally spaced in x rows and in y columns; the z values are computed as weighted averages or spline interpolations of the scattered points’ z values. In other words, a regularly spaced grid is created, and a smooth approximation to the raw data is evaluated for all grid points. Only this approximation is plotted, but not the raw data. The number of columns defaults to the number of rows, which defaults to 10.

Several algorithms are available to calculate the approximation from the raw data. Some of these algorithms can take additional parameters. All the algorithms have in common that the closer a data point is to a grid point, the more effect it has on that grid location.

The splines algorithm calculates an interpolation based on thin plate splines. It doesn’t take additional parameters, which is convenient but also means the algorithm can’t be adapted to take the nature of the data into account.

An alternative and more flexible algorithm is based on weighted averages.^[2] Each data point is replaced with a kernel: a smooth function that’s peaked at the location of the data point. The contributions from all kernels are combined to find the weighted average for the plot:

²

The dgrid3d facility allows for some other options as well. Check the standard gnuplot reference documentation for details.

Here, z_i is the value of the ith data point, and d_i is the Euclidean distance between the current grid point and the location of the ith data point. The function w(d) is the smoothing kernel. Several kernels can be selected by supplying the appropriate keyword to set dgrid3d. Table C.4 lists the available choices.

Table C.4. Smoothing kernels available with set dgrid3d

Keyword	Definition
gauss	w(d) = exp(-d2)
cauchy	w(d) = 1/(1+d2)
exp	w(d) = exp(-d)
box	w(d) = 1 if |d| < 1; w(d) = 0 otherwise
hann	w(d) = ½·(1-cos(2Πd)) if |d| < 1; w(d) = 0 otherwise

When using one of the five smoothing kernels from table C.4, up to two additional parameters can be specified: dx and dy. These are used to rescale the coordinate differences when calculating the Euclidean distance:

The value of dy defaults to the value of dx, which defaults to 1. The parameters dx and dy make it possible to control the radius over which data points contribute to a grid point in the units of the data.

Figure C.11 shows the data from listing C.2 plotted when smoothed using dgrid3d with the Gaussian kernel. (The Gaussian kernel is probably the most generally useful and versatile kernel—unless you have specific reasons to use a different one, it’ll serve you well in a variety of situations.)

Figure C.11. The same data as in figure C.9, but plotted after turning on smoothing using set dgrid3d 30,30 gauss 0.6,0.6

The set dgrid3d facility isn’t perfect. In particular, it can’t be turned on and off for individual data sets—either all data sets are smoothed with it, or none. This makes it impossible, for instance, to plot the raw data together with the smooth surface. But overall, dgrid3d is a great tool to generate good-looking two-dimensional graphs from otherwise unsuitable data.