Psvelo [Plot velocity vectors, crosses, and wedges]

[lhoupert]

Description of the desired feature
Implementation of the psvelo function.

It would be really a great feature for pygmt to be able to plot velocity vectors and confidence ellipse, because, at the moment, it is not possible with the classic matplotlib function quiver.

---

Example plots
Two examples are available on gmt.soest.hawaii.edu. I copy the description of the example provide and the output when I run the code on GMT-6.0.0.

Example 1
"The following should make big red arrows with green ellipses outlined in red. Note that the 39% confidence scaling will give an ellipse which fits inside a rectangle of dimension Esig by Nsig."

gmt psvelo << END -h2 -R-10/10/-10/10 -W0.25p,red -Ggreen -L -Se0.2/0.39/18 \
    -B1g1 -Jx0.4/0.4 -A0.3p -P -V > test.ps
#Long. Lat. Evel Nvel Esig Nsig CorEN SITE
#(deg) (deg) (mm/yr) (mm/yr)
0. -8. 0.0 0.0 4.0 6.0 0.500 4x6
-8. 5. 3.0 3.0 0.0 0.0 0.500 3x3
0. 0. 4.0 6.0 4.0 6.0 0.500
-5. -5. 6.0 4.0 6.0 4.0 0.500 6x4
5. 0. -6.0 4.0 6.0 4.0 -0.500 -6x4
0. -5. 6.0 -4.0 6.0 4.0 -0.500 6x-4
END

The example above seems to be running fine on GMT-6.0.0, except that the colour of my ellipses are not green.

Example 2
"This example should plot some residual rates of rotation in the Western Transverse Ranges, California. The wedges will be dark gray, with light gray wedges to represent the 2-sigma uncertainties."

gmt psvelo << END -Sw0.4/1.e7 -W0.75p -Gdarkgray -Elightgray -h1 -D2 -Jm2.2 \
    -R240./243./32.5/34.75 -Bf10ma60m/WeSn -P > test.ps
#lon lat spin(rad/yr) spin_sigma (rad/yr)
241.4806 34.2073 5.65E-08 1.17E-08
241.6024 34.4468 -4.85E-08 1.85E-08
241.0952 34.4079 4.46E-09 3.07E-08
241.2542 34.2581 1.28E-07 1.59E-08
242.0593 34.0773 -6.62E-08 1.74E-08
241.0553 34.5369 -2.38E-07 4.27E-08
241.1993 33.1894 -2.99E-10 7.64E-09
241.1084 34.2565 2.17E-08 3.53E-08
END

*I don't really understand what should be plotted here [I am a physical oceanographer], but it doesn't seem absurd...

---

Are you willing to help implement and maintain this feature?
I can try to help but I am not an expert in gmt or in python programming ... Therefore I will need some help to understand how complex functions are coded :-D

[weiji14]

Hi @lhoupert, it's called velo now 😉. Do you have an example of how it looks like? You can edit the original post with an example figure. I've not personally used velo before but there's certainly been interest in wrapping some of the supplementary modules (see e.g. #516).

Considering that velo is quite similar to plot, except for the -S flag, a quick way to start might just be to:

1. Copy the plot code at https://github.com/GenericMappingTools/pygmt/blob/master/pygmt/base_plotting.py#L447 and rename it to velo.
2. Change the documentation string to that in https://docs.generic-mapping-tools.org/latest/supplements/geodesy/velo.html.
3. Handle the slightly different -S flag somehow.

If you're keen, open up a Pull Request and give it a go! it'll be easier for us or someone else to pick up the PR and add things like gallery examples and unit tests. It might be useful to see how plot3d is being implemented at #471.

[lhoupert]

Thank you @weiji14 . It is exactly the -S flag options that interest me :-). Any suggestion on how to do implement it?

I added two example pictures in the original post.

Also, I just started editing the documentation string and looked into the code copied from plot but I don't know how to handle the fact that table is a required argument for velo while it is only optional for plot. Do you know how I should write this down?

[weiji14]

Thank you @weiji14 . It is exactly the -S flag options that interest me :-). Any suggestion on how to do implement it?

Thanks for adding the example, it's nice having a visual image on what we're working towards 😄 After taking a closer look, I think the -S option in velo could be implemented almost exactly like plot (i.e. you could just copy and paste it), though it is a required argument in velo. It would just take in a str (e.g. S="e0.2/0.39/18"), and that would handle the different table columns being passed in.

Also, I just started editing the documentation string and looked into the code copied from plot but I don't know how to handle the fact that table is a required argument for velo while it is only optional for plot. Do you know how I should write this down?

We'll always require some form of data input (e.g. longitude, latitude, etc), even for PyGMT's plot. Any 'required' or 'optional' argument is just an 'argument' to us! In plot, we have two options to pass in data:

1. Passing in lists or numpy arrays as x/y pairs (e.g. x=0, y=1, style="c"), good for plotting a single or a few points.
2. Passing in a pandas.DataFrame into data (e.g. data=df), good for plotting several rows of data

Again, I imagine this would be very similar for velo, and I wouldn't be surprised if everything works if you just copied and pasted the def plot code and renamed this line to velo:

pygmt/pygmt/base_plotting.py

Line 559 in 0f12972

lib.call_module("plot", arg_str)

I see you've already made a fork for PyGMT, if you already have something done, just open up a draft pull request and we (and the PyGMT team) can work on it together, will be much easier to suggest changes and talk about the specifics.

[lhoupert]

Thank you @weiji14 for the help. I started working on it and I opened a pull request [here].