Time/Date data

gnuplot supports the use of time and/or date information as input data. This feature is activated by the commands set xdata time, set ydata time, etc.

Internally all times and dates are converted to the number of seconds from the year 1970. The command set timefmt defines the default format for all inputs: data files, ranges, tics, label positions – anything that accepts a time data value defaults to receiving it in this format. Only one default format can be in effect at a given time. Thus if both x and y data in a file are time/date, by default they are interpreted in the same format. However this default can be replaced when reading any particular file or column of input using the timecolumn function in the corresponding using specifier.

The conversion to and from seconds assumes Universal Time (which is the same as Greenwich Standard Time). There is no provision for changing the time zone or for daylight savings. If all your data refer to the same time zone (and are all either daylight or standard) you don't need to worry about these things. But if the absolute time is crucial for your application, you'll need to convert to UT yourself.

Commands like show xrange will re-interpret the integer according to timefmt. If you change timefmt, and then show the quantity again, it will be displayed in the new timefmt. For that matter, if you reset the data type flag for that axis (e.g. set xdata), the quantity will be shown in its numerical form.

The commands set format or set tics format define the format that will be used for tic labels, whether or not input for the specified axis is time/date.

If time/date information is to be plotted from a file, the using option must be used on the plot or splot command. These commands simply use white space to separate columns, but white space may be embedded within the time/date string. If you use tabs as a separator, some trial-and-error may be necessary to discover how your system treats them.

The time function can be used to get the current system time. This value can be converted to a date string with the strftime function, or it can be used in conjunction with timecolumn to generate relative time/date plots. The type of the argument determines what is returned. If the argument is an integer, time returns the current time as an integer, in seconds from 1 Jan 1970. If the argument is real (or complex), the result is real as well. The precision of the fractional (sub-second) part depends on your operating system. If the argument is a string, it is assumed to be a format string, and it is passed to strftime to provide a formatted time/date string.

The following example demonstrates time/date plotting.

Suppose the file "data" contains records like

03/21/95 10:00  6.02e23

This file can be plotted by

set xdata time
set timefmt "%m/%d/%y"
set xrange ["03/21/95":"03/22/95"]
set format x "%m/%d"
set timefmt "%m/%d/%y %H:%M"
plot "data" using 1:3

which will produce xtic labels that look like "03/21".

Gnuplot tracks time to millisecond precision. Time formats have been modified to match this. Example: print the current time to msec precision

print strftime("%H:%M:%.3S %d-%b-%Y",time(0.0))
18:15:04.253 16-Apr-2011

See time_specifiers.

Copyright 1986 - 1993, 1998, 2004 Thomas Williams, Colin Kelley
Distributed under the gnuplot license (rights to distribute modified versions are withheld).