What's the most Pythonic way for long GMT arguments?

[seisman]

For each GMT option, PyGMT usually provides a long-form parameter. For example, GMT CLI option -B is equivalent to frame in PyGMT. This is done by the alias system (the use_alias decorator), which automatically converts long-form PyGMT parameters to short-form GMT options. The alias system works well but has known limitations and issues (e.g., #256, #262).

Sometimes, GMT arguments are still specified using long unreadable strings. For example,

• projection="S0/90/12c": related to Create Projection classes instead of strings #356, Implement Projection classes to encapsulate arguments #379
• frame=["WSen", "xaf+lXLABEL", "yaf+lYLABEL"]: related to Better way to configure axis (instead of B/frame) #249

As these common options are used a lot, we may take some time to find and implement a more Pythonic way to specify projection, frame et al.

However, there are still a lot of other long GMT arguments. Here is a simple example showing how to plot a GMT logo on maps.

import pygmt

fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 2], projection="X6c", frame=["WSen", "xaf", "yaf"])
fig.logo(position="jTR+o0.3c/0.6c+w3c", box="+p1p+glightblue")
fig.show()

The above Python script is equivalent to the following GMT CLI script:

gmt begin
gmt basemap -R0/10/0/2 -JX6c -B
gmt logo -DjTR+o0.3c/0.6c+w3c -F+p1p+glightblue
gmt end show

The long argument for position and box are really difficult to remember and write. There are definitely some better and more Pythonic ways to specify these arguments. As GMT has too many options, we must provide a universal way to specify these long arguments.

Perhaps the simplest way is to pass these long arguments as dict, i.e.,

fig.logo(
    position={
        location: "jTR",
        offset: [0.3, 0.6],
        width: "3c",
    },
    box={
        pen: "1p",
        fill: "lightblue"
    }
)

Are there any better ways?

[weiji14]

This has come up again and again in different forms, so I've started a project at https://github.com/GenericMappingTools/pygmt/projects/6 to track the various issues and PRs tackling this. Let's make this issue the central point to gather all the ideas. Here's my attempt at summarize the various candidates (feel free to edit this comment anyone, or suggest alternatives)

Dictionary

Pass the arguments into the parameter as a Python dictionary. E.g. at #262 (comment), #1082 (comment)

fig.logo(position={location: "jTR", offset: [0.3, 0.6], width: "3c"})

Pros: Appears easy to implement, sort of intuitive for new Python users
Cons: Parameters like location/offset/width cannot be tab-completed, every PyGMT module will need to be updated to handle these dict inputs

Functions

Expand the PyGMT module's keyword argument list to specify every possible parameter. E.g. at #1173 (comment)

fig.logo(position_location="jTR", position_offset=[0.3, 0.6], position_width="3c")

Pros: Can tab-complete inside PyGMT module, more discoverable by new users
Cons: May result in long list of parameters to scroll through, will need to be added to docstring of every module
Note: if it's a one-off thing though, this functional style might be suitable, e.g. for the text 'paragraph' option at #1078 (comment)

Classes

Set up a dedicated PyGMT Python class to handle the parameter/arguments. E.g. at #356 (comment), #262 (comment).

position = pygmt.param.Position(location="jTR", offset=[0.3, 0.6], width="3c")
fig.logo(position=position)

Pros: Can be tab-completed, only need to implement once and be used throughout all PyGMT modules, can plug into existing workflow
Cons: May not be as discoverable by new users, will be a bit harder to program up front

---

Yes, my preference is for the 'Classes' option, so I'll elaborate on it a bit more. The main idea is to have a params.py file with lots of pygmt.param.Abcde classes (or some other name). E.g.:

• pygmt.param.Frame (-B, Better way to configure axis (instead of B/frame) #249)
• pygmt.param.Position (-D, What's the most Pythonic way for long GMT arguments? #1082)
• pygmt.proj.Orthographic (-J, Implement Projection classes to encapsulate arguments #379)

Implementation (of pygmt.param.ClassName)

It's been mentioned at #249 (comment) and attempted for e.g. at #379, but I'll summarize the idea again. A class like pygmt.param.Pen for example, will need to have a __str__ method to produce the correct -W argument to be passed into pen:

pen = pygmt.param.Pen(width="1p", color="blue", style="-")
print(pen)
# 1p,blue,-

Since PyGMT has adopted NEP29 #1074 and is Python 3.7+ now, we can use Python dataclasses to implement this (see https://realpython.com/python-data-classes), and this means less boilerplate when coding things up (compared to traditional Python classes).

TLDR: Let's start small-ish, e.g. @willschlitzer's issue on pen (-W) at #1173 will be a great start, and we can work out the implementation details along the way.

[seisman]

The "Classes" option sounds the best way, but we need to think about a general way to implement classes for all options.

[maxrjones]

I agree that the classes option is good. I have a couple further opinions about the implementation of long GMT arguments:

1. Based on this discussion, we will implement full-word modifiers for GMT arguments in the PyGMT library independently of the planned effort to support long-option modifiers in core-GMT (see https://docs.generic-mapping-tools.org/dev/devdocs/long_options.html and the newly added project https://github.com/GenericMappingTools/gmt/projects/1). I agree with this decision but would like to see a system for ensuring consistent attribute names throughout the GMT ecosystem. So far, only GMT.jl has implemented long-format for both GMT options and modifiers (https://www.generic-mapping-tools.org/GMT.jl/dev/quick_learn/#Case-2.-You-are-a-new-GMT-user-or-one-that-wants-to-use-long-verbose-options). My opinion is that it will help GMT sustainability in the long run if all the GMT-related projects are consistent with at least the names of the modifiers even if the implementation is different. Do others think this is something worth tracking?
2. I would prefer to use a different method than __str__ to format into GMT style, such that print gives user-readable information rather than the sometimes convoluted GMT syntax.

[weiji14]

I agree that the classes option is good. I have a couple further opinions about the implementation of long GMT arguments:

1. Based on this discussion, we will implement full-word modifiers for GMT arguments in the PyGMT library independently of the planned effort to support long-option modifiers in core-GMT (see https://docs.generic-mapping-tools.org/dev/devdocs/long_options.html and the newly added project https://github.com/GenericMappingTools/gmt/projects/1). I agree with this decision but would like to see a system for ensuring consistent attribute names throughout the GMT ecosystem. So far, only GMT.jl has implemented long-format for both GMT options and modifiers (https://www.generic-mapping-tools.org/GMT.jl/dev/quick_learn/#Case-2.-You-are-a-new-GMT-user-or-one-that-wants-to-use-long-verbose-options). My opinion is that it will help GMT sustainability in the long run if all the GMT-related projects are consistent with at least the names of the modifiers even if the implementation is different. Do others think this is something worth tracking?

Yep, we should definitely have standardized aliases across all GMT wrappers. There was a lot of discussion around this in 2019/2020 on GitHub and the GMT forum (e.g. https://forum.generic-mapping-tools.org/t/standardized-human-readable-gmt-parameters-for-pygmt-matlab-julia-pyshtools-etc/77) but the conversation stalled for some reason, so thanks for picking this up again and starting the project to keep track!

2. I would prefer to use a different method than __str__ to format into GMT style, such that print gives user-readable information rather than the sometimes convoluted GMT syntax.

This can be arranged. We can have both a __str__ and __repr__ method in the pygmt.param.ClassName class (see https://stackoverflow.com/questions/1436703/what-is-the-difference-between-str-and-repr), one which is human-readable (for the user), and one which is machine-readable (for GMT 😛). I'll work on it in the RFC PR at #1239.

Edit: Actually, Python 3.7 data classes already implements a __repr__ method (see https://realpython.com/python-data-classes/#basic-data-classes). So the current implementation at #1239 does the following:

pen = pygmt.param.Pen(style=".-.-", color="120-1-1", width="0.5c")

str(pen)  #'0.5c,120-1-1,.-.-'
print(pen)  # 0.5c,120-1-1,.-.-
repr(pen)  # "Pen(width='0.5c', color='120-1-1', style='.-.-')"
pen  # Pen(width='0.5c', color='120-1-1', style='.-.-')

For the last one, simply putting pen at the end in a Jupyter cell would give the information-rich __repr__ representation of the Pen object, same as calling repr(pen). Calling str(pen) or print(pen) would give the GMT style string. It sounds though that you prefer it to be the other way around @meghanrjones?

[maxrjones]

Yep, we should definitely have standardized aliases across all GMT wrappers. There was a lot of discussion around this in 2019/2020 on GitHub and the GMT forum (e.g. https://forum.generic-mapping-tools.org/t/standardized-human-readable-gmt-parameters-for-pygmt-matlab-julia-pyshtools-etc/77) but the conversation stalled for some reason, so thanks for picking this up again and starting the project to keep track!

Cool, this is on the agenda to discuss at the next GMT community meeting. Of course, we could also discuss at the next PyGMT meeting in case anyone is unavailable May 6.

For the last one, simply putting pen at the end in a Jupyter cell would give the information-rich __repr__ representation of the Pen object, same as calling repr(pen). Calling str(pen) or print(pen) would give the GMT style string. It sounds though that you prefer it to be the other way around @meghanrjones?

Yes, but I could be convinced elsewise if others feel strongly that __str__ should be used for the GMT readable formatting.