Better aliases for specifying axes

[adigitoleo]

Here is an attempt at summarizing the following ideas. I propose the following changes to frame:

• Make frame throw an error when it would construct an illegal -B flag due to missing annot or ticks
• Make the default axes behaviour of frame the same as the overall axes default
• Add convenient aliases for common multi-axes setups like axes = :full for drawing all axes with automatic annotation and ticks

---

This example is from the GMT tutorial session 1 no. 3 link. I tried three different ways of specifying the axes which I think should be equivalent, but one of them constructs an incorrect -B flag.

function tutorial3()
    coast(
        region = (-90, -70, 0, 20),
        proj = :Mercator,
        figsize = "6i",
        # frame = (axes = (:left_full, :bottom_full, :right_full, :top_full)),  # doesn't work
        frame = (axes = :ESWN),  # works
        # axes = :ESWN,  # works
        land = :chocolate,
        show = true,
        Vd = 1,
    )
end

Output from the one that doesn't work:

pscoast  -R-90/-70/0/20 -JM6i -B(:left_full, -B:bottom_full, -B:right_full, -B:top_full) -Gchocolate -Da -P -K > /tmp/GMTjl_tmp.ps

First, it would be good to fix the verbose case. In general, maybe it would also be nice to be able to write it like this:

function tutorial3()
    coast(
        region = (-90, -70, 0, 20),
        proj = :Mercator,
        figsize = "6i",
        axes = :full,  # new alias, same as :ESWN
        land = :chocolate,
        show = true,
        Vd = 1,
    )
end

I propose nine new axes aliases in total:

• :full as above
• :full_horizontal == :NS
• :full_vertical == :WE
• same as above, but for ticks_ and bare_

Let me know what you think.

[adigitoleo]

OK, so I figured out that to use the verbose syntax I have to add annot = :auto (and ticks = :auto).

function tutorial3()
    coast(
        region = (-90, -70, 0, 20),
        proj = :Mercator,
        figsize = "6i",
        # frame = (axes = (:left_full, :bottom_full, :right_full, :top_full)),  # error, see OP
        # frame = (axes = (:left_full, :bottom_full, :right_full, :top_full),),  # -BWSEN
        # frame = (
        #     axes = (:left_full, :bottom_full, :right_full, :top_full),
        #     annot = :auto,
        # ),  # -Bpa -BWSEN
        frame = (
            axes = (:left_full, :bottom_full, :right_full, :top_full),
            ticks = :auto,
            annot = :auto,
        ),  # -Bpaf -BWSEN
        # frame = (axes = :WESN),  # -BWESN -Baf
        # axes = :WESN,  # -BWESN -Baf
        land = :chocolate,
        show = true,
        Vd = 1,
    )
end

In that case, I suggest to throw julia errors when frame is misused like in the first example. We will need to collect all of the allowed combinations to frame to do this.

The question is, should my proposed aliases implement -Bpaf or -Baf or -Bpa. To be consistent with the current syntax, I think that e.g. axes = :full should produce -Baf. The idea would be to reduce the usage of :auto, which seems to be an unfortunate inheritance from upstream GMT.

[adigitoleo]

One more suggestion for making the behaviour more consistent: Currently, when frame is used, it "resets" the GMT.jl default from the equivalent of (:left_full, :bottom_full) to the equivalent of (:left_full, :bottom_full, :right_full, :top_full). In other words, using frame changes which axes are annotated by default. Maybe it would be less surprising if the default axis settings were standardised across the API. I agree that left and bottom (full) axes are a good idea, can we make frame = ... do this by default too, if no axes are provided?

[joa-quim]

Thanks for the thoughts put on this. It's really useful to have the users perspective ... specially on the horribly complicated -B option 😃

I'm a bit busy right now (we'll have a GMT course starting tomorrow) so won't go through all of your points. Anyway, they were many so we probably should split this to not leave some out.

• Quickly: frame=:auto => very simple to implement (already done, will commit soon).

• Make frame throw an error when it would construct an illegal -B flag due to missing annot or ticks

  Very hard/impossible to implement (only GMT knows that). What I can do is to try to parse always correct option.

• Make the default axes behaviour of frame the same as the overall axes default

  Not sure to get what you mean by this. You mean in axes = (axes = ...., ...) drop the first axes?

frame = (axes = (:left_full, :bottom_full, :right_full, :top_full)) # doesn't work

It doesn't because of an user error. I hate this and see many people falling in the same trap but have no means to avoid it. The problem is that Julia is not seeing it as a NamedTuple and so it dropped the axes keyword and only saw:

frame = (:left_full, :bottom_full, :right_full, :top_full)

It's frustrating but one really must follow the language rules. It works if we add a comma to make it a NamedTuple

frame = (axes = (:left_full, :bottom_full, :right_full, :top_full), )   # Works

Note, I've added a themes function that allows some more control on the default axes (per theme) and worked a lot in the function that parses the option -B (parse_B()). Some of that work is so far only in the #master branch, so it would be better if you use #master.

[adigitoleo]

@joa-quim Thanks for the responses, that already clears up many things (for some reason it didn't occur to me that frame must be a NamedTuple!). I think I'll close this and check out master for the new aliases.

I'll move the remaining point about axes defaults to a new issue.