List of GMT aliases

[leouieda]

Paul compiled this list of aliases and GMT vocabulary. We should include this somewhere in the docs and in the code somewhere to avoid repetition.

GMT Vocabulary for Python Aliases

The idea is to agree on a set of nouns that can serve as the Python aliases for GMT common options as well as commonly used options (such as pens, color).

Common options:

Option	Alias
B	frame
Bx,By,Bz	axes settings
J	projection, proj
P	portrait [PS only - goes away I think]
R	region
U	timestamp
V	verbosity
X	xshift
y	yshift
b	binary_in, binary_out, binary
d	nodata
e	search
f	coltypes,type?
g	gap
h	header
i	cols_in
n	bc
o	cols_out
p	view
r	reg, registration
s	skip
t	transparency
x	cores

Common themes that could use fixed aliases

Option	Alias
G	fill,color,clip
W	pen, thickness,color,style
C	cpt
F	font=, justification=, offset=,

[weiji14]

Crossreferencing https://github.com/GenericMappingTools/gmt/issues/2079 and https://forum.generic-mapping-tools.org/t/standardized-human-readable-gmt-parameters-for-pygmt-matlab-julia-pyshtools-etc/77. I see that https://github.com/GenericMappingTools/gmt/pull/230 was merged last year (Dec 2019), does that mean there is a standard source for long aliases now?

[seisman]

https://github.com/GenericMappingTools/gmt/pull/230 was merged, but the long name feature is disabled by default. So the feature is still experimental and the long names can still change (for example, GMT uses verbosity, but PyGMT uses verbose for -V).

[maxrjones]

I think we can solve this by adding a link to https://docs.generic-mapping-tools.org/dev/devdocs/long_options.html#common-options in the contributing guide.

[seisman]

Why do we want to add the link in the contributing guide?

Should we just wrap up all aliases in the COMMON_OPTIONS dict?

https://github.com/GenericMappingTools/pygmt/blob/1fb9e2e4e523baaf3aaedb90d71872ede6d03bb7/pygmt/helpers/decorators.py#L15

[maxrjones]

Why do we want to add the link in the contributing guide?

Should we just wrap up all aliases in the COMMON_OPTIONS dict?

https://github.com/GenericMappingTools/pygmt/blob/1fb9e2e4e523baaf3aaedb90d71872ede6d03bb7/pygmt/helpers/decorators.py#L15

Is it decided that the current names of core GMT aliases will be used for all pygmt common aliases? #764 indicated that incols and outcols will be used; there's also distcalc versus spherical and possibly other common options that are wrapped in individual modules rather than decorators.py.

[maxrjones]

I'll start wrapping the other common options and we can discuss alternate names if needed.

[weiji14]

I'll start wrapping the other common options and we can discuss alternate names if needed.

Cool, have a look at other 'Add common alias for XXX) PRs like #994, #853, #662 as a reference. Maybe have a list of what other common option aliases needs to be done and we can split up the workload too.

[maxrjones]

I'll start wrapping the other common options and we can discuss alternate names if needed.

Cool, have a look at other 'Add common alias for XXX) PRs like #994, #853, #662 as a reference. Maybe have a list of what other common option aliases needs to be done and we can split up the workload too.

Yes, I agree. Do you think it's best to post a list in this issue or create separate issues for the remaining common option aliases? My preference would be to create separate issues, because I think tasks are less likely to get lost that way and it would make splitting up the workload easier (people can either self-assign, post that they will be working on it, or open a linked PR).

Edit: the downside would be if the number of open issues is bothersome to anyone - I suspect that it would be at least a handful

[weiji14]

Up to you whether you want to open a separate issue. If it's just a couple, I was thinking that a comment with a tickbox list will do. You could even edit Leo's original comment on the top to keep track of things without scrolling down.

[maxrjones]

Checklist of unwrapped common option aliases

• [x] a - aspatial (#1090)
• [x] b - binary
• [x] d - nodata
• [x] e - find
• [x] g - gap
• [x] h - header
• [x] i - incols
• [x] l - legend
• [x] o - outcols
• [x] s - skiprows
• [x] w - wrap
• [ ] : - switchcols

[maxrjones]

@willschlitzer, do you think that the -i (columns or incols) description could be made general enough to include in COMMON_OPTIONS in pygmt/helpers/decorators.py as part of #1040, rather than adding the alias independently to each method that uses it?

Here's the list of GMT modules that use incols (not all are wrapped as PyGMT methods):

blockmean
blockmedian
blockmode
clip
contour
events
filter1d
fitcircle
gmt2kml
gmtbinstats
gmtconnect
gmtconvert
gmtinfo
gmtmath
gmtregress
gmtselect
gmtsimplify
gmtspatial
gmtsplit
gmtvector
grdedit
grdgdal
grdinterpolate
grdmask
grdmath
grdtrack
histogram
makecpt
mapproject
mask
nearneighbor
plot
plot3d
project
rose
sample1d
spectrum1d
sph2grd
sphdistance
sphinterpolate
sphtriangulate
supplements/geodesy/velo
supplements/potential/gmtflexure
supplements/potential/grdseamount
supplements/potential/talwani2d
supplements/potential/talwani3d
supplements/seis/coupe
supplements/seis/meca
supplements/seis/polar
supplements/seis/pscoupe
supplements/seis/psmeca
supplements/seis/pspolar
supplements/spotter/backtracker
supplements/spotter/gmtpmodeler
supplements/spotter/hotspotter
supplements/spotter/originater
supplements/spotter/polespotter
supplements/spotter/rotsmoother
surface
ternary
trend1d
trend2d
triangulate
wiggle
xyz2grd

[seisman]

do you think that the -i (columns or incols) description could be made general enough to include in COMMON_OPTIONS in pygmt/helpers/decorators.py as part of #1040, rather than adding the alias independently to each method that uses it?

Yes, we should. Docstring of any common options should be included in COMMON_OPTIONS. We should also rename columns to incols.

[maxrjones]

I just started working on the alias for the -b common option. However, I find that I am repeating myself a lot in adding these common options (e.g., typing b="binary" and {b} in every module that uses it). I think it could be better to refactor the use_alias decorator or create a new use_common decorator that automatically adds common option aliases and descriptions from a simple list. But, I have seen in conversations some comments about eliminating use_alias all together. @GenericMappingTools/pygmt-maintainers do you think it is worthwhile to improve the wrapping of common options to better follow a DRY principle? Or is it better to not work on these decorators that may become obsolete.

[maxrjones]

I am closing this issue since all except -: are now listed in COMMON_OPTIONS table. I will open separate issues for adding these options to relevant functions, which will serve as good first issues for new developers.