Disallow single character arguments

leouieda commented 5 years ago

Description of the desired feature

A major usability problem for GMT are the complex and cryptic single character arguments and modifiers. This is why we implemented the entire alias system in GMT/Python (which is making its way back into GMT 6). Our docs all encourage using the long form names and this is not strange in the Python ecosystem. Since we're actively discouraging the use of B and the like, why are we maintaining the capability of doing so? Hardcore GMT users who value brevity are not our target audience. And if you're using Jupyter or any modern text editor, tab completion eliminates the hassle of longer names (which we currently can't use because of the alias system).

I propose getting rid of the single letter arguments all together.

Doing this will allow us to:

Define functions arguments normally in the Python functions instead of relying on **kwargs.
Get rid of the use_alias decorator and replace it with a translator function that's called inside the function body. This functions would be a lot easier than the decorator to maintain (which is an ugly function inside a function inside a function).
Use tab completion for the long argument names
Simplify the testing a lot but not needing to test the aliases

The one downside I see that we will have to fully implement all arguments in order for them to be used (like X and Y, etc). But we were gonna have to do this eventually any way.

I'd love to get some feedback on this.

leouieda commented 5 years ago

Pinging @GenericMappingTools/gmt-python @liamtoney @weiji14 @akshmakov @mjziebarth

seisman commented 5 years ago

GMT is trying to implement long-form options, see https://github.com/GenericMappingTools/gmt/pull/230.

If it's merged, we no longer need use_alias anymore.

leouieda commented 5 years ago

Yep. We'll still need to parse and do some conversion on the arguments, though.

liamtoney commented 5 years ago

What would be the Pythonic implementation of the numerous modifiers that follow option arguments, i.e. the Python version of

--longoption[=[<directive>:]<arg>][+<mod1[=<arg1>]][+<mod2[=<arg2>]]...

as given in GenericMappingTools/gmt#230?

The more complex cases could be tricky — and they do come up. For example, I recently wrote something like the following to produce a frame overlay with map scale:

fig.basemap(frame='af', L='g{0}/{1}+w100k+c{0}/{1}+l'.format(*SCALE_LOC))

I guess when I think of an optimal solution as an end user, dictionaries of modifiers come to mind (see the docs for the option):

fig.basemap(frame='af', scale=dict(
                   location_type='g',
                                   location=SCALE_LOC,
                                   length=100,
                                   unit='k',
                                   reference_coordinates=SCALE_LOC,
                                   label=True
                                   )

Wrapping would take some time, though...

leouieda commented 5 years ago

@liamtoney that's a good point but it's probably better discussed in a separate issue. We don't have a good answer for that yet. In Julia, @joa-quim is doing something similar to what you suggest. The only problem with that implementation on the Python side is that editors won't be able to tab complete the arguments. This is a bit of a deal breaker for me since it becomes really annoying to type out long names.

A lot of these problems arise from a single argument/module trying to do many different jobs at once. Ideally, we should try to split these up into separate arguments or functions. But it's not trivial where the line needs to be drawn.

I don't think we'll be able to think of every single possibility. The best option is probably to implement the basics with the top-level arguments first. I find that a lot of these usability problems will come up as we write the documentation and often times a better solution presents itself. I'm working on expanding the docs with some tutorials and examples for this reason.

mjziebarth commented 5 years ago

Good idea!

@liamtoney @leouieda Regarding the dict of keywords a small issue highjacking: If classes are autocomplete friendly (I must admit I work using simple text editors), one could also do something like

fig.basemap(frame='af', scale=Scale(location_type='g', location=SCALE_LOC, ...))

That would surely take a lot of work setting up but may be helpful.

leouieda commented 5 years ago

@mjziebarth that was my initial idea but I'd be more prone to using a function instead of a class. The only thing needed is to convert the arguments into a GMT-compatible string, so a class wouldn't really do much besides store the values and define a __str__ method that does the conversion. The benefit of the class is that the documentation might be more straight-forward (the required value of scale would be either a string or a Scale instance). Another advantage is that we can add them as needed and still allow the normal string input. The only problem with this is that it's kind of unnatural to require these objects. But I don't see a good way around it without completely changing the GMT way of doing things.

PaulWessel commented 1 year ago

I think having a post-Covid summit of all of GMT core, PyGMT and Julia/GMT people would be very helpful to discuss some of these issues. I have a bunch of grant funds for us getting together. A smaller chunk ($10k) expires July 2023 or so, so my hope was to find a way to get everybody together ideally before then, but there are more funds for later so not critical. I know that not all are academics and can carve out time, or necessarily want to, but to simplify some of the planning (like where to hold a summit or two), please send me (dont have to post here) your location. If you already know now what part of spring and summer you could carve out 2-5 days then please indicate that too. We cannot give that kind of money back to NSF, Happy New Year!

maxrjones commented 1 year ago

I think having a post-Covid summit of all of GMT core, PyGMT and Julia/GMT people would be very helpful to discuss some of these issues. I have a bunch of grant funds for us getting together. A smaller chunk ($10k) expires July 2023 or so, so my hope was to find a way to get everybody together ideally before then, but there are more funds for later so not critical. I know that not all are academics and can carve out time, or necessarily want to, but to simplify some of the planning (like where to hold a summit or two), please send me (dont have to post here) your location. If you already know now what part of spring and summer you could carve out 2-5 days then please indicate that too. We cannot give that kind of money back to NSF, Happy New Year!

Sounds fun and helpful! pinging @GenericMappingTools/core and @GenericMappingTools/pygmt-maintainers for awareness of your request.

Happy New Year!

michaelgrund commented 1 year ago

I think having a post-Covid summit of all of GMT core, PyGMT and Julia/GMT people would be very helpful to discuss some of these issues. I have a bunch of grant funds for us getting together. A smaller chunk ($10k) expires July 2023 or so, so my hope was to find a way to get everybody together ideally before then, but there are more funds for later so not critical. I know that not all are academics and can carve out time, or necessarily want to, but to simplify some of the planning (like where to hold a summit or two), please send me (dont have to post here) your location. If you already know now what part of spring and summer you could carve out 2-5 days then please indicate that too. We cannot give that kind of money back to NSF, Happy New Year!

Sent an email 😉.

wasjabloch commented 1 year ago

Even though this is in older post, I just discovered it. I'd very much like to make a case for the short term arguments.

For once, the short-term arguments are pretty much in my muscle-memory. I usually edit PyGMT source scripts from within vim and do not always have tab-completion available. It is as if one would substitute :wq for :write-quit.

Furthermore, writing elaborate GMT scripts oftentimes consists of copy-pasting older code, which does just the beautiful thing one figured out ages ago. Abandoning the short-form arguments would deprive me of 5 years of accumulated scripts (as in grep grdimage plot*.sh withing a folder for an old publication). I imagine it would be closer to 15 years for some users. Going into the documentation to see how a specific letter has been translated appears very tedious to me.

Hardcore GMT users who value brevity are not our target audience.

I think it is more then just appreciating breviety. It is more about backward compatibility and efficiency. I'd also like to note that, even as a hardcore GMT user, I much appreciate that I can manipulate data with numpy and xarray and combine it within python right away. (No, I don't like awk, I was just forced to use it for ages).

P.S.: And, yes, all my scripts start with a warnings.filterwarnings("ignore", category=SyntaxWarning), so you can call me ignorant.

joa-quim commented 1 year ago

I do agree with you and posted about that in some other thread that I can't find right now.

yvonnefroehlich commented 1 year ago

I do agree with you and posted about that in some other thread that I can't find right now.

@joa-quim maybe you refer to your post on the GMT forum https://forum.generic-mapping-tools.org/t/pygmt-v0-8-0-released/3577/5?u=yvonnefroehlich?

joa-quim commented 1 year ago

Yes, Yvonne. Thanks.

De: Yvonne Fröhlich @.> Enviado: 18 de março de 2023 09:35 Para: GenericMappingTools/pygmt @.> Cc: Joaquim Manuel Freire Luís @.>; Mention @.> Assunto: Re: [GenericMappingTools/pygmt] Disallow single character arguments (#262)

I do agree with you and posted about that in some other thread that I can't find right now.

@joa-quimhttps://github.com/joa-quim maybe you refer to your post on the GMT forum https://forum.generic-mapping-tools.org/t/pygmt-v0-8-0-released/3577/5?u=yvonnefroehlich?

— Reply to this email directly, view it on GitHubhttps://github.com/GenericMappingTools/pygmt/issues/262#issuecomment-1474788492, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAEDF2PSYXEDDNF3RQP75FTW4V6XHANCNFSM4GQNBFBQ. You are receiving this because you were mentioned.Message ID: @.***>

wasjabloch commented 1 year ago

Upon reading @joa-quim post, I'd like to second his argument for the short-form arguments:

we can (still) tell people: You already know how to use them, just X=“options” instead of -Xoptions

Just last month I suggested to a colleague to dim the background of a figure by using t=60. If t wasn't available, an untrained student would become frustrated and perhaps wouldn't know where to find the information that t has been translated into transparency .

NB: I just mistyped the word transparency and required spell correction. In a script, this would have thrown me an error and diverted me from my original task: doing science. So, an other argument is that the long form arguments are prone to typing errors, especially for non-native English speakers (like me).

I think the bottom line is that, for some people, abandoning short term arguments would be a major nuisance. Please keep them.

GenericMappingTools / pygmt

Disallow single character arguments #262