Chapter 8. All about axes

This chapter covers

• Using multiple axes
• Selecting plot ranges
• Customizing tic marks and tic labels
• Plotting time series with gnuplot

In this chapter, we finally come to coordinate axes and their labeling. Treating them last, after discussing plot styles and decorations, may seem surprising, given how critical well-labeled coordinate axes are to achieving an informative graph. On the other hand, gnuplot’s default behavior for axes-related options is adequate in almost all situations, so explicit customization is rarely required.

One topic deserves special consideration: the use of multiple axes on the same plot. We’ll discuss this first. Then we’ll move on and describe all the ways axes and their labels can be customized. Finally, we’ll treat the special case when one axis (usually the x axis) represents time: in other words, when the plot shows a time series. Time-series plots pose special challenges, because the labels aren’t numeric. Instead, you need to worry about things such as the names of months and weekdays—potentially in different languages! This has long been a problem to gnuplot users, so I’ll devote significant space to this application. But first, let’s talk about multiple axes on the same plot.

8.1. Multiple axes

Gnuplot gives you the ability to plot graphs using two different coordinate systems within the same plot. Typically, these coordinate systems share one axis (otherwise there’s no good reason to have them on the same plot), but they may also be entirely independent.

Plots involving two different y axes usually make the most sense when you want to compare side by side two data sets that have very different units. As a typical example, let’s study figure 8.1, which compares the average ice cream consumption (in some community) over consecutive four-week periods with the mean temperature during the same period.^[1]

¹

This example was inspired by the “Ice Cream Consumption” story, found in the StatLib’s Data and Story Library (DASL) at http://lib.stat.cmu.edu/DASL/Datafiles/IceCream.html.

Figure 8.1. Using multiple axes on a plot to compare two different quantities side by side. (See listing 8.2 to find out how this plot was made.)

Figure 8.1 is a good example of why you might want to use multiple axes on a plot: the two quantities (ice cream consumption and temperature) are of a different nature and are also numerically quite different. Yet once you put them next to each other, the correlation becomes clear (not too surprisingly, in this example).

8.1.1. Terminology

As you’ve just seen, gnuplot can handle two sets of axes on a single plot. The consequence is that all commands and options to manipulate axes-related properties come in two versions—one for each set of axes. This section summarizes the naming conventions associated with these commands.

The primary coordinate system is usually plotted along the bottom and left borders of the graph. (This corresponds to the first coordinate system introduced in section 7.2.) If the secondary system (second) is used, it’s plotted along the top and right borders.

By default, the secondary system isn’t used. Instead, the tic marks (but not the labels) of the primary system are mirrored on opposite sides of the plot (that is, on the top and right borders, respectively).

All options that modify aspects of the coordinate systems can be applied to any of the axes: either the x or the y axis, in either the primary or the secondary coordinate system. The commands and options are prefixed to indicate which specific axis a command should be applied to (see table 8.1). Omitting the prefix applies the option to all axes.

Table 8.1. Prefixes used to indicate the selected coordinate system

In the rest of this chapter, I’ll frequently discuss only one variant of any option—typically the one for the x axis of the primary coordinate system. You should keep in mind that everything applies to all other axes as well, just by selecting the appropriate prefix per table 8.1.

8.1.2. Plotting with two coordinate systems

The best way to understand how multiple coordinate systems are used in the same plot is through an example. Listing 8.1 shows the beginning of the data file from figure 8.1; the complete set of commands used to generate the plot from the data file is in listing 8.2.

Listing 8.1. Incomplete data for figure 8.1 (file: icecream)

# Date         Consumption[g]   Temperature[Celsius]
1951-04-01     179.8             6.01
1951-04-29     180.8            13.34
1951-05-27     186.5            17.78
1951-06-24     202.1            19.38
1951-07-22     190.1            19.48
...

Listing 8.2. Commands for figure 8.1 using data from listing 8.1 (file: icecream.gp)

The first three lines (from set timefmt to set xdata) tell gnuplot how to parse and format the calendar date used along the x axis. We’ll discuss them in section 8.4.

Next, the mirroring of the primary axis’ tic marks is switched off on the opposite (right) side of the plot (set ytics nomirror), and instead tic marks for the secondary y axis (set y2tics) are switched on.

Explicit labels are placed on both vertical axes—this step is crucial when using multiple axes, because otherwise the viewer has no chance of figuring out which data set goes with which axis. The key is modified from its default location and appearance (see section 7.4 if you need a refresher on any of the options).

Finally, the only new thing in the actual plot command is the use of the axes keyword with its arguments. These directives tell the plot command which combination of axes to use for each data set. For example, axes x1y2 means that the data should be plotted according to the primary x axis, but the secondary y axis. There are four possible combinations of axes that can be used, and they can be selected using x1y1, x1y2, x2y1, and x2y2.

8.1.3. Linking axes

In the previous section, you learned how to plot two curves representing different and independent quantities (ice cream consumption and temperature) on the same plot. In this section, we’ll consider a related problem: how to plot two curves representing different but related quantities.

Let’s look at an example. Figure 8.2 shows two data files, side by side. Both contain temperature readings for the same date range, but for two different locations (New York City, USA and Frankfurt a.M., Germany) and in two different units (Fahrenheit and Celsius).^[2]

²

Weather data is available from the respective government services: http://mng.bz/V299 and www.dwd.de.

Figure 8.2. Two data sets showing daily temperatures. Note that the data sets use different units.

Because both data sets show the same kind of data, it makes sense to plot them in the same graph. Nevertheless, because the units are different, the two data sets can’t just share a single y axis. Of course, you could use inline transformations (see section 3.3) to transform (say) the Fahrenheit values into Celsius and plot them—but in order to easily go back and forth between both temperature systems, it would be nice if you could retain both units in the same plot.

This is where gnuplot’s new set link facility comes in. Using set link, you can make the values on one axis dependent on the values on the opposite axis. All you need to do is provide a link function that maps values from one system to the other, together with its inverse.

In this example, Celsius must be mapped to Fahrenheit and vice versa. The two temperature systems are related to each other by the following formulas:

Fahrenheit = (9/5)*Celsius + 32
Celsius    = (5/9)*(Fahrenheit - 32)

Using these formulas, you can set up the link between the two vertical axes:

set link y2 via (9/5.)*y+32 inverse (5/9.)*(y-32)

This establishes a link between the primary vertical axis (the y axis, on the left), which shows temperatures in Celsius, and the secondary vertical axis (the y2 axis, on the right), which shows values in Fahrenheit. You can now plot both files using the commands from listing 8.3; the resulting graph is shown in figure 8.3. (See listing 8.2 for an explanation of the commands at the beginning of this example.)

Figure 8.3. Linking two axes using link. See the text for details and listing 8.3 for the commands.

Listing 8.3. Commands for figure 8.3 using data from figure 8.2 (file: link.gp)

set xdata time
set timefmt "%Y-%m-%d"

set xtics format "%d%b%y"
set ytics nomirror
set y2tics

set ylabel "Celsius"
set y2label "Fahrenheit"

set link y2 via (9/5.)*y+32 inverse (5/9.)*(y-32)

plot "frankfurt" u 1:2 axis x1y1 w lp, "newyork" u 1:2 axis x1y2 w lp

This example should give you a sense how the set link feature can be used. Here are a few additional details:

• Links can be established between the two horizontal axes and between the two vertical axes using set link x2 and set link y2, respectively.
• When linking the horizontal axes using set link x2, you must call the dummy variable in the link functions x; when linking the vertical axes using set link y2, the dummy variable in the link functions must be called y.
• You can remove the link between either set of axes using unset link x2 or unset link y2.
• Keep in mind that the link function must be invertible! This isn’t a problem when the link function is linear (as in the example), but non-linear functions are, in general, not invertible (or are invertible only over a limited domain—the function x², for instance, is invertible for all non-negative values of x).

The set link feature is relatively new and strikes me (at the time of this writing) as still somewhat immature. Feel free to experiment further!

plot "data" u 1:(log10($2)) w lp

set link y2 via 10**y inverse log10(y)

set y2tics ( 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000 )

8.2. Selecting plot ranges

I introduced plot ranges in chapter 2, but only in a limited form as an inline specification to the plot command, something like this:

plot [-10:10][-2:2] sin(x)

The first pair of numbers in brackets sets the desired x range, and the second pair of numbers in brackets fixes the y range. Both terms are optional—if you leave them out, gnuplot will select ranges automatically.

This is enough—most of the time. But using this syntax, only the plot ranges of the primary coordinate system can be fixed, which is insufficient if you want to use multiple axes on the same plot. Also, the inline syntax doesn’t work well when you’re attempting to change the plot range with the mouse. Let’s look at gnuplot’s facilities for controlling plot ranges in more detail.

Tip

A distinctive property of good graphs is that they show what is relevant. Plot ranges are the primary means of achieving this goal. Well-selected plot ranges are essential!

8.2.1. What you need to know for interactive work

The inline syntax is a shorthand for the family of _range commands. (In this discussion, the underscore is a placeholder for any one of the prefixes from table 8.1.) To adjust plot ranges for the primary and secondary systems independently, you need to issue separate set _range commands using different prefixes.

The explicit set _range commands expect a pair of numbers enclosed in square brackets, similar to the syntax for inline range specifications. The following listing shows some examples of _range commands in action.

Listing 8.4. Permissible syntax for setting plot ranges

In addition to providing explicit lower and upper boundaries, you can leave one or both of the numbers blank, in which case the corresponding value won’t be changed. Alternatively, you can supply a star (*) to turn on autoscaling for that particular value. Autoscaling means gnuplot selects a plot range that is at least large enough to include all data points, but gnuplot may extend the range in order to include the next full tic mark position. This behavior can be suppressed using the noextend specifier. Using the following setting, the vertical range is bounded precisely by the minimal and maximal values in the plotted data set:

set yrange [*:*] noextend

The inline shorthand (like plot [0:1] ...) only affects the command line it’s part of—it doesn’t reset the overall plot ranges, the way set _range does. This is why you don’t need to use the * indicator to turn on vertical autoscaling when using only the shorthand: by default, the plot ranges are [-10:10] horizontally and [*:*] vertically. Issuing a command like plot [][0:1] ... doesn’t change the global autoscale setting for the y axis, so a subsequent command like plot [][0:] ... will autoscale the positive y axis. But if the vertical range has been fixed globally—using set yrange [0:5], for example—then plot [][0:] ... will honor the explicit plot range. To reestablish autoscaling behavior, you need to turn it on explicitly, either inline (plot [][0:*] ...) or using set yrange [0:*].

8.2.2. What you might want to know for batch processing

Special considerations apply when creating large numbers of graphs automatically. Imagine, for instance, that you want to monitor traffic across many websites—in hosted or enterprise environments, this may mean following hundreds of separate traffic streams. Furthermore, the traffic to these sites is likely to vary by several orders of magnitude: a busy site may see tens of thousands of clicks a day (or more), but other sites may see few if any clicks.

Obviously, you don’t want to select plot ranges manually (for all the sites—every day!). But relying entirely on gnuplot to adapt the plot range to the available data often isn’t satisfactory either. For some of the very slow sites (those that show at most a single click a day), gnuplot will select a vertical plot range of [0:1], which isn’t a visually pleasing solution. It would be better if you could make sure the plot range is always at least [0:10] but larger if need be. Fortunately, gnuplot let’s you do just that: you can define bounds for autoscaled ranges. The next listing shows you the syntax.

Listing 8.5. Restricting plot ranges to bounded intervals

Other times, it may make sense to let autoscaling apply to only some of the lines in a plot. For example, imagine that you want to plot two data sets together, one of which is corrupted by occasional crazy outliers. In that case, you may want to let gnuplot use only the smoother curve to determine the plot range. There are two ways to do this. Using the noautoscale (noauto for short) keyword, you can flag those data sets in a plot command that should be disregarded when determining the plot range:^[3]

³

The noautoscale directive is available only when plotting data files, not when plotting functions. If you want to use it with functions, you need to “fake” it using the "+" pseudofile facility (see section 4.5).

plot "smooth" u 1:2, "noisy" u 1:2 noautoscale

Another approach is to evaluate the data sets first and then use the information obtained to calculate the plot range. The set _range family of options provides a way of doing this (using writeback and restore), but the stats command (see section 5.6) and the internal variables it defines are probably more straightforward to use.^[4]

⁴

Another related option is set autoscale, possibly in conjunction with set offset, but it seems overly complicated and largely redundant. For more information about this, as well as about writeback and restore, see the standard reference documentation.

8.3. Tic marks

Subdivision markers or tic marks are placed on the axes of a plot to indicate the scale of the graph. Only if tic marks are present can a viewer infer quantitative information from a graph. Suitably chosen tic marks are therefore of critical importance to any well-constructed graph. Fortunately, gnuplot handles tic marks well on its own, and you rarely need to customize tic-mark generation and labeling. But for the few cases when you do have special requests, here’s how to do it.

8.3.1. Overview and common conventions

Gnuplot distinguishes between major and minor tic marks. The difference is that major tic marks also carry a textual label (normally a number), whereas minor tic marks don’t. By default, only major tic marks are used, except for logarithmic axes, where both major and minor tic marks are drawn by default.

Major tic marks are by far the more important of the two types. The appearance of major tic marks and their labels is controlled through the family of set _tics options. The available sub-options are as follows:

set _tics [ axis | border ]
          [ in | out ] [ front | back ]
          [ scale [ default | {flt:major} [,{flt:minor}] ] ]
          [ [no]mirror ]

          [ rotate [by {flt:ang}] | norotate ]
          [ left | right | center | autojustify ]
          [ offset {pos:offset} | nooffset ]
          [ font "{str:name} [,{int:size}]" ]
          [ textcolor | tc {clr:color} ]
          [ format {"str:format"} ]

As before, the underscore _ is a placeholder for any one of the available axes identifiers (see table 8.1), indicating which axis the settings should be applied to. If you omit the identifier (set tics ...), then the chosen style is applied to all axes.

The location and frequency of tic marks is controlled through another set of sub-options to set _tics. These sub-options only make sense when applied to a specific axis (meaning you can’t leave the _ placeholder blank in this case):

set _tics ...
          [ add ]
          [ autofreq
            | {flt:incr}
            | {flt:start}, {flt:incr} [,{flt:end}]
            | ( ["{str:label}"] {flt:pos} [ 0 | 1 ]
                [, ["{str:label}"] ... ] ) ]

We’ll next step through these options: first we’ll discuss how to modify the appearance and placement of tic marks, and then we’ll talk about labels, before discussing ways to control the location and frequency of tic marks. We’ll round off this section with some related features that are handled using commands other than set _tics.

8.3.2. Tic mark appearance and placement

By default, gnuplot draws tic marks on the border of the plot, extending inward into the plot region, but they can be drawn toward the outside using the out option. This is useful in particular when the tic marks would interfere with the data. Tic marks can be drawn in either the front or the back layer of the visual stack (see section 7.2).

Instead of being placed along the borders of the plot, tic marks can also be drawn along the zero axis (for instance, set xtics axis draws tic marks along the line of the plot where y equals 0). If the zero axis isn’t within the plot range, the tic marks are drawn along the border.

The scale parameter controls the size of both major and minor tic marks. If no size for the minor tic marks is given explicitly, it’s set to half the size of the major marks. The size is given relative to the default size of 1.0 for major tic marks.

By default, the tic marks (but not their labels) of the primary coordinate system are mirrored on the opposite side. You can turn off this behavior using nomirror. You want to do this when you’re using two coordinate systems in one plot (such as both the y and the y2 systems), but there are also other situations when mirroring is undesirable.

A worked example

Figure 8.4 shows a graph that doesn’t use the gnuplot default format: it has no border, and instead uses explicitly drawn coordinate axes (zero axes). Because there is no border, the tic marks are drawn along the coordinate axes.

Figure 8.4. Nonstandard placement of coordinate axes and tic marks. See listing 8.6.

You’ll find the commands for this figure in listing 8.6. First the border is switched off, but the coordinate axes are drawn with solid black lines. (See section 8.3.6 later in this chapter for the set zeroaxis command. The line type -1 is guaranteed to draw a solid black line; see table 9.3.) Then gnuplot is instructed to place tic marks along the coordinate axis (instead of the border) with set xtics axis (and equivalent for the vertical axis). Finally, a function is plotted.^[5]

⁵

The Airy function is the solution to the differential equation y″ - xy = 0 that is bounded everywhere. It’s important in the approximation theory of differential equations.

Listing 8.6. Commands for figure 8.4 (file: var-axes.gp)

unset border
set zeroaxis lt -1

set xtics axis
set ytics axis

plot [-8:4] airy(x)

The resulting graph is closer to what is common in mathematical contexts, but the disadvantages are clear: the curve interferes with the tic marks whenever it crosses the axes. (The partial obscuring of the zeros near the origin could be avoided through smarter placement of the labels and isn’t a fundamental problem.)

8.3.3. Tic labels

The text labels associated with major tic marks can be rotated and shifted using rotate and offset. If rotate is used without an explicit angle (in degrees), the labels are turned by 90 degrees to the left. You can adjust the position of the labels using offset. The relative shift can be specified in one of the five usual coordinate systems (see section 7.2); if none is specified, the character coordinate system is assumed.

By default, tic labels are justified depending on the axis and the rotation angle (autojustify). Alternatively, you can control the alignment explicitly with left, right, and center. Text font and color can be selected in the usual fashion.

Formatting tic labels

You can change the formatting used for the labels placed at the major tic marks using set _tics format, followed by a string that describes the desired format.^[6] The format string is similar to the format string used by the printf() family of functions from the standard C library. In addition, gnuplot uses some extra format (or conversion) specifiers, which are listed in table 8.2. These conversion specifiers only apply to numeric arguments; for date/time values, check section 8.4.

⁶

Traditionally, formatting of tic labels was accomplished using the set format option. This option is still available, but it’s now redundant and should probably be avoided in favor of the more consistent method described in the text.

Table 8.2. Conversion specifiers understood by the gprintf(...) function. See table 8.4 and table 8.5 for conversion specifiers for date and time values, and table 5.1 for information on gprintf(...).

^a

This conversion specifier is new with gnuplot 5.

Tip

Don’t attempt to build up date and time strings manually; use dedicated conversion specifiers for time series (see section 8.4).

If the % character is encountered in the format string, it’s interpreted as the beginning of a conversion specifier. It must be followed by one of the characters from table 8.2. Several modifiers can be placed between the % character and the conversion specifier; see table 8.3. In general, gnuplot’s functionality is built on top of the system’s C library—check its documentation for additional details.

Table 8.3. Accuracy specifiers to be used with the gprintf() and sprintf() functions

The format string can also contain arbitrary characters, which are placed verbatim onto the plot. This makes it possible, for instance, to print the units (such as kg or cm) together with the numerical values.

Finally, providing an empty string as the format specifier (as in set xtics format "") is a way to suppress the generation of tic labels, although the tic marks are drawn.

Scientific notation and enhanced text mode

Several of the conversion specifiers in table 8.2 give you individual access to the coefficient and exponent of a number in scientific notation. They’re intended for situations where you want to build up the combination of coefficient and exponent yourself.

In scientific notation, a number x is represented as

x = a × b^c

where a is called the coefficient (also mantissa or significand), b is the base, and c is called the exponent or power. For example, the number 1,024 can be written as 1.024 × 10³ (base 10) or 1 × 2¹⁰ (base 2).

When in enhanced text mode, gnuplot interprets certain regular characters embedded in string labels as control or formatting characters. This way, it’s possible to change font face, size, and weight locally and on the fly.^[7] A full discussion of enhanced text mode will have to wait until chapter 10; what is of interest in the context of tic marks and especially tic labels is the ability to include subscripts and superscripts in all text elements that are part of a graph. Subscripts are indicated with an underscore (_) and superscripts with a caret (^). A single character following either of these (or a sequence of characters enclosed in curly braces) is formatted as subscript or superscript, respectively.

⁷

Enhanced text mode is now the default in gnuplot 5; in general, it’s no longer necessary to enable it explicitly. In fact, at times you may need to disable it using the noenhanced keyword in order to include control characters in text labels.

In particular for powers of 10, the ability to use real superscripts is welcome. Imagine a number such as 5,000. In scientific notation, this becomes

5 × 10³

Using the customary E notation (see section 4.3), this is written as 5.0e+03. But using enhanced text mode, you can format this string as

"5 × 10^{3}"

(or even as "5 × 10^3", because the exponent consists only of a single character), and gnuplot will display the exponent as a proper superscript.

The new conversion specifiers %h and %H use enhanced text mode to format numbers this way if the proper encoding (such as UTF-8; see the sidebar in section 5.1) has been chosen. Otherwise, the lowercase version (%h) uses the letter x to signify the multiplication operator following the coefficient, whereas the uppercase version (%H) uses the asterisk *.

A worked example

Let’s study an example. Figure 8.5 shows the weight of several mammals as a function of their heart rate in a double-logarithmic plot. Remarkably, the points seem to fall roughly onto a straight line: there is a distinct relationship between the size (or weight) of an animal and the rate of its metabolism. This is known as allometric scaling and extends to other properties, such as the life span, as well: bigger animals live longer. Allometric scaling is a fascinating topic, but what interests us right now are the commands used to draw this graph. They’re shown in the following listing.

Figure 8.5. Allometric scaling: larger animals have a slower heart rate. Notice the customized tic labels along both axes. See the text for details and listing 8.7 for the commands.

Listing 8.7. Commands for figure 8.5 (file: mammals.gp)

Choosing logarithmic scales and setting axes labels should be familiar by now, but pay close attention to the way the tic labels are formatted. For the vertical axis, the format string is "%.0s%cg" . According to table 8.2, %s is the coefficient (in scientific notation) when the power is restricted to being a multiple of 3, and %c is a character replacement for that power (k for kilo, M for Mega, and so on). Hence a number like 2,000 is split into the coefficient 2 (all decimals are suppressed because of %.0s), followed by k for the factor of 1,000. The example tacks on an additional g, which carries through unchanged, to represent the weight unit gram. The result is perfect for grams and kilograms, but megagrams are more commonly known as (metric) tons. The horizontal axes uses a custom format with a multiplication dot in place of the cross sign .^[8] Finally, the plot command is an interesting example of the use of the with labels style (see section 6.3.5), with an explicitly selected point type and color .

⁸

The multiplication cross can be found at Unicode code point U+00d7 and the multiplication dot at U+22c5. The interpunct at code point U+00b7 provides an alternative for the latter that may be more readily available.

8.3.4. Tic mark location and frequency

Finally, you can control where tic marks are drawn. Using autofreq, gnuplot will automatically generate tic marks covering the plot range.^[9] Alternatively, you can provide an increment alone; then tic marks are drawn at integer multiples of the increment. Or you can specify a start point, an increment, and (optionally) an endpoint. (For logarithmic axes, the increment is interpreted multiplicatively instead of additively.)

⁹

To generate tic marks covering only the actual range of the data, rather than the plot range, you can use the rangelimited keyword. See the standard gnuplot reference documentation for details.

Some examples will clarify (remember that the variable pi is predefined in gnuplot):

You can also provide a list of explicit labels and locations at which to draw tic marks. The list must be enclosed in regular parentheses, with list entries separated by commas. Each entry in the list consists of the text label for the tic mark, its location, and a third, optional parameter that indicates whether the tic mark should be drawn as a major or minor tic mark: 0 for major and 1 for minor.^[10] The text label can be an empty string (so that no label is drawn for the tic mark), or it can be missing (in this case, a textual representation of the location parameter is used as a label). If a text label is provided for minor tic marks, it’s ignored. Here are some examples:

¹⁰

You can add further levels of tic marks beyond major and minor. See the standard gnuplot reference documentation for set tics and set xtics for details.

Adding and overriding individual tic marks

Usually, any change to the location and frequency of tic marks wipes out any previous settings. To make changes to individual tic marks while retaining existing ones, use the add keyword. This can be useful for adding tic marks for special values to otherwise autogenerated tics, like so:

set xtics autofreq
set xtics add ( "π" pi )

These commands draw a tic mark at π in addition to the automatically generated ones. If you omitted the add keyword here, the second line would clobber the first, and the only tic mark would be the one explicitly set at π.

You can also use the add keyword to override the label of an autogenerated tic mark.^[11] Consider the following:

¹¹

I’d like to thank Christoph Bersch for making me aware of this possibility.

Tip

You can use set _tic add to add individual tic marks or to replace the label for autogenerated ones.

Minor tic marks

Minor tic marks aren’t labeled and are typically drawn smaller than major tic marks. By default, minor tic marks are disabled for linear axes and enabled for logarithmic axes.

Minor tic marks can be switched on using the m_tics family of options, where the underscore is again used as a placeholder for any of the usual prefixes:

set m_tics [ {int:intervals} ]

The optional parameter counts the number of subintervals between major tics marks; the number of minor tic marks generated is one less than this number. For example, let’s say there are major tic marks at x=0 and x=5, and you’d like to create minor tic marks for all the integers in between. The command set mxtics 5 will do the trick, because there are five integer-sized intervals between neighboring major tics, but the number of minor tic marks generated is only four.

Minor tic marks are drawn only when there are regularly spaced major tic marks. If all major tics are individually placed, m_tics has no effect. You can still create minor tic marks manually, using set _tics.

A worked example

You may have wondered how I generated the plot in figure 4.2 using two different y axis scales, each covering only part of the plot. Now you have all the information at hand to discover the secret.

The plot shows the same data twice, but vertically shifted. You can achieve this—without using inline transformations!—by plotting the data once against the primary and once against the secondary vertical coordinate axis, with properly chosen plot ranges for both axes. Note how the visible range (from min to max) is the same for both systems, but the two ranges are offset from each other.

Next, the tic marks are added. The following listing specifies both a start and an end value for tic-mark generation—this way, you partially label each axis, but only for the part of the plot that’s relevant to each curve.

Listing 8.8. Commands for figure 4.2 (file: missing.gp)

set yrange [9:16]
set y2range [6:13]

set ytics 9,1,12 nomirror
set y2tics 10,1,13

set datafile missing "NaN"

plot [0:10] "missing" u 1:2 ax x1y2 w linesp lt 1 pt 7,
          "" u 1:($2) ax x1y1 w linesp lt 1 pt 7

8.3.5. Reading tic labels from file

Finally, gnuplot can read the tic labels from the input file using the _ticlabels() family of functions as part of the using directive to the plot command. (The underscore _ is again a placeholder for any of the axis identifiers from table 8.1.)

Let’s look at the data file in listing 8.9. The x values are present both in numeric form (column 1) and as strings. Of course, it would be nice to use the strings for the tic labels. Here’s how to do that:

plot "months" u 1:2:xtic(3) w linesp

The xtic() function takes as argument the number of a column to be used for the tic labels. Equivalent functions exist for the other coordinate axes; labels for the y axis are specified after labels for the x axis.

Listing 8.9. Time series data for figure 8.7 (file: months)

# Month Data      Month Name
1        3        Jan
2        4        Feb
3        2        Mar
4        5        Apr
5        8        May
6        7        Jun
7        4        Jul
8        5        Aug
9        3        Sep
10       2        Oct
11       4        Nov
12       2        Dec

When you use any of the _tic() functions in a plot command, tic marks and labels are only drawn at the locations explicitly read from the data file—in other words, auto-generation of tic marks is turned off.

The _tic() functions allow a variety of further tricks beyond reading an explicit string from the data file. The following snippet calculates the quarter of the year for each month (such as Q1 or Q2) and uses it as the tic label:

plot "months" u 1:2:xtic( 'Q' . (1+int(($1-1)/3) )) w lp

In sections 8.4.1 and 8.4.2, I’ll show you two more ways to produce figure 8.7 (shown later in the chapter) from the file in listing 8.9.

8.3.6. Grid and zero axis

In addition (or as an alternative) to tic marks along the border of the graph, you can overlay a scale grid on the data. Grid lines are drawn at the position of major and, optionally, minor tic marks:

set grid [ [no]_tics ] [ [no]m_tics ]
         [ layerdefault | front | back ]
         [ polar [ {flt:angle} ] ]
         [ majorlineoptions [, minorlineoptions] ]

You can switch the grid on to be drawn at major or minor tic marks, for the primary or secondary coordinate system. (The underscore again must be replaced by any one of the prefixes from table 8.1.) Tic marks must be enabled—instructions to draw a grid at nonexistent tic locations are ignored. The grid is drawn either in front of (set grid front) or behind the data (set grid back).^[12] The lines to use for the grid can be set separately for grid lines drawn at major and minor tic marks. If no style or type is given, gnuplot uses the style ls 0, which draws the least-visible lines possible (often using a dotted line). The polar option is relevant only for plots using polar coordinates, which we’ll discuss in section F.2.1.

¹²

The option layerdefault is only relevant for three-dimensional graphs—see the standard reference documentation for details.

Similar to grid lines, but less obtrusive, are zero axes. These are lines drawn across the graph for all the points where one of the coordinates is equal to zero:

set _zeroaxis [ lineoptions ]

For example, set xzeroaxis switches on a horizontal line at y = 0 (representing the x axis). The default line type is ls 0, the same as for the grid.

A worked example

A quick example will help to clarify. (See the following listing and figure 8.6.) Turning on the grid is simple; more interesting are the tic marks and labels along the horizontal axis.

Figure 8.6. Tic marks at multiples of π and Greek letters used for the tic labels. See listing 8.10.

Listing 8.10. The commands for figure 8.6 (file: ticmarks.gp)

set grid
set xtics pi format "%.0Pp"

plot [-4*pi:4*pi] sin(x)/x

The command set xtics pi instructs gnuplot to place major tic marks at multiples of π. The format specification format "%.0Pπ" tells gnuplot to use the integer multiple of π as a label. Tacking on the character π makes it clear to the viewer what the tic marks represent.

It’s important to understand that the format specifier %P interprets a value as a multiple of π but by itself does not ensure that tic marks will only be drawn at integer multiples of π. Instead, you must explicitly choose the locations where tic marks will be drawn using set xtics pi and then use format "%P" to format the labels at those positions accordingly.

8.4. Special case: time series

Whenever you want to study how a quantity changes over time, you’re dealing with a time series.^[13] Time series are incredibly common—from stock charts and opinion polls to fever curves. Unfortunately, they pose special challenges, because the tic labels you’d like to use for the x axis (such as the names of months or weekdays) aren’t strictly numeric. Worse, they aren’t even universal, but locale-dependent. If you want to plot time-series data, you therefore need to be able to parse arbitrary date/time formats from a file, and you must be able to format timestamps in a suitable, locale-dependent format.

¹³

If the time intervals between successive measurements are equal, the data points form a discrete time series; otherwise, the time series is continuous. I have more to say about time-series analysis in chapter 14.

Gnuplot offers three different ways to deal with date/time information as part of axes labels:

• The classic approach uses set _data, set timefmt, and set _tics format, which let you parse and reformat arbitrary date/time information in the input file; I’ll describe these in detail in section 8.4.2. This is gnuplot’s most flexible and powerful method of handling timestamps.
• Alternatively, gnuplot can read fully formatted tic labels directly from the input file using the _ticlabels() functions introduced in section 8.3.5. This method is easy if the labels read from file are in the format you want, but it only works if the data set also contains numeric time information (to fix the x coordinate of the data points). It’s also only suitable for relatively sparse data sets, because _ticlabels() creates a tic mark and label for every data point. And it doesn’t allow locale-dependent formatting.
• For special cases when you don’t require arbitrary date/time labels but merely want to use the names of months or weekdays in a plot, gnuplot provides the simplified set _mtics and set _dtics facilities (see section 8.4.1).

In the next section, we’ll first discuss the simpler case of using month or weekday names as tic labels. Afterward, we’ll tackle the harder problem of dealing with arbitrary date/time information, both for input and for output. (Reading tic labels in files was discussed previously in section 8.3.5.)

set locale ["{str:locale}"]

8.4.1. Turning numbers into names: months and weekdays

Gnuplot provides two simple commands to turn numbers into the names of months or days of the week. They offer much less flexibility than the general time-series commands discussed in the next section, but they’re easy to use.

Let’s look back at the data file in listing 8.9. Suppose you want to label the x axis with the names of the months, but without using the explicit names in the third column. You can do this using the set xmtics command, which maps numbers to names of months (with 1=“January”, ..., 12=“December”). Don’t confuse this command with the set mxtics command introduced in section 8.3.4, which switches on minor tic marks!

The following sequence of commands produced the plot in figure 8.7:

Figure 8.7. A time-series plot, using set xmtics to use months for the labels along the horizontal axis. Also see listings 8.11 and 8.12. The data is shown in listing 8.9.

In addition to the names of months, you can use days of the week (such as “Mon”, “Tue”, and so on) as tic labels. You enable them using set xdtics (with 0=“Sunday”, ..., 6=“Saturday”), similar to what you’ve seen for set xmtics. Both set xmtics and set xdtics map overflows back into the legal range through a modulo operation (modulo 12 and modulo 7, respectively), as you’d expect. To restore normal (numerical) axes labeling, use unset xmtics or unset xdtics. Equivalent commands exist for all other axes, using the usual prefixes in table 8.1.

The set xmtics and set xdtics facilities are very limited. The strings follow the locale but can’t be formatted any further. But as a quick-and-easy alternative to the general methods described next, the techniques introduced in this section are occasionally useful.

8.4.2. General time series: the gory details

For more general time series, you face two problems: you must be able to read arbitrary timestamps from the input file and then format them again for output. But before you can do anything, you must first put gnuplot into time-series mode (for the primary x axis) using

set xdata time

Issuing set xdata (without an argument) restores normal operation. Equivalent commands exist for all other axes, distinguished through the usual prefixes.

Tip

To handle general date and time information in data files, you must first switch to time-series mode using set xdata time. In time-series mode, timestamps are parsed (for input) according to the value of set timefmt and are formatted (for output) according to set _tics format.

In time-series mode, input (parsing of timestamps from files) and output (formatting timestamps for inclusion in the plot) are controlled by the commands set timefmt for input and set xtics format for output.^[14] Both accept a format string using a syntax similar to that found in the POSIX strftime() routine. (I introduced set _tics format in section 8.3.3 already, but there we only talked about the formatting of plain numbers. Now I explain the ability to format complex date/time values.)

¹⁴

The command set format x is an older alternative for controlling the output format. It’s now redundant, but you’ll still find references to it in the standard reference documentation.

Gnuplot assumes that all data is in universal time coordinates (UTC)—it has no facilities to perform time zone changes, adjust for daylight savings, or apply similar transformations. If they’re required, they must be applied externally, before you attempt to plot the data.^[15]

¹⁵

Gnuplot 5 stores timestamps internally as seconds since the beginning of the Unix epoch. This is a change from previous versions of gnuplot.

Input

Time/date information is parsed in a way reminiscent of the scanf() family of functions and shares its familiar challenges. The expected input format is indicated through a format string to set timefmt. The format string may contain several conversion specifiers, all of which begin with the % character, followed by a letter that indicates how an input value should be interpreted. Check tables 8.4 and 8.5 for a list of all possible conversion specifiers and their meanings.

Table 8.4. Alphabetically sorted conversion specifiers for date/time information for the set _tics format and set timefmt commands. See table 8.2 to format numeric values. See table 8.5 for a list sorted by topic.

Table 8.5. Conversion specifiers for date/time information for the set _tics format and set timefmt commands, sorted by topic. See table 8.2 to format numeric values. See table 8.4 for a list sorted alphabetically by conversion specifier.

The input format string may contain other characters besides format specifiers, but input strings must match the format exactly (with some exceptions regarding whitespace that we’ll discuss shortly):

If there are no characters separating different fields from one another, gnuplot consumes a fixed number of characters per field (left to right), and the fields must be left-zero-padded as necessary:

Special rules apply when the date format to be parsed contains whitespace. First, gnuplot interprets whitespace-separated data as occupying several columns. A timefmt format containing whitespace in turn consumes several columns. A blank space (not an escaped tab: ) embedded in a formatting string matches one or more blanks (not tabs) in the input file. So, "%H %M" matches 12␣20 and 12␣␣␣20 but not 1220. (The ␣ symbol indicates a whitespace character.)

An example will help. The following input file

2005-01-01     8:41     3
2005-01-01     9:17     4
2005-01-01    22:46     2
2005-01-02    03:05     5

will be correctly parsed and plotted by the following commands:

set xdata time
set timefmt "%Y-%m-%d %H:%M"
set xtics format "%F
%T" rotate
plot "data" u 1:3 w lp

Note that the column used for the y values is the third, because the time format consumes two columns. Also, the format string contains a single whitespace, but in the data file several blanks separate the date from the time. The file won’t parse correctly if the spaces between date and time are replaced by tabs.

Finally, gnuplot won’t parse strings enclosed in quotes (see section 4.3.3). Therefore, you can’t parse a file that contains date/time information as strings with embedded whitespace:

Also keep in mind that gnuplot’s capabilities when it comes to parsing date/time information depend on the capabilities (and sensibilities) of the underlying system libraries. Don’t expect edge cases to be absolutely portable!

Output

Compared to parsing time/date information, it’s much easier to format the information into human-readable tic labels. To do so, specify the desired output format using set _tics format "..." (where the underscore again is a placeholder for any of the possible prefixes from table 8.1), and you’re done.^[16]

¹⁶

I also recommend that you avoid the former way of formatting tic labels based on the set format command. The new style, based on set xtics format, is both clearer and more robust.

The format string can contain arbitrary text in addition to the formatting characters. Here’s a useful snippet to stack the time on top of the date (note the embedded newline):

But you can also use other text, such as formatting characters

and even plain text:

In particular when used together with string functions, there is almost no limit to the appearance of tic labels for plots displaying time series.

Working in time-series mode

Keep in mind that when working in time-series mode (after issuing the set xdata time command), all x coordinates are interpreted according to the current setting of the set timefmt format option (or equivalent for all other axes). In particular, this means plotting ranges must be specified as quoted strings, in the format defined by timefmt (the input time format): plot ["01Jan00":"15Jan00"] "data" u 1:2. Similar concerns hold for the coordinates supplied to set arrow and set label.^[17]

¹⁷

Alternatively, you can specify ranges and positions as integers, which are interpreted as Unix epoch seconds.

Also, don’t forget that the currently selected locale (as inherited from the environment when gnuplot was started, or set using set locale) affects the tic labels (names of months and of days in the week).

And finally, always remember that you need to switch on time-series mode explicitly using set xdata time. This necessary step is easy to forget, and doing so will lead to mysterious errors.

Tip

Before parsing date/time information from files and using it to plot data, you must enable time-series mode using set xdata time.

A worked example

Remember the file with monthly data from listing 8.9? In section 8.3.5, gnuplot read the tic labels for the horizontal axis directly from the data file. In section 8.4.1, the plot was created using the simple set xmtics formatting. Now you’ll see a third way of plotting the file, this time using the full machinery of gnuplot’s general time-series mode.

The next listing shows one way to do it. In this version, the strings in the third column aren’t used. (See tables 8.4 and 8.5 for the conversion specifiers.) The resulting graph is exactly the same as figure 8.7.)

Listing 8.11. Commands for figure 8.7 using time-series mode (file: months1.gp)

Amusingly, there’s another way to achieve the same effect. Remember that the data in listing 8.9 is redundant: the first and third columns both contain information that can be interpreted as months. You can therefore ignore the first (numeric) column and base the graph on the third column. The following listing shows this approach.

Listing 8.12. Alternative commands for figure 8.7 (file: months2.gp)

Notice how the strings in the third column are used to give the horizontal position for each point. (You may want to change the output format to full, rather than abbreviated, month names using set xtics format "%B" to convince yourself that the strings read from the file are actually parsed and interpreted and aren’t just passed through to the graph.)

8.4.3. Beyond tic labels: processing date/time information

The functionality I just described for use with time-series plots can be extended to more general applications. Most date/time manipulations involve the first three functions in table 8.6.

Table 8.6. Functions to parse and format arbitrary time strings. See tables 8.4 and 8.5 for conversion specifiers.

As an example, consider again the list of athletic records in listing 3.1. This data set contains not only the finishing times, but also the calendar date when the record was set. You may want to include this information in a plot of the data (see figure 8.8).

Figure 8.8. Men’s world records, together with the date when the record was set. The dates are read from the data file, reformatted, and placed onto the graph. See the text for details and listing 3.1 for the data.

This plot command to create this figure is shown here:

plot [0:1200] "records"
            u 1:2:(strftime( "%d %b %y", timecolumn(4, "%Y-%m-%d")))
            w labels point pt 7 offset 0,-1

The primary plot style is with labels (see section 6.3.5), using the ability to plot a point symbol together with the label. The labels are first parsed (using timecolumn()) and then formatted (using strftime()). Notice that the date format in the graph is different than in the data file—the date strings are parsed and reformatted, not merely passed through to the plot.

Instead of using the timecolumn() function, you can use strptime() in conjunction with the basic stringcolumn() function:

plot [0:1200] "records"
            u 1:2:(strftime("%d %b %y", strptime("%Y-%m-%d", strcol(4))))
            w labels point pt 7 offset 0,-1

This example will suffice to demonstrate the possibilities. Keep in mind that timecolumn() and strptime() return a numeric representation of a timestamp, thus making all kinds of further date calculations and manipulations possible.

8.5. Summary

In this chapter, we talked about all the ways you can control the appearance of the axes on a plot. It’s been a long chapter, but axes—or rather, the tic marks and labels placed on them—are important: they enable the viewer to gain quantitative insight from the data displayed in the plot.

This chapter concludes our overview of what I would call “basic” gnuplot. In the following chapters, we’ll look at some exciting but distinctly more advanced topics, such as color in graphs, customizations, and scripting capabilities. You’ll also learn just about everything there is to know about exporting graphs to standard file formats.