Skip to content

Figure.plot/Figure.plot3d: Improve the docstrings for straight_line #3720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jan 6, 2025
Merged

Figure.plot/Figure.plot3d: Improve the docstrings for straight_line #3720

Changes from 5 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
caef6e9
Figure.plot: Improve the docstring for 'straight_line'
seisman Dec 25, 2024
1361602
Rephrase again
seisman Dec 27, 2024
21ed3f9
Merge branch 'main' into plot/straight_line
seisman Dec 27, 2024
d3071a3
Fix formatting
seisman Dec 27, 2024
98d195e
One more fix
seisman Dec 27, 2024
3c3c52a
Fix a typo
seisman Dec 31, 2024
48febe5
Merge branch 'main' into plot/straight_line
seisman Jan 2, 2025
9aa8f97
Add a note about the bug in GMT<=6.5.0
seisman Jan 2, 2025
b839e2d
Merge branch 'main' into plot/straight_line
seisman Jan 3, 2025
7009972
Apply the same changes to plot3d
seisman Jan 5, 2025
9c148cf
One extra note for plot3d
seisman Jan 5, 2025
dd5f63b
Merge branch 'main' into plot/straight_line
seisman Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 27 additions & 13 deletions pygmt/src/plot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
plot - Plot in two dimensions.
"""

from typing import Literal

from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import (
Expand Down Expand Up @@ -49,7 +51,15 @@
)
@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
def plot(
self, data=None, x=None, y=None, size=None, symbol=None, direction=None, **kwargs
self,
data=None,
x=None,
y=None,
size=None,
symbol=None,
direction=None,
straight_line: bool | Literal["x", "y"] = False, # noqa: ARG001
**kwargs,
):
r"""
Plot lines, polygons, and symbols in 2-D.
Expand Down Expand Up @@ -98,18 +108,22 @@ def plot(
depending on the style options chosen.
{projection}
{region}
straight_line : bool or str
[**m**\|\ **p**\|\ **x**\|\ **y**].
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use
``straight_line=True``.
Alternatively, add **m** to draw the line by first following a
meridian, then a parallel. Or append **p** to start following a
parallel, then a meridian. (This can be practical to draw a line
along parallels, for example). For Cartesian data, points are
simply connected, unless you append **x** or **y** to draw
stair-case curves that whose first move is along *x* or *y*,
respectively.
straight_line
By default, line segments are drawn as straight lines in the Cartesian and polar
coordinate systems, and as great circle arcs (by resampling coarse input data
along such arcs) in the geographic coordinate system. The ``straight_line``
parameter can control the drawing of line segments. Valid values are:

- ``True``: Draw line segments as straight lines in geographic projections.
- ``"x"``: Draw line segments by first along *x*, then along *y*.
- ``"y"``: Draw line segments by first along *y*, then along *x*.

Here, *x* and *y* have different meanings depending on the coordinate system:

- **Cartesian** coordinate system: *x* and *y* are the X- and Y-axes.
- **Polar** coordinate system: *x* and *y* are theta and radius.
- **Gragraphic** coordinate system: *x* and *y* are parallels and meridians.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not really familiar with this parameter, and maybe I am wrong or confused by myself. I can follow the cases for "Cartesian" and "Polar", but for "Geographic" I am wondering if there is something mixed up. Looking at the image at the beginning of this PR (I reduced the example and added a red point at the starting point): For A="x", it's first in north-south direction (varying latitude, constant longitude, i.e. meridian) and then in east-west direction (varying longitude, constant latitude, i.e. parallel); and for A="y" it's the other way around. At the moment it looks to me a bit like that (only for the Geographic case) for the "x" and "y" arguments, people defined the x-axis as latitude (vertical) and the y-axis as longitude (horizontal), which is the other way around as the input data points are given. Comparing the images for the "Geographic" case with the images for the "Cartesian" case, I would expect the images for the "Geographic" case to be switched:

plot_A_geographic

import pygmt

fig = pygmt.Figure()
values = ["x", "y"]

for arg in values:
    fig.basemap(region=[0, 10, 1, 10], projection="X6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[3, 8], y=[2, 7], pen="1p", straight_line=arg)
    fig.plot(x=3, y=2, style="c0.2c", fill="red")
    fig.shift_origin(xshift="w+1")

fig.shift_origin(xshift="-2w-2", yshift="h+2")

for arg in values:
    fig.basemap(region=[0, 360, -90, 90], projection="H6c", frame=[f"WSen+t-A={arg}"])
    fig.plot(x=[90, 200], y=[-50, 50], pen="1p", straight_line=arg)
    fig.plot(x=90, y=-50, style="c0.2c", fill="red")
    fig.shift_origin(xshift="w+1")

fig.show()

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch. It looks more like an upstream bug. Need time to verify it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's confirmed to be an upstream bug at GenericMappingTools/gmt#8645 and has been fixed in GenericMappingTools/gmt#8648.

Unfortunately, there is no way to determine the type (Cartesian, polar or geographic) of the current coordinate system via public GMT APIs, so we can't have a fix on the PyGMT side. Instead, I have added a note for the bug 9aa8f97


{frame}
{cmap}
offset : str
Expand Down
Loading