Appendix for "New features in gnuplot 5.4"

This is the appendix for "New features in gnuplot 5.4" by Lee Phillips.

The voxel plotting script

Here is the script that was used to create the voxel plot of the dipole field. The line numbers are not part of the script, but are there to facilitate the explanation. Here we have space only for brief explanations of the commands and settings used. Please refer to our more detailed followup article for a more expansive introduction to voxel plotting in gnuplot.

    (1) set cbrange [-3:3]
    (2) set vgrid $v size 25
    (3) set vxrange [0:1]; set vyrange [0:1]; set vzrange [0:1]
    (4) set urange [0:1]; set vrange [0:1]
    (5) set xrange [0:1]; set yrange [0:1]; set zrange [0:1]
    (6) $charges << EOD
    (7) 0 0 0.75 1
    (8) 0 0 0.25 -1
    (9) EOD
    (10) pot(r) = r > 0 ? -1/r : 0
    (11) vfill $charges using 1:2:3:(2):($4 * pot(VoxelDistance))
    (12) set xyplane at -0.1; set border 4095; unset key
    (13) splot $v with points above -100 pointtype 7 pointsize 0.4 linecolor pal

(1) The cbrange is the range of values mapped to the color palette; it can be set to emphasize the details of interest.

(2) The vgrid, which must have a name beginning with a "$", is initialized here; it will have dimensions 25 × 25 × 25.

(3-5) In addition to the usual xrange (and friends) for setting the ranges of the axes, the vxrange, etc., settings establish the extents of the voxel grid. Here we set those ranges to

(6-9) This establishes a data block containing two lines. Each line holds the x, y, and z coordinates and charge of one of the charges.

(10) The function for the potential field in a vacuum a distance r away from a charge. Since it diverges at r = 0, we use ternary notation to handle the value there.

(11) The new vfill command uses the $charges as a source to supply the voxel grid with values. How this is done is specified in the using clause. The first three colon-separated numbers tell gnuplot what to use for the x, y, and z coordinates; in this case, we want to take the first three columns without change. The next field, "(2)", uses parentheses to tell gnuplot that this is a mathematical expression, in this case simply the number 2. This field is for the radius over which each point of the source will influence the voxel grid. The value 2 is large enough to cover our entire plot, which is what we want in this case, because the potential field extends through all of space. If, for example, we were plotting the potential within some medium, rather than a vacuum, we might want to model it as having a "cutoff" at a particular radius, which we could enter here. The last field, the final expression in parentheses in line (11), is the expression for the value to add to each voxel. Here the $4 means to read a number from column 4 in $charges, which we used for the value of the charge. This is multiplied by our pot() function, using the convenience function supplied by gnuplot called VoxelDistance, which is the distance from each $charges point to the voxel; this saves us the trouble of calculating r from x and y.

(12) These settings merely affect the appearance of the plot, setting the location of the x-y coordinate plane, asking that a box be drawn around the plot, and turning off the legend.

(13) The splot command, originally meaning "surface plot", has been repurposed to do several things. Here it renders our voxel grid as an array of colored points for every place where the value is greater than -100, a number chosen to include everything. The pointtype is 7, which gives us closed circles, and the pointsize is set quite small to allow us to see around the points and inside the box. The final two words in this command, linecolor pal, say to color the points using the default palette.

Plotting a surface with pixmap labels

    set term pngcairo size 1920, 1440
    set out "planetary.png"
    set iso 50
    set samp 50
    set hidden3d
    set view 67, 74
    f(x,y) = exp(x/5.)*cos(y/3.)
    set pixmap 1 "earth.png" at 5, 5, f(5, 5) width screen 0.06
    set pixmap 2 "saturn.png" at -7, -9, f(-7, -9) width screen 0.06
    set pixmap 3 "jupiter.png" at 10, -10, f(10, -10) width screen 0.06
    set pixmap 4 "uranus.png" at 3, -6, f(3, -6) width screen 0.06
    set pixmap 5 "pluto-yesPluto.png" at -9, 0, f(-9, 0) width screen 0.06
    set pixmap 6 "mars.png" at -6, 6, f(-6, 6) width screen .06
    unset key
    set xlab "Variable 1" rot parallel font ",22"
    set ylab "Another planetary variable" rot parallel font ",22"
    set zlab "f(x, y)" rot parallel font ",22"
    set xtics font ",16"
    set ytics font ",16"
    set ztics font ",16"
    splot f(x, y)

3D box plot

The numbers in parentheses at the beginning of each line are not part of the script, but are there to make the explanation easier to follow.

    (1) set term pngcairo size 1920, 1440
    (2) set title "COVID-19 cases per million by country and date" font "Times,40"
    (3) set grid z dt '- -' lc 'black' lw 2
    (4) unset key; unset colorbox
    (5) set ytics ("Italy" 1, "U.S." 2, "Honduras" 3, "France" 4, "Canada" 5, "Switzerland" 6)\
    (6)     font ",24"
    (7) set xtics font ",24" offset 3
    (8) set ztics font ",24"
    (9) set xr [0.5:5.5]; set yr [0.5:6.5]; set zr [0:10000]
    (10) set cbrange [0.5:6]
    (11) set xlabel "\nYear 2020" rot parallel font ",24"
    (12) set xyplane 0
    (13) set boxwidth .3
    (14) set boxdepth .3
    (15) set pm3d depthorder base
    (16) set pm3d border linewidth 1.000
    (17) set view 60, 320
    (18) splot for [country = 1 : 6] 'covid.dat'\
              u ($0):(country):(column(country)):(country):xtic(7)\
	      with boxes lc pal

(3): Here we use a recent addition to gnuplot, the dashtype, which allows a visual definition of a dash pattern. This line produces the dashed gridlines that make it easier to read values off the graph;

(9): We set the ranges to leave a little margin. There are six countries and five times plotted;

(10): The cbrange is the range of values mapped to the default color palette. The country numbers go from 1 to 6, but we manipulated the range to skip the black part of the palette;

(12): The x-y plane should be at z = 0 for a box plot, usually;

(13-14): The cross-section of a bar;

(15): Bars are drawn under the hood using pm3d quadrangles, the same routines that make colored surfaces, so we can apply settings to this to control how they appear. This setting is necessary to make the bars occlude each other properly;

(18): The splot command reads the data and makes the plot. Here we loop over the six countries in the data file "covid.dat". The using clause contains five fields, separated by colons. The first, $0, is the row number in the file, which becomes the x-value; the second is the country index, which becomes the y-value; next comes the value in the country columns, used for the bar height; after that, the country index again, now used to set the color, so that each country will have its own color; and finally, the xtic command takes the string in the 7^th column, which is the date, and uses it for the tic label.