Create Projection classes instead of strings

[leouieda]

Description of the desired feature

The Figure methods take a projection argument that is using the same arguments as GMT -J ("M10i" for Mercator 10 inches). But a lot of projections have many arguments and it's impossible to remember them all. A relatively simple alternative would be to implement classes (based on a single Projection class maybe) that take the projection arguments in the constructor (and so allows tab-completion). The key would be for these classes to define a __str__ method so that when str is called on them, they produce the GMT -J code. For example:

>>> proj = pygmt.Orthographic(central_longitude=10, central_latitude=52, width=10)
>>> print(str(proj))
G10/52/10

The plotting method pre-processing would only have to call str on projection, which works fine if you pass in a string as well.

Are you willing to help implement and maintain this feature? Yes but I'd welcome anyone else who wants to try :)

[weiji14]

@leouieda, just mentioning that @MarkWieczorek has done some side work here to parse a human readable projection name into a GMT compatible projection string. It would be good to combine efforts and have that in-house in PyGMT.

Also had a thought about the implementation aspect of this, and it feels like dataclasses would be a nice way to go. It's meant for Python 3.7+ but there's a backport to Python 3.6 at https://github.com/ericvsmith/dataclasses we could pull in. Alternatively, we could use good ol' classes, namedtuples, or maybe the attrs library.

Not sure if it's better to have pygmt.Orthographic() or pygmt.Projection(projection="orthographic"). The first one might clutter up our namespace. Or maybe we could do pygmt.Projection.orthographic? I'd take a look at cartopy.

[leouieda]

@weiji14 I would prefer to avoid having to use a backport as that complicated the packaging quite a bit by introducing different dependencies on different Python versions. This is such a light weight implementation that attrs is probably the best tool for the job.

The problem with pygmt.Projection(projection="orthographic") is that projections take slightly different parameters so this implementation would have to use **kwargs which can't be tab-completed (negating the effect of having the class in the first place). With pygmt.Orthographic(), the projection name and arguments can be tab-completed.

To avoid cluttering the namespace, I'd be fine with bundling them in a submodule like pygmt.projection.Orthographic(). That makes it easier to find as well since you can type pygmt.projection.<TAB> and get a list of all projections.

[leouieda]

I definitely like @MarkWieczorek's names for the projections. Though since we have classes they should be CamelCase.

[weiji14]

Ok noted - basically do pygmt.projection.Xxxxx(). I'll see if I can get some people to work on this in about 12 hours at the FOSS4G Oceania Community Day.

[sixy6e]

Hi everyone, I'm just having a quick exploration into this issue whilst at the FOSS4G Oceania Community Day.

I think attrs is a good idea, so I'll prototype out something over the weekend and see what you think. I have used attrs in a similar fashion to what is being described in this issue.

[sixy6e]

I've put together a working prototype for a dozen of the 31 supported GMT projections. You can find the code here (I can do an initial PR as a WorkInProgess if that's easier for an initial review and discussion).

What it enables:

• pygmt.projection.Xxxxx()
• listing of supported projections

list(pygmt.projection.Supported)

• Automatic conversion to GMT's string format via str
• Keyword arguments that can be validated eg latitude/longitude bounds, horizon limits etc, (currently I've only added validators for the horizon argument).

For any parameters listed as optional on GMT, such as horizon, I've set defaults based on the examples in the pygmt gallery.

The Enum class Supported has multiple purposes such as easy listing of supported projections it also enables a simpler comparison of projection labels. eg

>>> a = Supported.LAMBERT_AZIMUTH_EQUAL_AREA
>>> a == a
True
>>> b = Supported.EQUIDISTANT_CONIC
>>> a == b
False

If such comparisons are desired elsewhere in the code, an additional attribute can be added to the Projection class, thus allowing the Projection class to be carried around to other parts of the pygmt ecosystem.
Each enum instance also contains the projection name and the GMT code as given in GMT.

>>> a = Supported.LAMBERT_AZIMUTH_EQUAL_AREA
>>> a.name
LAMBERT_AZIMUTH_EQUAL_AREA
>>> a.value
A

Anyway, take a look and see what you think. From the descriptions in this thread, it is pretty close to the desired outcomes. If it is along the lines of what you're after I can open up a PR and finish the rest of it off.

Just to note, the names for the keyword arguments have come directly from GMT. These can easily be changed to central_longitude, central_latitude, etc.

[weiji14]

Good work @sixy6e, you must have taken a lot of time over the weekend to get this up! I've taken a quick look already, and I do like the default arguments, but we'll need to discuss that with the rest of the team. Also, the central_longitude does looks better than lon0, and I just realized that the Julia wrapper has done some work already on Map projections and we might want to coordinate a bit on those keyword argument names.

Definitely recommend opening up a draft Pull Request so that we can comment on individual lines of the code and follow up on the discussion there. Before you do that though, have a quick look over our Contributing Guidelines. In particular, you might want to run make format to Black format the code (it's designed to make code diffs more minimal).

[MarkWieczorek]

Just a couple minor comments:

1. I would probably use central_longitude and central_latitude, but then also define center which has the default value of [central_longitude, central_latitude]
2. For the width parameter, I would also define an optional unit parameter, which could be either i (default) or c. The gmt width string would then be str(width) + unit.
3. My preference would be to used mixed case for the projection names, instead of upper case. For ease of use, it might be useful to define purely lowercase and uppercase names as aliases.
4. Lastly, I think it would be useful to define short name aliases for the projections. The julia project already has given an initial try at this, and the majority of their aliases are good.

[sixy6e]

Thanks for the feedback @weiji14 and @MarkWieczorek
I'll make the changes to use central_longitude and central_latitude instead of lon0 and lat0.
With center, I'll write it so that the attribute gets created post init, and is then not required to be input by the user.
I was thinking last night that the Enum Supported, is probably better to be called GMTCodes, as it acts as a reference to the shorthand (mostly single character) codes that GMT uses, but I'm open to suggestions. Enum's themselves are typically UPPERCASE to make it clear that they're constants, but by no means, are you forced to follow it either.

[MarkWieczorek]

I only mentioned center because it appears that the Julia-gmt project uses this instead of separate variables for the latitude and longitude. I think that it might be useful to accept either center or both central_longitude and central_latitude.

[leouieda]

@sixy6e thank you for doing all of this!

I was thinking last night that the Enum Supported, is probably better to be called GMTCodes, as it acts as a reference to the shorthand (mostly single character) codes that GMT uses, but I'm open to suggestions.

What is the rationale for the Supported class? I feel like that is a tab-complete or documentation lookup away. I kind of want to stay away from the single character codes altogether. Ideally, we should support all GMT projections so it's only a matter of time before Supported is obsolete. In that case, is it worth adding all the code (and tests/documentation) required?

I'll leave some more comments in #379.

@MarkWieczorek a few comments to your points:

I would probably use central_longitude and central_latitude, but then also define center which has the default value of [central_longitude, central_latitude]

I really don't like having two arguments for setting the same thing. That makes documentation and testing much more complicated than it needs to be and is confusing for new users. I see the appeal of center but the problem is that not all projections take both central_latitude and central_longitude. So there is no way of center being consistent, which is why I prefer central_latitude and central_longitude.

For the width parameter, I would also define an optional unit parameter, which could be either i (default) or c. The gmt width string would then be str(width) + unit.

That is a great idea! I have having to specify a string for something that should be a number ("10c"). Having a unit="c" in the projections is great!

My preference would be to used mixed case for the projection names, instead of upper case. For ease of use, it might be useful to define purely lowercase and uppercase names as aliases.

Classes should always be CamelCase but module-level constants are UPPER_CASE.

Lastly, I think it would be useful to define short name aliases for the projections. The julia project already has given an initial try at this, and the majority of their aliases are good.

I'm firmly against this. The main point of having these classes is to be explicit with the projection names. Having short lowercase class names breaks the naming conventions. For short-hand, users can always pass projection="W180/10c" instead of using the classes. Plus, there is always tab-completion to avoid typing long names.