Skip to content

Time Series Data in GMT

The time (CLOCK) and date (DATE) axis added to GMT is exceptionally flexible but also can be a challenge to get it to function correctly.  There is also no comprehensive documentation on the time and date axis for GMT, so this page attempts to pull that information together into a more usable form and provides samples for generating different types of axis.

Time-series support (from GMT documentation)

GMT can now read and write time-series data where the time coordinates are of the form dateTclock. The formats used for date and clock are under the user's control. Both Gregorian and ISO calendars are supported. Frame annotation for time-series are now supported via the -B option; there are many new modifiers reflecting the vast number of ways one may want to annotate time axes, including support for primary and secondary annotation levels and the day- and month-names in numerous languages (send us the information we need if your language is not supported). The capability to handle time (in -R, -J, -B, i/o, and plotting) required considerable changes "under the hood", including the introduction of numerous new gmt.conf parameters to make the time series support as "generic" as we need it to be.

Setting DATE I/O Format - for year, month, week and day

gmtset INPUT_DATE_FORMAT yyyy-mm-dd

The default date format for GMT is yyyy-mm-dd.  This is used for read and writing dates as well as for labeling plot axis.  The gmtdefault variables INPUT_DATE_FORMAT, OUTPUT_DATE_FORMAT and PLOT_DATE_FORMAT can be used to change the style of I/O dates as needed.  INPUT_DATE_FORMAT controls how dates are read from a file.  OUTPUT_DATE_FORMAT controls how dates are written to a file.  PLOT_DATE_FORMAT controls how dates should be plotted within the EPS file generated by calls to various GMT tools.

The formatting template used for any of these three can be defined using the following options:

  • For Gregorian calendar format:
    • Use  any combination of yyyy (or yy for 2-digit years; if so see Y2K_OFFSET_YEAR), mm (or o for abbreviated month name in the  current  time  language),  and  dd,  with  or  without delimiters.   For day-of-year data, use jjj instead of  mm  and/or  dd.  
    • Examples  can  be  ddmmyyyy,  yy-mm-dd,  dd-o-yyyy, yyyy/dd/mm, yyyy-jjj, etc.    
  • For ISO week calendar format:
    • Expected template is yyyy[--]W[--]ww[--]d, where ww is ISO week and d is ISO week day.  
    • Either  template must  be  consistent, e.g., you cannot specify months if you don't specify years.
    • Examples are yyyyWwwd, yyyy--Www, etc.

Surprisingly the final aspect of formatting dates actually uses the gmtdefault variables TIME_FORMAT_PRIMARY and TIME_FORMAT_SECONDARY.  These variables control how the names of months, weeks and weekdays are formatted for the primary and secondary axis labels, respectively.  Specifically the user must choose among \"full\" (name spelled out completely), \"abbreviated\" (standard abbreviations), and \"character\" (first letter of name) representations.  If the leading f, a, or c of the selection is replaced with F, A, and C, respectively, then the entire annotation will be in upper case.

Setting CLOCK I/O Format - for hours, minutes and seconds

INPUT_CLOCK_FORMAT

Formatting  template that indicates how an input clock string is formatted.  This\               template is then used to guide the reading of clock strings in data  fields.   To\               properly  decode  12-hour  clocks,  append am or pm (or upper case) to match your\               data records. As examples, try hh:mm, hh:mm:ssAM, etc. [hh:mm:ss].

OUTPUT_CLOCK_FORMAT\               Formatting  template that indicates how an output clock string is to be\               formatted.  This template is then used to guide the  writing  of  clock\               strings  in data fields.  To use a floating point format for the small-\               est unit (e.g. seconds), append .xxx, where the number of  x  indicates\               the  desired  precision.   If  no  floating point is indicated then the\               smallest specified unit will be rounded off to  nearest  integer.   For\               12-hour clocks, append am, AM, a.m., or A.M. (GMT will replace a|A with\               p|P for pm).  If your template starts with a leading  hyphen  (-)  then\               each  integer  item  (y,m,d)  will  be  printed  without  leading zeros\               (default uses fixed width formats).  As examples, try hh:mm,  hh.mm.ss,\               hh:mm:ss.xxxx, hha.m., etc. [hh:mm:ss].

Setting TIME I/O Format - for additional display format control

TIME_FORMAT_PRIMARY\               Controls  how  primary month-, week-, and weekday-names are formatted.  Choose among\               \"full\", \"abbreviated\", and \"character\".  If the leading f, a, or c are replaced with F, A,\               and C the entire annotation will be in upper case.

TIME_FORMAT_SECONDARY\               Controls how secondary month-, week-, and weekday-names are formatted.  Choose among\               full, abbreviated, and character.  If the leading f, a, or c are replaced with F, A,\               and C the entire annotation will be in upper case.

Other GMT defaults variables include TIME_EPOCH, TIME_IS_INTERVAL, TIME_INTERVAL_FRACTION, TIME_LANGUAGE, TIME_UNIT, and TIME_WEEK_START. These provide additional control on the functioning of time and date within GMT, but for most applications the default values should suffice.  Use \"man gmtdefaults\" to learn more about each of these global variables.

Establishing Axis Labels and Tick Marks

Defining axis labels, tick marks and even grid lines using time and date requires that new units for the stride are defined.  Available units are presented in the table below.

Variable Definition
Y year, plot with 4 digits
y year, plot with 2 digits
O month, plot using PLOT_DATE_FORMAT
o month, plot  with 2  digits
U ISO week, plot using PLOT_DATE_FORMAT
u ISO week, plot using 2 digits
r Gregorian week, 7-day stride from start of week  TIME_WEEK_START
K ISO  weekday,  plot name of day
D date, plot using PLOT_DATE_FORMAT
d day, plot day of month 0-31 or year 1-366, via PLOT_DATE_FORMAT
R day, same  as  d, aligned  with  TIME_WEEK_START
H hour, plot using PLOT_CLOCK_FORMAT
h hour, plot with 2 digits
M minute, plot using PLOT_CLOCK_FORMAT
m minute,  plot with  2 digits
C second, plot using PLOT_CLOCK_FORMAT
c second, plot with 2 digits

Note

When defining geographic axes, instead of time and date axis, m and c instead mean arc minutes and arc seconds.

Sample Code for Generating Date and Time Axes

Sample 1: Five years with every three months labeled

 gmtset PLOT_DATE_FORMAT o
 gmtset TIME_FORMAT_PRIMARY Character
 gmtset ANNOT_FONT_SIZE_PRIMARY 10p
 psbasemap -JX5/1 -R1990-01-01T/1995-01-01T/0/50 -Bs1Y/WSen -Bpa3Of1o/25f5WSen -P > ! Test1.eps

Sample 2: One year with every two months labeled and every month marked

 gmtset PLOT_DATE_FORMAT o
 gmtset TIME_FORMAT_PRIMARY Abbreviated
 gmtset ANNOT_FONT_SIZE_PRIMARY 10p
 psbasemap -JX5/1 -R1990-01-01T/1991-01-01T/0/50 -Bs1Y/WSen -Bpa2Of1o/25f5WSen -P >! Test2.eps

Sample 3: One month with every ISO week labeled and days marked

 gmtset PLOT_DATE_FORMAT o
 gmtset TIME_FORMAT_PRIMARY Abbreviated
 gmtset ANNOT_FONT_SIZE_PRIMARY 10p
 psbasemap -JX5/1 -R1990-01-01T/1990-02-01T/0/50 -Bs1O/WSen -Bpa1uf1d/25f5WSen -P > ! Test3.eps