Add Figure.hlines for plotting horizontal lines

[michaelgrund]

Description of proposed changes

This PR implements the Figure.hlines method to plot horizontal line(s). This is a high-level wrapper of Figure.plot, and is inspired by matplotlib.pyplot.hlines.

Address #670.

Features

• Plot one or multiple lines (specified by y)
• The X-limits of lines can be set by xmin/xmax, and then default to the x-limits of the current plot (i.e., fig.region[0:2])
• Support Cartesian coordinates (as straight lines), geographic projection (as lines along constant latitude), and polar projection (as lines along constant radius).
• The line's pen attribute can be set via pen
• A legend entry can be added via label
• Parameters no_clip/transparency/perspective are also supported

Limitations

• When plotting multiple lines, only one single pen/label is allowed. It's possible to allow different pen or label (by passing a sequence of pen or label), but I feel it makes the codes too complicated. Users who need different pens/labels can call Figure.hlines multiple times.
• When plottting multiple lines, we call Figure.plot multiple times in a loop. As mentioned in Add Figure.hlines for plotting horizontal lines #923 (comment), it's possible to use np.nan as separators for each line, then we can call Figure.plot once. However, GMT will complain about NaN records when plotting lines in geographic projections because GMT needs to resample the lines before plotting.
• When plottling lines in geographic or polar projections, just passing two points is not enough, since GMT defaults to plot the minor great-circle arcs. As shown below, we need to at least 4 points for geographic projections.

import pygmt
import numpy as np

fig = pygmt.Figure()
fig.basemap(region="d", projection="H15c", frame=True)

# Passing 2, 3 or 4 data points to plot horizontal lines.
for npoints in [2, 3, 4]:
    fig.plot(x=np.linspace(0, 360, npoints), y=[npoints * 10] * npoints, pen="1p,red", straight_line="m")
fig.show()

• npoints=2: Line is not plotted, because in geographic projections, longitude is periodic, so longitude 0=360.
• npoints=3: i.e., passing x=[0, 180, 360], only one minor arc is drawn
• npoints=4: i.e., passing x=[0, 90, 180, 360], works
  

Example

Here is an example showing how it works in Cartesian/polar/geographic projections. See the tests for more examples.

import pygmt

fig = pygmt.Figure()

# Cartesian projection
fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
fig.hlines(y=1, pen="1p,black", label="Line 1")
fig.hlines(y=2, xmin=2, xmax=8, pen="1p,red,-", label="Line 2")
fig.hlines(y=[3, 4], xmin=3, xmax=7, pen="1p,black,.", label="Line 3")
fig.hlines(y=[5, 6], xmin=4, xmax=9, pen="1p,red", label="Line 4")
fig.hlines(y=[7, 8], xmin=[0, 1], xmax=[7, 8], pen="1p,blue", label="Line 5")
fig.legend()

fig.shift_origin(xshift="w+2c")
# Geographic 
fig.basemap(region="g", projection="R15c", frame=True)
fig.hlines(50, xmin=0, xmax=360, pen="1p")

fig.shift_origin(xshift="w+2c")
# Polar
fig.basemap(region=[0, 360, 0, 1], projection="P10c", frame=True)
fig.hlines(0.5, xmin=0, xmax=80, pen="1p")
fig.show()

Preview: https://pygmt-dev--923.org.readthedocs.build/en/923/api/generated/pygmt.Figure.hlines.html

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[seisman]

@michaelgrund Nice work! I just changed the PR title so that we can focus on one feature Figure.hlines in this PR.

[seisman]

Furthermore, currently the whole procedure is performed in a loop since it's not possible to pass multi-segment lines to the plot function so far (except using an input file).

It's possible to use np.NaN record to separate segments:

import numpy as np
import pygmt

x = np.array([2, 4, 4, np.NaN, 5, 6])
y = np.array([3, 5, 7, np.NaN, 4, 2])

fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], frame=True)
fig.plot(x, y, pen="2p")
fig.show()

but I'm not sure if other features (lines with different colors) are supported.

[michaelgrund]

Furthermore, currently the whole procedure is performed in a loop since it's not possible to pass multi-segment lines to the plot function so far (except using an input file).

It's possible to use np.NaN record to separate segments:

import numpy as np
import pygmt

x = np.array([2, 4, 4, np.NaN, 5, 6])
y = np.array([3, 5, 7, np.NaN, 4, 2])

fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], frame=True)
fig.plot(x, y, pen="2p")
fig.show()

but I'm not sure if other features (lines with different colors) are supported.

Ok will check that and, if possible, adjust the code.

[yvonnefroehlich]

@seisman related to your comment in #3593 (comment) should this new high-level method for specifically plotting horizontal lines be included in the "Plotting Lines" tutorial? Or do we want to have a separate gallery example showing the different interpretation of horizontal lines in different coordinate systems?

[seisman]

Or do we want to have a separate gallery example showing the different interpretation of horizontal lines in different coordinate systems?

I prefer this one

[seisman]

The plan is to implement hlines and vlines, then add a gallery example for plotting horizontal and vertical lines in Cartesian, polar and geographic projections.

[michaelgrund]

Thanks for pushing this forward @seisman after almost 3.5 years. I'm fine with all the changes, especially with removing too complicated parts I added initially. Since I'm the author of this PR I cannot give an approval.

The plan is to implement hlines and vlines, then add a gallery example for plotting horizontal and vertical lines in Cartesian, polar and geographic projections.

If I remember correctly the gallery example I provided within this PR was the left one in the example figure of the first post. After implementing vlines adding this together with some geographic and polar plots might be a good gallery example.

[seisman]

I've marked this PR as "final review call", but will keep this PR open for more days since most of you are busy with the AGU workshop.

Please 👍 if you have time reviewing this PR and think it's ready for merge. Or we can revisit the PR after AGU.

[michaelgrund]

Looks good!