Convenient methods to plot horizontal and vertical lines

[seisman]

Description of the desired feature

matplotlib provides two methods, hlines and vlines, for plotting horizontal and vertical lines.

In PyGMT, we can plot any lines using the plot() method. However, for plotting horizontal and vertical lines, we have to prepare the input x and y arrays, which is not elegant.

Expected syntax:

Figure.hlines(y, xmin=None, xmax=None, pen=None, label=None)
Figure.vlines(x, ymin=None, ymax=None, pen=None, label=None)

An expected hlines example:

import pygmt
fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
fig.hlines(1, label="line1")
fig.hlines([2, 3], pen="1p,blue", label="line2")
fig.hlines([4, 5], xmin=2, xmax=8, pen="1p,red", label="line3")
fig.hlines([6, 7], xmin=[2, 3], xmax=[8, 9], pen="1p,lightblue", label=["line4", "line5"])
fig.legend()
fig.show()

Expected output:

The above script is equivalent to the following script:

import pygmt
fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
fig.plot(x=[0, 10], y=[1, 1], label="line1")
fig.plot(x=[0, 10], y=[2, 2], pen="1p,blue", label="line2")
fig.plot(x=[0, 10], y=[3, 3], pen="1p,blue")
fig.plot(x=[2, 8], y=[4, 4], pen="1p,red", label="line3")
fig.plot(x=[2, 8], y=[5, 5], pen="1p,red")
fig.plot(x=[2, 8], y=[6, 6], pen="1p,lightblue", label="line4")
fig.plot(x=[3, 9], y=[7, 7], pen="1p,lightblue")
fig.legend()
fig.show()

Are you willing to help implement and maintain this feature? Yes

[willschlitzer]

Is there any way to get basemap to return x/y min/max values to set as the endpoint values when calling hlines/vlines? I would like to give this a try but I can't get past how to plot the line to take up the range of the figure if the None defaults are used for the min/max values.

[seisman]

I think this function is what you need:

pygmt/pygmt/clib/session.py

Line 1374 in 6bad810

def extract_region(self):

[willschlitzer]

Thanks! I assume you're talking about extract_region()?

[seisman]

Yes.

[michaelgrund]

Are you still working on that issue @willschlitzer? If not and if it's ok for you I would like to continue with that 😉

[willschlitzer]

@michaelgrund Haven't made any progress lately; by all means have a stab at it!

[weiji14]

Just two quick questions:

1. On organizing these higher level convenience functions. Do we want to keep them in the pygmt/src folder or somewhere else?

2. Should the implementation of hlines and vlines be reusing some part of the fig.plot code? Or do we implement them from scratch as is being done in Add Figure.hlines for plotting horizontal lines #923?

[seisman]

1. On organizing these higher level convenience functions. Do we want to keep them in the pygmt/src folder or somewhere else?

I think we should put them in pygmt/src. To users and developers, they are the same as other modules/functions.

2. Should the implementation of hlines and vlines be reusing some part of the fig.plot code? Or do we implement them from scratch as is being done in Add Figure.hlines for plotting horizontal lines #923?

Do you mean Figure.hlines() should calling Figure.plot()? Ideally yes, but I'm not sure if Figure.hlines() can use the aliases of Figure.plot().

[nathandloria]

Hello! Thank you for the continued communication with our team (@cklima616 @munzekm @noorbuchi and I) as we decide where to go next in our class. I would just like to inquire about the availability of this issue? It seems very interesting and we would consider working on it if it is available still. Thanks again, we really do appreciate the cooperation.

[michaelgrund]

Hey @nathandloria, I'm currently working on this in #923, so maybe you can find another interesting topic or issue like #549 (Add tutorial for plotting datetime inputs) as suggested by @weiji14 ?

[maxrjones]

@michaelgrund, are you planning to add vlines after #923? If so, I'll remove the help-wanted label.

[maxrjones]

@daroari is going to work on the vlines function to complement @michaelgrund's hlines function in pull request #923

[seisman]

We have added Figure.hlines (#923) and Figure.vlines (#3726), but we still need one gallery example to tutorial for these two new functions.

[seisman]

A gallery example was added in #3755. Closing.