Ability to place seismological/geological symbols in legends

[PaulWessel]

Description of the desired feature

Modules like meca, velo, etc. plot advanced symbols in seismology and geodesy and use a geographic region (-R), map projection (-J) and input longitude, latitude to place these features on a map. There are times when we also would like to plot such a symbol outside a map, such as in a legend. In legends, there usually is no geographic region nor projection, and at best there is a Cartesian -R -J set up for placing information. Because the above-mentioned tools reads longitude, latitude of where a feature is it becomes a guessing game to pick -R -J and input coordinates to align the symbol, say, centered in a legend.

One way to handle this would be to add a new option to these modules that, like -D for colorbars or scales, deals with this issue. Examining the various modules I see that the option -I (for information) is available [or -Z if coupe is can be excluded]. Thus, a solution may be this:

1. Add -I[g|j|J|n|x]refpoint for specifying where the special symbol should be plotted (with the usual ways of refpoint values like coordinates or codes)
2. When -I is used the input longitude, latitude is ignored and placement is given via -I instead.

For instance, to center a focal mechanism in the middle of a 5x10 cm legend area we could do

gmt meca -R0/10/0/5 -Jx1c -Sm2.5c -M -G110/168/255 -T0 -W0.5p -Yh+0.5c -IjCM <<- EOF
-159.70 54.81 39 0.82 -0.68 -0.14 0.63 0.34 -0.40 25
EOF

and the actual earthquake location (-159.70 54.81 ) is simply ignored. I think the proposed mechanism will make it easier to add special symbols such as GPS velocity with error symbols and focal mechanism to user legends.

Comments, @joa-quim and @seisman? Apart from meca and velo, does it make sense to extend this solution to polar, coupe, and sac?

[seisman]

Is it worth wasting the -I option for such rare cases? I probably would manually modify the longitude and latitude to position it at the specific location.

[PaulWessel]

Well, to be discussed. In the past we have had requests for how to place a velocity vector for scale in a legend. Sometimes these items need to be evaluated at a given location but then plotted in a Cartesian table or legend. Hard to do if you modify the input coordinates which then changes the latitude. Replacing the lon, lat with a dummy Cartesian coordinate in meca is possible but not very slick from the command line; perhaps simpler in Python, Julia, Matlab. Also, to do the placement shown in #4449 means all the math is now on you to do in the script.

[PaulWessel]

Because of #4400 I would like a resolution to this suggestion and the PR I made for testing, i.e., #4449.

To summarize where we are:

Pros:

1. Greatly simplifies ability to place an actual meca and velo symbol in a legend where there are no lon/lat/projection settings.
2. Only uses one new option -I for indicating placement, similar to -D options for psscale and other embellishments.

Cons:

1. Adds a new option that perhaps could be used for other enhancements to the seis and geodesy tools.
2. Does not really affect Animation 13 (seismic waveforms) #4400 since we are placing a map first so -R -J are available for plotting the focal mechanism.

@seisman's main con point is (1) plus that he can edit the coordinates to make it work. (1) is not too strong an argument since (a) there are no pressing other features being contemplated for meca and velo (I think?), while manually fiddling with coordinates does not lend itself to scripting and automation, meaning this will remain a thing that only the brave will do, and with a per-case unique solution.

As for me, I have no urgent need for this feature but as mentioned we have had several requests for how to place velo error/uncertainty symbols in legends and have not been able to give good answers, and I suspect placing a focal mechanism in a legend would be useful to seismologists as well. To avoid issues and PRs to linger too long, may I have final words from @seisman and @joa-quim on this so we can make a decision?

[joa-quim]

I don't mind using a capital letter but -I is almost a global meaning increment. Besides grdvector would benefice a lot with this since we have no mean of potting a vector scale and it already has I taken ... as increment.
I see that coupe uses -Z for cpt. Silly, it should be using -C. Limit, we are not obliged to use the same letter in all modules, though I know we should.

[PaulWessel]

Yes, I noticed the coupe abomination too. Since there is no -C option in coupe we should use -C for the CPT (and handle it in a backwards compatible way). That would free up -Z (and it is easy to tell -Zcpt from Z). I would prefer -Z to -I as well. These tools have a long history with lots of options I had to break to fit into GMT (they had lots of lower-case options that clashed with ours, hence I had to make -Fe, -Ff etc options).

So regardless of what we do with the current issue, I think changing coupe backwardsly is a separate issue I can start on right away.

[PaulWessel]

Well, actually the same shit is true of meca (-Zcpt) and it also have a -C and lots of options in general. We whould have to do this:

1. -C goes to new -A (with backwards check)
2. -Z goes to -C (with backwards check)

Give the syntax this is pretty easy to do under the hood and handle the backwardness. There was a lot of lack of planning the options when the French wrote this back in the late 1990s. Even polar has a -C option for something similar to what meca does. So does sac. So to free up -Z I would need to also fix meca. Think we need @seisman's comments on all of this.
I think this is why I settled on the less desirable -I.

[joa-quim]

But -I cannot be used in grdvector.

[PaulWessel]

True. But I think I need to look at grdvector and what is required to plot a vector at the right scale. Legend can already plot vectors so it is different than the other cases above which are very specialized symbols.

[seisman]

In the past we have had requests for how to place a velocity vector for scale in a legend.

Even if -I option is added, it's still not easy to plot beachballs or vectors in a legend. Imaging that you already have many symbols (circles, triangles) in a legend, you have to leave some spaces for vector and also need to adjust -I option to correctly position the vetcor. It would be good if legend module can position and plot these symbols.

[PaulWessel]

Resurrecting this thread so we can reach a resolution and finish #4400. Let's see if @seisman's suggestion of using legend might work. This would involve (I think):

1. New legend code for a specific meca symbol (we already have a generic focal mechanism symbol via -Skmeca.)
2. New legend codes for a specific geographic vector length/scale that are different for psvelo and grdvector

I note we already have special legend codes to place a colorbar (B), image (I), and map scale (M), and these were added for very similar reasons to the discussion above (placement inline in a legend). We have a long list of unused letters that could become new legend codes: E, J, K, O, Q, R, U, W, X, Y, Z). So, we could consider adding:

1. Q for earthQuake via a special call to meca. It would do under the hood what I suggested should happen above.
2. O for velO symbol (arrow with error ellipse) via call to velo
3. R for grdvectoR symbol (arrow) via a call to grdvector (or possibly plot)

These would have to take enough arguments to allow us to properly call meca, velo, and grdvector (and have reasonable defaults]. It seems this would be a better and simpler scheme. What do you think, @seisman and @joa-quim ?

[joa-quim]

Looks good. Better than -I

[seisman]

I'm wondering whether it's possible to have a more general legend code which can handle all the three (and maybe more in the future) symbols, like:

R module dx1 input_columns options dx2 text

For example:

R meca 0.2c 10 20 30 40 50 60 5 -Sa0.4c -W1p -Gred 0.5c beachball-1

In the above example, 10 20 30 40 50 60 5 are input columns for meca, in which 10 20 30 are lon, lat, and depth, which are ignored. 40 50 60 are strike, dip, rake, and 5 is the magnitude.

[PaulWessel]

Sure, it is just parsing of some line. As long as we can uniquely parse things. If options always starts with -letter then we can tell that apart from, say, -45. Given that the S syntax is

S dx1 symbol size fill pen [ dx2 text ]

perhaps it is possible to do

R module dx1 symbol size fill pen [ dx2 text ]

since all symbols need a fill and outline (and either can be -). And dx2 text are often optional.

[PaulWessel]

And while available, I would avoid using R or J for obvious reasons. Perhaps this is better as a Q, with alternatives being E, Z.

[seisman]

I would avoid using R or J for obvious reasons

I agree.

Given that the S syntax is

S dx1 symbol size fill pen [ dx2 text ]

perhaps it is possible to do

R module dx1 symbol size fill pen [ dx2 text ]

beachballs are complicated, as users can specify two fills (for compressional and extensive quadrants), and two pens (outline and nodal planes).

[PaulWessel]

OK, fair enough; E for Extra or External symbol perhaps?

E module dx1 input_column(s) option(s) [dx2 text]

[seisman]

E sounds good to me. What about swapping dx1 and module?

E dx1 module input_column(s) option(s) [dx2 text]

or even

E module input_column(s) option(s) dx1 [dx2 text]

[PaulWessel]

Could be. I think it becomes clear once we decide what each symbol requires and what is simplest. Since you know meca and focal mechanisms, perhaps you can do a mock up of what you expect to be able to do in a legend.

[seisman]

Since you know meca and focal mechanisms, perhaps you can do a mock up of what you expect to be able to do in a legend.

Sorry, I don't fully understand what you mean. Do you want to provide a list of allowed meca options in legend, or an example legend record?

[PaulWessel]

Yes, I was not very clear... I was thinking what is the layout here. There is a symbol (selected via meca options) that is treated like a S symbol so it is centered at that first column with a RM-justified optional text item. I think that is it, no? Any extra text that one may want will be placed with other codes, like L or H or paragraph text. I guess the initial example in anim13 had a quite large meca symbol but if this is similar to -S then I wonder how it will look.

[PaulWessel]

Looking at this again: Are there cases where you want a legend but only showing a single event in the main map and then want the same focal mechanism in the legend? Seems to me that the common case is to show lots of earthquakes on a map and then the legend typically might just show a single event with title "earthquakes > 5" or perhaps indicate thrust vs normal etc. If we simply pre-determined three sets of parameters for strike-slip, thrust, and normal, and possibly a non-double-couple solution, is that good enough? It would simplify what arguments we pass.