Standardized human-readable gmt parameters for pygmt/matlab/julia/pyshtools/etc

Many projects are building on the base functionality of gmt, and these often introduce a large number of human-readable parameters. Ideally, it would be useful if we as a community could try to standardize the syntax among the various gmt-related projects.

In creating a plotting routine for my pyshtools project, I needed to define parameters related to projections, annotations, colorbars, ticks, etc. What I came up with might not be idea, so I would be more than happy to modify these based on what other people are using.

  • projection : The name of a global or hemispherical projection (see Notes). Only the first three characters are necessary to identify the projection.
  • region : The map region, consisting of a list [West, East, South, North] in degrees. The default ‘g’ specifies the entire sphere.
  • width : The wdith of the projected image.
  • unit : The measurement unit of the figure width and shift_origin: ‘i’ for inches or ‘c’ for cm.
  • longitude : The central meridian or center of the projection.
  • latitude : The center of the projection for some hemispheric projections.
  • grid : If True, plot grid lines.
  • grid_interval : Grid line interval [latitude, longitude] in degrees.
  • annotate : If True, plot annotation labels on axes.
  • annotate_interval : Annotation label interval [latitude, longitude] in degrees.
  • ticks : If True, plot ticks on axes.
  • tick_interval : Tick interval [latitude, longitude] in degrees.
  • axes : Specify which plot axes should be drawn and annotated. Capital letters draw the axes, ticks, and annotations, whereas small letters draw only the axes and ticks.
  • title : The title to be displayed above the plot.
  • cmap : The color map to use when plotting the data and colorbar.
  • cmap_reverse : Set to True to reverse the sense of the color progression in the color table.
  • continuous : If True, create a continuous colormap. Default behavior is to use contant colors for each interval.
  • limits : A list containing the lower and upper limits of the data to be used with the color map, and optionally an interval.
  • colorbar : If True, plot a colorbar.
  • cb_orientation : Orientation of the colorbar; either ‘h’ or ‘v’ for horizontal or vertical, respectively.
  • cb_triangles : Add triangles to the edges of the colorbar for background ‘b’ and/or foreground ‘f’ colors.
  • cb_label : Text label for the colorbar.
  • cb_ylabel : Text label for the y axis of the colorbar
  • cb_annotate : If True, plot annotation labels on the colorbar.
  • cb_annotate_interval : Annotation interval on the colorbar.
  • cb_ticks : If True, plot ticks on the colorbar.
  • cb_tick_interval : Colorbar tick interval.
  • shift_origin : Offset of the plot in the x and y directions from the origin.
  • fname : If present, save the image to the specified file.

Not sure I fully understand this. Are you thinking in the things mentioned in #254 and started in the longoptionsparsing branch?

An in GMT.jl a couple hundred of those have been started as well.

This example code from GMT.jl readme demonstrates the problem:

coast(region=:global, proj=:Winkel, frame=:g, area=10000,
      land=:burlywood4, water=:wheat1, figsize=12, show=true)

From the list I gave above, region has the same meaning, but julia uses proj whereas I used projection, and julia used frame whereas I used axes.

The Julia wrapper accepts several aliases. You have to consult the (existing) documentation.
For example for option -J and -B you’ll see that both projection and axes are also supported keywords.

Most of modules do not have yet a manual but on Julia one can ask the online help by typing ? modulename and it will print the available aliases (though some need updating). Since GMT.jl was the first to name the keywords I suggest that you follow them. And bring to discussion any that you think it would be better to name differently.

The longoptions branch intends to come up with an official set of keyword names but while it doesn’t exist the julia set is the most extended one. AFAIK the pygmt keyword names are equal or at least intercept those of GMT.jl.