Merge branch 'main' into add-gallery-grdmask

Author: yvonnefroehlich

doc/api/index.rst

@@ -127,7 +127,6 @@ Operations on tabular data
     blockmedian
     blockmode
     filter1d
-    grdmask
     nearneighbor
     project
     select
@@ -157,6 +156,7 @@ Operations on raster data
     grdhisteq.equalize_grid
     grdhisteq.compute_bins
     grdlandmask
+    grdmask
     grdpaste
     grdproject
     grdsample

examples/gallery/basemaps/ternary.py

@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Position
+from pygmt.params import Axis, Frame, Position
 
 fig = pygmt.Figure()
 
@@ -34,11 +34,13 @@
     blabel="Water",
     clabel="Air",
     cmap=True,
-    frame=[
-        "aafg+lLimestone component+u %",
-        "bafg+lWater component+u %",
-        "cafg+lAir component+u %",
-    ],
+    frame=Frame(
+        xaxis=Axis(
+            annot=True, tick=True, grid=True, label="Limestone component", unit="%"
+        ),
+        yaxis=Axis(annot=True, tick=True, grid=True, label="Water component", unit="%"),
+        zaxis=Axis(annot=True, tick=True, grid=True, label="Air component", unit="%"),
+    ),
 )
 
 # Add a colorbar indicating the values given in the fourth column of the input dataset

pygmt/params/frame.py

@@ -3,6 +3,7 @@
 """
 
 import dataclasses
+from typing import Literal
 
 from pygmt.alias import Alias
 from pygmt.exceptions import GMTParameterError
@@ -45,6 +46,11 @@ class Axis(BaseParam):
     #: Specify the interval for gridlines. Same format as ``annot``.
     grid: float | str | bool = False
 
+    #: Skip annotations that fall exactly at the ends of the axis. Set to ``True`` to
+    #: skip both ends, or use ``"lower"``/``"upper"`` to skip only the lower/upper
+    #: end.
+    end_skip: Literal["lower", "upper"] | bool = False
+
     #: Label for the axis [Default is no label].
     label: str | None = None
 
@@ -73,6 +79,12 @@ def _aliases(self):
             Alias(self.annot, name="annot", prefix="a"),
             Alias(self.tick, name="tick", prefix="f"),
             Alias(self.grid, name="grid", prefix="g"),
+            Alias(
+                self.end_skip,
+                name="end_skip",
+                prefix="+e",
+                mapping={"lower": "l", "upper": "u"},
+            ),
             Alias(self.label, name="label", prefix="+l"),
             Alias(self.alt_label, name="alt_label", prefix="+s"),
             Alias(self.hlabel, name="hlabel", prefix="+L"),

pygmt/src/grdmask.py

@@ -128,14 +128,14 @@ def grdmask(
     """
     Create mask grid from polygons or point coverage.
 
-    Reads one or more files containing polygon or data point coordinates, and creates a
-    grid where nodes that fall inside, on the edge, or outside the polygons (or within
-    the search radius from data points) are assigned values based on the ``outside``,
-    ``edge``, and ``inside`` parameters.
+    Takes one or more polygons or data point coordinates, and creates a grid where nodes
+    that fall inside, on the edge, or outside the polygons or within the search radius
+    from data points are assigned values based on the ``outside``, ``edge``, and
+    ``inside`` parameters.
 
-    The mask grid can be used to mask out specific regions in other grids using
-    :func:`pygmt.grdmath` or similar tools. For masking based on coastline features,
-    consider using :func:`pygmt.grdlandmask` instead.
+    The mask grid can be used to mask out specific regions from another grid. For
+    masking based on coastline features, consider using :func:`pygmt.grdlandmask`
+    instead.
 
     Full GMT docs at :gmt-docs:`grdmask.html`.
 
@@ -156,7 +156,7 @@ def grdmask(
         Pass in either a file name to an ASCII data table, a 2-D $table_classes
         containing the polygon(s) or data points. Input can be:
 
-        - **Polygon mode**: One or more files containing closed polygon coordinates
+        - **Polygon mode**: One or more polygons with closed coordinates
         - **Point coverage mode**: Data points (used with ``search_radius`` parameter)
     $outgrid
     $spacing
@@ -165,10 +165,13 @@ def grdmask(
     inside
         Set the value assigned to nodes outside, on the edge, or inside the polygons.
         Can be any number, or one of ``None``, ``"NaN"``, and ``np.nan`` for NaN.
+        Defaults are ``0`` for ``outside``, ``0`` for ``edge``, and ``1`` for
+        ``inside``. When setting these values, keep in mind you are creating a mask grid
+        which is thought to be applied to a real grid in a second step.
 
-        ``inside`` and ``edge`` can also be set to one of the following values:
+        ``edge`` and ``inside`` can also be set to one of the following values:
 
-        - ``"z"``: Use the z-value from polygon data (segment header ``-Zzval``,
+        - ``"z"``: Use the z-values from polygon data (segment header ``-Zzval``,
           ``-Lheader``, or via ``-aZ=name``).
         - ``"id"``: Use a running polygon ID number.
 

pygmt/src/ternary.py

@@ -8,7 +8,103 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
+from pygmt.exceptions import GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
+from pygmt.params import Axis, Frame
+from pygmt.params.frame import _Axes
+
+
+def _ternary_frame(frame):
+    """
+    Convert 'frame' to ternary-compatible format.
+
+    For ternary diagrams, GMT uses axis names **a**, **b**, **c** instead of **x**,
+    **y**, **z**, and there are no primary/secondary axes. This function converts a
+    :class:`pygmt.params.Frame` or :class:`pygmt.params.Axis` object to a string or
+    a list of strings with the correct axis prefixes.
+
+    Parameters
+    ----------
+    frame : Frame, Axis, str, list, or bool
+        The frame parameter to convert.
+
+    Returns
+    -------
+    str, bool, or list of str
+        The converted frame parameter. For Frame inputs, returns a list of strings;
+        for Axis, str, bool, or list inputs, returns the value directly.
+
+    Examples
+    --------
+    >>> from pygmt.params import Axis, Frame
+    >>> _ternary_frame(Axis(annot=True, tick=True, grid=True))
+    ['afg', '']
+    >>> _ternary_frame(
+    ...     Frame(title="Title", axis=Axis(annot=True, tick=True, grid=True))
+    ... )
+    ['+tTitle', 'afg']
+    >>> _ternary_frame(
+    ...     Frame(
+    ...         title="Title",
+    ...         xaxis=Axis(annot=True, tick=True, grid=True, label="Water"),
+    ...         yaxis=Axis(annot=True, tick=True, grid=True, label="Air"),
+    ...         zaxis=Axis(annot=True, tick=True, grid=True, label="Limestone"),
+    ...     )
+    ... )
+    ['+tTitle', 'aafg+lWater', 'bafg+lAir', 'cafg+lLimestone']
+    >>> _ternary_frame(Frame(fill="lightblue", axis=Axis(annot=True)))
+    ['+glightblue', 'a']
+    >>> _ternary_frame("afg")
+    ['afg', '']
+    >>> _ternary_frame(True)
+    True
+    >>> _ternary_frame(["aafg+lWater", "bafg+lAir", "cafg+lLimestone"])
+    ['aafg+lWater', 'bafg+lAir', 'cafg+lLimestone']
+    >>> _ternary_frame("none")
+    'none'
+    >>> _ternary_frame(Frame(axes="WSen", axis=Axis(annot=True)))
+    Traceback (most recent call last):
+    pygmt.exceptions.GMTValueError: ...
+    >>> _ternary_frame(Frame(xaxis2=Axis(annot=True)))
+    Traceback (most recent call last):
+    pygmt.exceptions.GMTValueError: ...
+    """
+    if isinstance(frame, Axis):
+        axis_str = str(frame)
+        if axis_str:
+            return [axis_str, ""]
+        return axis_str
+    if isinstance(frame, Frame):
+        _attributes = ["title", "subtitle", "fill", "axis", "xaxis", "yaxis", "zaxis"]
+        if any(
+            _attr not in _attributes and getattr(frame, _attr) for _attr in vars(frame)
+        ):
+            raise GMTValueError(
+                repr(frame),
+                description="frame setting",
+                reason="For ternary diagrams, only Frame attributes "
+                f"{', '.join(repr(_attr) for _attr in _attributes)} are supported.",
+            )
+        frame_settings = _Axes(
+            title=frame.title, subtitle=frame.subtitle, fill=frame.fill
+        )
+        params = [
+            Alias(frame_settings) if str(frame_settings) else Alias(None),
+            Alias(frame.axis),
+            Alias(frame.xaxis, prefix="a"),
+            Alias(frame.yaxis, prefix="b"),
+            Alias(frame.zaxis, prefix="c"),
+        ]
+        result = [par._value for par in params if par._value is not None]
+        # When only general axis settings are used without frame-level settings
+        # (title/fill) or axis-specific settings (xaxis/yaxis/zaxis), GMT needs
+        # a bare -B to draw the frame border. E.g., -Bafg alone doesn't draw it.
+        if not str(frame_settings) and not any((frame.xaxis, frame.yaxis, frame.zaxis)):
+            result.append("")
+        return result
+    if isinstance(frame, str) and frame not in {"", "none", "+n"}:
+        return [frame, ""]
+    return frame
 
 
 @fmt_docstring
@@ -20,7 +116,7 @@ def ternary(  # noqa: PLR0913
     blabel: str | None = None,
     clabel: str | None = None,
     region: Sequence[float | str] | str | None = None,
-    frame: str | Sequence[str] | Literal["none"] | bool = False,
+    frame: str | Sequence[str] | Literal["none"] | bool | Frame | Axis = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
@@ -65,6 +161,9 @@ def ternary(  # noqa: PLR0913
         [*amin*, *amax*, *bmin*, *bmax*, *cmin*, *cmax*].
         Give the min and max limits for each of the three axes **a**, **b**,
         and **c**.
+    $frame
+        For ternary diagrams, use :class:`pygmt.params.Frame` ``xaxis``, ``yaxis``, and
+        ``zaxis`` attributes to set the **a**, **b**, and **c** axes, respectively.
     $cmap
     $fill
     alabel
@@ -85,15 +184,14 @@ def ternary(  # noqa: PLR0913
     $transparency
     """
     self._activate_figure()
-
     # -Lalabel/blabel/clabel. '-' means skipping the label.
     _labels = [v if v is not None else "-" for v in (alabel, blabel, clabel)]
     labels = _labels if any(v != "-" for v in _labels) else None
 
     aliasdict = AliasSystem(
         L=Alias(labels, name="alabel/blabel/clabel", sep="/", size=3),
     ).add_common(
-        B=frame,
+        B=_ternary_frame(frame),
         R=region,
         V=verbose,
         c=panel,

pygmt/tests/baseline/test_ternary_axis.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 97854ed4620b20f7fdf8fc685b6f7d3a
+  size: 57608
+  hash: md5
+  path: test_ternary_axis.png

pygmt/tests/baseline/test_ternary_no_frame.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 0d4303390ab992ab68cdf7fc045cb9d9
+  size: 10357
+  hash: md5
+  path: test_ternary_no_frame.png

pygmt/tests/test_params_frame.py

@@ -14,6 +14,9 @@ def test_params_axis():
     assert str(Axis(annot=True)) == "a"
     assert str(Axis(annot=True, tick=True, grid=True)) == "afg"
     assert str(Axis(annot=30, tick=15, grid=5)) == "a30f15g5"
+    assert str(Axis(annot=30, end_skip=True)) == "a30+e"
+    assert str(Axis(annot=30, end_skip="lower")) == "a30+el"
+    assert str(Axis(annot=30, end_skip="upper")) == "a30+eu"
     assert str(Axis(annot=30, prefix="$", unit="m")) == "a30+p$+um"
     assert str(Axis(annot=30, label="LABEL")) == "a30+lLABEL"
     assert str(Axis(annot=30, alt_label="LABEL2")) == "a30+sLABEL2"

pygmt/tests/test_ternary.py

@@ -5,6 +5,7 @@
 import numpy as np
 import pytest
 from pygmt import Figure
+from pygmt.params import Axis, Frame
 
 
 @pytest.fixture(scope="module", name="array")
@@ -58,7 +59,11 @@ def test_ternary(array):
         region=[0, 100, 0, 100, 0, 100],
         cmap="red,orange,yellow,green,blue,violet",
         width="10c",
-        frame=["bafg+lAir", "cafg+lLimestone", "aafg+lWater"],
+        frame=Frame(
+            xaxis=Axis(annot=True, tick=True, grid=True, label="Water"),
+            yaxis=Axis(annot=True, tick=True, grid=True, label="Air"),
+            zaxis=Axis(annot=True, tick=True, grid=True, label="Limestone"),
+        ),
         style="c0.1c",
         pen="thinnest",
     )
@@ -80,7 +85,11 @@ def test_ternary_3_labels(array):
         alabel="A",
         blabel="B",
         clabel="C",
-        frame=["bafg+lAir", "cafg+lLimestone", "aafg+lWater"],
+        frame=Frame(
+            xaxis=Axis(annot=True, tick=True, grid=True, label="Water"),
+            yaxis=Axis(annot=True, tick=True, grid=True, label="Air"),
+            zaxis=Axis(annot=True, tick=True, grid=True, label="Limestone"),
+        ),
         style="c0.1c",
         pen="thinnest",
     )
@@ -99,7 +108,56 @@ def test_ternary_1_label(array):
         cmap="red,orange,yellow,green,blue,violet",
         width="10c",
         alabel="A",
-        frame=["bafg+lAir", "cafg+lLimestone", "aafg+lWater"],
+        frame=Frame(
+            xaxis=Axis(annot=True, tick=True, grid=True, label="Water"),
+            yaxis=Axis(annot=True, tick=True, grid=True, label="Air"),
+            zaxis=Axis(annot=True, tick=True, grid=True, label="Limestone"),
+        ),
+        style="c0.1c",
+        pen="thinnest",
+    )
+    return fig
+
+
+@pytest.mark.parametrize(
+    "frame",
+    [
+        Axis(annot=True, tick=True, grid=True),
+        "afg",
+        Frame(axis=Axis(annot=True, tick=True, grid=True)),
+    ],
+    ids=["axis", "string", "frame-axis"],
+)
+@pytest.mark.mpl_image_compare(filename="test_ternary_axis.png")
+def test_ternary_axis(array, frame):
+    """
+    Test plotting a ternary chart with equivalent frame settings.
+    """
+    fig = Figure()
+    fig.ternary(
+        data=array,
+        region=[0, 100, 0, 100, 0, 100],
+        cmap="red,orange,yellow,green,blue,violet",
+        width="10c",
+        frame=frame,
+        style="c0.1c",
+        pen="thinnest",
+    )
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_ternary_no_frame(array):
+    """
+    Test plotting a ternary chart with frame set to "none".
+    """
+    fig = Figure()
+    fig.ternary(
+        data=array,
+        region=[0, 100, 0, 100, 0, 100],
+        cmap="red,orange,yellow,green,blue,violet",
+        width="10c",
+        frame="none",
         style="c0.1c",
         pen="thinnest",
     )