Org-babel-gnuplot

Unfortunately, there seems to be an issue with getting gnuplot-mode working properly with Org-mode on Windows machines. Attempts to use Babel for gnuplot code blocks or the org-plot method both seem to fail. Discussion is taking place on how to resolve this issue.⁴ As of Aug/Sept 2010, Bruce Ravel, the creator of gnuplot-mode, has indicated willingness to work with a mailing list member to identify the potential source of the issue.

Set the title for the whole graph like this:

set title "This Title Goes at the Top"

Set axis labels like so:

set xlabel "This is the X Axis"
set ylabel "This is the Y Axis"

The size ratio of the graph is controlled like so:

• Wider/shorter: set size ratio 0.5 (any number less than 1)
• Taller/thinner: set size ratio 2 (any number greater than 1)
• Square (1:1): set size square

Tic marks are set with the method "start,increment[,end]." Start is the beginning tic value, increment sets how far apart the tics are, the the optional end specifies a stopping value. If no end is given, the tics will carrry on by the increment value until the max x/y value is reached. Here are some examples:

set xtics 0,10,100  %% tics every 10 from 0 -> 100
set ytics -10,50    %% tics every 50 from -10 onward

Named tics can also be used. Two values are provided, a numerical value (where on the given axis the tic should be placed) and a name in quotes to indicate what word should be placed at the tic instead of the numerical value. This method allows for words instead of numbers to be used (which has many uses) as well as for complete control over tic mark placement.

set xtics ("Tic 1" -1, "Tic 2" 10, "Tic 3" 1001)

The gnuplot default is for tics to show up on both sides and the top and bottom of the graph. In other words, the tics on the left y-axis and bottom x-axis are "mirrored" to the opposing side of the plot borders. Stop this (tics only on left/bottom) by using:

set xtics nomirror
set ytics nomirror

You can rotate tic marks for increased readability by specifying an angle at which to rotate their labels. Here is the syntax (substitute any angle value for -45):

set xtics rotate by -45
set ytics rotate by -45

The heart of gnuplot is the plot command. It is broken down into several sections:

A full babel block of code for a few functions might look like this:

#+begin_src gnuplot :exports code :file file.png
reset

set title "Putting it All Together"

set xlabel "X"
set xrange [-8:8]
set xtics -8,2,8


set ylabel "Y"
set yrange [-20:70]
set ytics -20,10,70

f(x) = x**2
g(x) = x**3
h(x) = 10*sqrt(abs(x))

plot f(x) w lp lw 1, g(x) w p lw 2, h(x) w l lw 3
#+end_src

Plotting data points from a table could look like this:²

#+begin_src gnuplot :var data=basic-plot :exports code :file file.png
set title "Putting it All Together"

set xlabel "X"
set xrange [0:1]
set xtics 0,0.1,1


set ylabel "Y"
set yrange [0.2:0.5]
set ytics 0.2,0.05,0.5


plot data u 1:2 w p lw 2 title 'x vs. y1', \
     data u 1:3 w lp lw 1 title 'x vx. y2'
#+end_src

Sometimes it's desireable to have text as the x-values/xtics instead of numbers.⁸ Gnuplot will plot a column of text entries as the x-values for its points by spacing the named values evenly along the axis. Here's an example of a running distance log:⁹

#+begin_src gnuplot :var data=xtics :exports code :file file.png
  reset

  set title "Running Stats"

  set xlabel "Date"
  set xtics rotate by -45

  set yrange [1:5]
  set ylabel "Distance (mi)"

  plot data u 2:xticlabels(1) w lp lw 2 notitle
#+end_src

The 2:xticlabels(1) tells gnuplot to use the values in column 1 for the xtic names and to plot them against the y-values in column 2.

While the above example works extremely well when evenly placed tics is desired, other circumstances may arise in which unevenly spaced text values may be desired.¹⁰ Remember from above that it is possible to set text xtics manually with set xtics ("name" value, "name2" value2,...), but the method here has the advantage of being automatic. Here is an example:

To accomplish this, make a table with a column for the value of the xtics (where it should be placed on the axis), another column with the name for each xtic (the names to be used), and then add whatever subsequent y values should correspond to these x-values. Here is an example:

#+begin_src gnuplot :var data=named-xtics :exports code :file file.png
  reset

  set yrange [0:25]
  set ylabel "Deaths (MM)"

  set xtics ("1850" 1850, "2010" 2010)
  set xrange [1850:2010]
  set xlabel "Wars in Time"

  set title 'War Deaths'

  plot data using 2:3:xticlabels(1) w p lw 3 notitle
#+end_src

For multiple data sets, simply include multiple columns for y-values to be plotted and plot each data set with the syntax x:y:xticlabels(col #). Most likely, the col # will be the same for all data sets (the column of names for xtics will probably remain the same). Here is an example:

plot data u 2:3:xticlabels(1) title 'Set1',\
data u 2:4:xticlabels(1) title 'Set2', \
data u 2:5:xticlabels(1) title 'Set3'
#+end_src

It is possible to set different scales for both x and y axes. This can be helpful for various reasons:

• Plotting data in two units of measure (e.g. left y axis = degrees F, right = degrees C)
• Plotting one data set against one axis and another against the other in the same graph

Returning to the running log, perhaps both times and distances were to be plotted in the same graph:¹¹

#+begin_src gnuplot :var data=multi-axes :exports code :file file.png
  reset

  set title "Running Stats"
  set size ratio square
  set key box linestyle -1

  set xlabel "Date"
  set xtics nomirror rotate by -45

  set yrange [9:21]
  set ylabel "Time (min)--Red"
  set ytics nomirror

  set y2range [1.5:3.5]
  set y2label "Distance (mi)--Green"
  set y2tics 0,0.5,3.5

  set style data points
  plot data u 2:xticlabels(1) axis x1y1 lw 3 title 'Time', \
       data u 3:xticlabels(1) axis x1y2 lw 3 title 'Distance'
#+end_src

Walking through the new items in the code:

• y2range, y2label, and y2tics set the options for the second y-axis, the one on the right side of the graph
• Setting both xtics and ytics to nomirror keeps tics off of the top of the plot border as well as keeping the left ytics from showing up on the right y-axis since the scales are different (this would be confusing)
• The plot commands have an axis x#y# argument
  • The first is plotted against the bottom x-axis (x1) and the left y-axis(y1) by inserting axis x1y1
  • The second is plotted against the bottom x-axis (the x-values are the same for both plots) but the right y-axis with axis x1y2

Lastly, in a plot like this where the left and right axis units (distance and time) can be related (d/t = speed), it is possible to create a "calibrated" plot. Note the ranges specified for the two graphs:

• y1min = 9min, y2min = 1.5mi; 1.5mi/9min = 10mph
• y1max = 21min, y2max = 3.5; 3.5mi/21min = 10mph

Since both axes are "calibrated" in this way, examining the two points plotted for each date can be visually informative:

• Distance/time on top of each other indicate that the speed was 10mph
• If the distance plot is higher than time, speed > 10mph (e.g. 9/2)
• If the time plot is higher than distance, speed < 10mph (e.g. 9/5)

Simply changing the yranges allows for re-calibrating the plot for a different target speed.

Sometimes, more than one scale is desired on the x-axis to call attention one or more areas on a curve. Perhaps most of a curve is rather "plain," but some detail exists which would stand out more if the scale were altered. This can be accomplished by something called multiplot which uses multiple graphs overlayed next to one another to create the appearance of one graph that uses varying scales along the x-axis.^{12 , 13} Here is an example:

Here is some data on the population of the world through time:¹⁴

#+begin_src gnuplot :var data=diff-scales :exports code :file file.png
  reset

  set xrange [ -10000 : 1 ]
  set yrange [ 0 : 7000 ]
  set xlabel "Time"

  set multiplot

  set size 0.275,1
  set origin 0.0,0.0
  set lmargin 10
  set rmargin 0
  set ylabel "Population (MM)"
  set ytics nomirror
  plot data using 2:3:xticlabels(1) with lines lw 3 notitle

  set origin 0.275,0.0
  set size 0.15,1
  set format y ""
  set noytics
  set lmargin 0
  set rmargin 0
  set xrange [2 : 1750]
  set ylabel ""
  plot data using 2:3:xticlabels(1) with lines lw 3 notitle

  set origin 0.425,0.0
  set size 0.575,1
  set format y ""
  set noytics
  set lmargin 0
  set rmargin 2
  set xrange [1751 : 2005]
  set ylabel ""
  plot data using 2:3:xticlabels(1) with lines lw 3 notitle

  set nomultiplot
#+end_src

Walking through the code:

• Left Slice
  • An initial xrange/yrange are set for the left-most "slice" of the graph
  • An x-axis label is also provided and the multiplot mode is set
  • set size tells gnuplot to make the first slice the full height high (1) but only .275 (out of 1) wide. This leaves 72.5% of the graph for the next two slices
  • set origin tells gnuplot to start the plot at the bottom left (0,0)
  • lmargin is set for 10 (standard) but rmargin is set at 0 in order to let the left edge of the middle slice sit against the right edge of the left-most slice with no gap
  • The ylabel is set here, and only once. Each slice is treated as a separate graph, and setting it for each slice creates mutliple labels which is unnecessary since they all share the same label/units.
  • Lastly, the data is plotted
• Middle slice
  • New values are given for the xrange, the ylabel is set to blank, and the plot command is about the same
  • This time both lmargin and rmargin are set to 0 to allow for seamless alignment with the left-most and right-most slices of the plot
  • The size is set for 0.15 width since this portion does not need to be very wide
  • Note that the origin is set to start where the previous slice left off (left slice origin + left slice width = 0 + 0.275 = 0.275)
• Right slice
  • New values are given for the xrange, the ylabel is set to blank, and the plot command is about the same again
  • The lmargin is 0 so that the slice aligns with the right edge of the middle slice, but rmargin is set for 2 to provide a nice border between the picture and the right y-axis
  • The origin for the right slice is set for the left slice width + middle slice width = 0.275 + 0.15 = 0.425
  • The size is set to take up the remaining width: 1 - 0.275 - 0.15 = 0.575

The set no ytics option removes the tics from the vertical divisions separating the slices. Using set ytics nomirror on the first slice keeps the ytics off of the first division.

The divisions could be turned off altogether if one wanted to. Gnuplot accepts setting borders individually in the form of set border 1+2+4+8. Each number stands for one of the borders:

• 1 = bottom
• 2 = left
• 4 = top
• 8 = right

For no vertical divisions in our example, this would be used:

• Left slice: use set border 1+2+4 (bottom, left, top)
• Middle slice: use set border 1+4 (bottom, top)
• Right slice: use set border 1+4+8 (bottom, top, right)

While slightly more visually appealing, this may be potentially confusing since no divisions gives the illusion that the x-axis is the same scale. If the divisions are there, it helps communicate that there is something else going on.

This method can be used for functions instead of data from a table as well in order to zoom in on a particular slice of a graph. One of the previous footnote above presents such case.¹³

Arrows can be used quite cleverly to "break" axes.^{15 , 16 , 17} The method involves drawing 6 arrows to "break" both the top and bottom x-axes: 2 diagonal and 1 white per axis to create the illusion of a break.

While the following is not really to scale, the example of a far distant date with a broken line and then some recent dates shows one example where this can be employed to create an esthetically pleasing plot. The world population data will be used again with some slight modifications.

#+begin_src gnuplot :var data=broken-axis :exports code :file file.png
  reset

  A=1725
  B=1600
  C=2010
  D=0
  E=6500

  xoff=.005*(C-B)
  yoff=.02*(E-D)

  set arrow 1 from A-xoff, D to A+xoff, D nohead lw 2 lc rgb "#ffffff" front
  set arrow 2 from A-xoff, E to A+xoff, E nohead lw 2 lc rgb "#ffffff" front
  set arrow 3 from A-xoff-xoff, D-yoff to A+xoff-xoff, D+yoff nohead front
  set arrow 4 from A-xoff+xoff, D-yoff to A+xoff+xoff, D+yoff nohead front
  set arrow 5 from A-xoff-xoff, E-yoff to A+xoff-xoff, E+yoff nohead front
  set arrow 6 from A-xoff+xoff, E-yoff to A+xoff+xoff, E+yoff nohead front

  set xrange [B:C]
  set yrange [D:E]

  set xlabel 'Time'
  set ylabel 'Population (MM)'
  set title 'World Population'

  plot data u 2:3:xticlabels(1) w l lw 3 notitle, data u 2:4:xticlabels(1) w l lw 3 lc 1 notitle
#+end_src

Here are some notes on the above:

• A->E are variables used to set the break location (A), the xrange (B,C) and the yrange (D,E)
• xoff/yoff have to do with the break. xoff is the gap created in the x-axis and yoff is the height above and below the scale for the diagonal lines. The multipliers (.005 & .02) work for this example but may need tinkering to work elsewhere (if they don't look right).
• The arrows (the set arrow... commands) draw the 4 diagonal lines and a white line in between them to create the actual break
• Two sets of y values and two plot commands were used to create the break between AD 1 and 1750. This is not always needed. See the gnuplot-tricks blog for how to do this with a continuous function (e.g. sin x) and an "offset" variable for the same effect.¹⁶

In the case above, the x-axis is "cheated" in that it is not only broken, but the scale is artificially manipulated. In the data chart, there should have been population values at 10,000 BC, 5,000 BC, and 1 AD. Instead they occur at 1600, 1650 and 1700 AD. The spacing is proportionate, but scaled by 100x (50 years apart vs. 5,000). Compared to the plot from 1750-2005, it's obviously not the same x-axis scale. If the actual data points were used, the later data points would have been significantly "scrunched." While not technically correct, it's perhaps more visually appealing, especially where scale is not too important. To get the point across, it does the job very well: left of break was not much growth, then in a much smaller time scale to the right of the break, much population growth occurred. The multi-axes/scales in the previous section is more "honest" with respect to scale, but perhaps this example is cleaner/better looking.

Obviously there are many functions (like sin (x) from gnuplot-tricks) where changing the scale is not required and thus the plot is both visually appealing and manipulation of scales is not required.

Sometimes when executing code blocks, odd results occur. Plots will persist in displaying the wrong title, a "remnant" option from a previously generated plot will appear, the size ratio will be wrong, etc. This typically happens when multiple gnuplot blocks exist in the same document. The use of reset at the beginning of each gnuplot block eliminates these issues by clearing any "residual options" from previously generated output.

For many graphs, output to .png (with :file filename.png in the header) may be sufficient. Sometimes, however, the generated image quality is not acceptable. The mailing list provided an excellent solution for increased gnuplot image quality:¹⁸

#+begin_src gnuplot :file file.eps
  reset
  set terminal postscript [color] [solid] eps enhanced 20
  ...
  ...
#+end_src

Note the output to file.eps, which corresponds to the set terminal... command used. This creates a higher resolution .eps image instead of a .png. The color and solid options are optional. Without the color option, the output will default to monochrome (black and white). The solid option can be used to keep all linestyles as solid lines; without it, gnuplot will cycle through various styles of dashes/shapes/etc.

Once the .eps file is generated, ImageMagick can be used to convert it to .png:¹⁹

convert -density 300 file.eps file.png