Realignment of common option for setting 1-D arrays

Added by Paul about 1 month ago

GMT has at least 8 modules that need to set up a 1D output array of sorts. There is some consistency but a few modules do things their own convoluted ways. This proposal tries to eliminate such deviations and standardize the setting of 1D arrays while retaining full backwards compatibility.

What is the problem?

  • Traditionally, these arrays had to be strictly equidistant, meaning we could not have variable spacings such as "month" (or even "year"). Last week, I finally implemented the ability (in gmtmath only) to accept arguments like -T2009T/2016T/2o, which sets up a time-series with output points spaced every two months. Same if year is used (e.g., 1y) since a years's length vary with leap years. This was all implemented by repurposing existing machinery for time and calendar handling when plotting time axes that Walter developed in the early 2000s for GMT4. I would now like to propagate these changes to the other modules but are running into a mix of syntax formats used across these modules.
  • Some modules must also be told which input column is the "time" column and this syntax vary across the modules.
  • Some modules has the option to create a spatial distance-series from x,y locations instead of time and this syntax vary as well.
  • The syntax used to set up the 1D array itself varies across the modules.

What modules are involved?

This is a list of the modules I have found that needs (always or sometimes) to set up 1D arrays, and I make a note of how they do this now:

  1. filter1d: Uses -T<min>/<max>/<inc>[+n] and uses -N to indicate the time column.
  2. gmtmath: Uses -T<min>/<max>/<inc>[+n] and understands calendar units.
  3. gmtregress: Uses -T<min>/<max>/<inc> or -T<n>.
  4. makecpt: Uses -T<min>/<max>/<inc>[+n].
  5. pshistogram: Uses -R (the west/east part) and -W<width>[+l|h|b].
  6. sample1d: Uses -S<start>[/<stop] and -I<inc>[<unit>] and uses -T to specify time column.
  7. gmtflexure: Uses -Q<min/max/inc>[+] for equidistant profile.
  8. talwani2d: Uses -T<min>/<max>/<inc>[+] for equidistant profile.

Comments on module shortcomings

The key problem that needs a discussion before presenting my proposals are pshistogram and sample1d. They have ancient command options that now stand out against the rest.

  • The pshistogram module has a special issue in that -R serves to set both plot domain and the bin domain. The bin increment is set via -W which also has optional modifiers to handle what should happen to data outside -R (added to first and/or last bins, or skip?). Also, because it used -W for bin width we had to introduce -L for pen width despite the fact all other modules use -W for pen width.
  • The sample1d module sets increment separately with -I, and then uses -S for setting min and max; but both have defaults (first and last multiple of inc in range of data). Like filter1d, it needs to be told which column is the time column and it unfortunately uses -T for this whereas filter1d uses -N (as does gmtmath). Note that both filter1d and sample1d can do spatial filtering and sampling where the first two columns are expected to be locations and are used to create distance arrays that then serve as the input "time" array.


All the proposals will be backwards compatible with existing syntax, but documentation and examples going forward will describe new syntax only. The proposed syntax for defining a 1D array on gmt module command lines shall be

-T[<min>/<max>/]<int>[unit|+n] or -T<file>

Since -T is not a GMT standard option the letter used may vary but for most modules will be -T. Furthermore:

  1. The new parser for -T will understand Cartesian, temporal, or geospatial increments, when appropriate for a module.
  2. A new generator will create the 1D array from the parsed information.
  3. pshistogram: If new argument -T is used then -W is only consulted to learn what happens to extreme data outside -T. Now, -R only sets the plot domain. New syntax uses -W for pen and -L for extreme modes, but we are backwards compatible.
  4. sample1d: If new -T is used then old options -I -S -T are not valid. We then need a new option to specify which column is time. I suggest -N<col> since the old -N<knotfile> is replaced by -T<file>.
  5. filter1d: Use new -T with units so that if increment is geospatial then -N modifier to this effect is no longer needed.
  6. In modules where min/max defaults to data range the leading min/max is not required.


  1. All modules will use the same standard machinery and documentation for -T<min>/<max>/<inc>[+n] or -T<file>, and we can support variable time increments like months or years for all modules where time may be used.
  2. Additionally, for filter1d and sample1d:
    1. The use of increment units will dictate if "time" should be distance along track derived from first two columns (e.g., -T0/1000/10k). As in other modules (e.g., mapproject), a leading sign for the increment encodes faster or slower geospatial distance calculations [spherical].
    2. The selection of which column has time will be set via -N<col> in all such modules (gmtmath, sample1d, filter1d)

Replies (1)

RE: Realignment of common option for setting 1-D arrays - Added by Paul 30 days ago

This proposal has now been implemented in r19803. In addition to the issues listed above, I ran into a few other things that had to be resolved along the way:

  1. makecpt can now produce CPTs with a time axis. However, psscale needed to know that when reading the CPT so I added a bit flag to the existing mode so that we can do things correctly in psscale (select time axis and time grid, specifically).
  2. pshistogram also had the awkwardness of using -L to set pen thickness, which is in contrast to pretty much all other models that uses -W. Now that the -W for setting bin width has been subsumed by -T, we now allow -W for pen. Of course, this only is supported with the new syntax and we detect this; otherwise we parse the backwards compatible arguments, including -L , -W and even -T from GMT4.
    All the tests that passed before these changes now pass, as do a few new tests added to deal with the changes. If you run into something that smells of this change, let me know,