Figure.wiggle: Deprecate parameter "color" (remove in v0.12.0) and add "fillpositive"/"fillnegative" (#2205)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Yvonne Fröhlich <[email protected]>

Author: 3 people

examples/gallery/lines/wiggle.py

@@ -6,7 +6,8 @@
 tracks. ``x``, ``y``, ``z`` can be specified as 1-D arrays or within a
 specified file. The ``scale`` parameter can be used to set the scale of the
 anomaly in data/distance units. The positive and/or negative areas can be
-filled with color by setting the ``color`` parameter.
+filled with color by setting the ``fillpositive`` and/or ``fillnegative``
+parameters.
 """
 
 import numpy as np
@@ -25,8 +26,10 @@
     z=z,
     # Set anomaly scale to 20 centimeters
     scale="20c",
-    # Fill positive and negative areas red and gray, respectively
-    color=["red+p", "gray+n"],
+    # Fill positive areas red
+    fillpositive="red",
+    # Fill negative areas gray
+    fillnegative="gray",
     # Set the outline width to 1.0 point
     pen="1.0p",
     # Draw a blue track with a width of 0.5 points

pygmt/src/wiggle.py

@@ -1,7 +1,10 @@
 """
 wiggle - Plot z=f(x,y) anomalies along tracks.
 """
+import warnings
+
 from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
 
 
@@ -30,7 +33,16 @@
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def wiggle(self, data=None, x=None, y=None, z=None, **kwargs):
+def wiggle(
+    self,
+    data=None,
+    x=None,
+    y=None,
+    z=None,
+    fillpositive=None,
+    fillnegative=None,
+    **kwargs
+):
     r"""
     Plot z=f(x,y) anomalies along tracks.
 
@@ -65,14 +77,12 @@ def wiggle(self, data=None, x=None, y=None, z=None, **kwargs):
         **+w**\ *length*\ [**+j**\ *justify*]\ [**+al**\|\ **r**]\
         [**+o**\ *dx*\ [/*dy*]][**+l**\ [*label*]].
         Defines the reference point on the map for the vertical scale bar.
-    color : str
-        Set fill shade, color or pattern for positive and/or negative wiggles
-        [Default is no fill]. Optionally, append **+p** to fill positive areas
-        (this is the default behavior). Append **+n** to fill negative areas.
-        Append **+n+p** to fill both positive and negative areas with the same
-        fill. **Note**: You will need to repeat the color parameter to select
-        different fills for the positive and negative wiggles.
-
+    fillpositive : str
+        Set fill shade, color, or pattern for positive wiggles [Default is no
+        fill].
+    fillnegative : str
+        Set fill shade, color, or pattern for negative wiggles [Default is no
+        fill].
     track : str
         Draw track [Default is no track]. Append pen attributes to use
         [Default is ``"0.25p,black,solid"``].
@@ -94,6 +104,24 @@ def wiggle(self, data=None, x=None, y=None, z=None, **kwargs):
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
 
+    if (fillpositive or fillnegative) and kwargs.get("G") is not None:
+        raise GMTInvalidInput("Use either fillpositive/fillnegative or color.")
+
+    if kwargs.get("G") is not None:
+        msg = (
+            "The 'color' parameter has been deprecated since v0.8.0"
+            " and will be removed in v0.12.0. Use fillpositive/fillnegative"
+            " instead."
+        )
+        warnings.warn(msg, category=FutureWarning, stacklevel=2)
+
+    if fillpositive or fillnegative:
+        kwargs["G"] = []
+        if fillpositive:
+            kwargs["G"].append(fillpositive + "+p")
+        if fillnegative:
+            kwargs["G"].append(fillnegative + "+n")
+
     with Session() as lib:
         # Choose how data will be passed in to the module
         file_context = lib.virtualfile_from_data(

pygmt/tests/test_wiggle.py

@@ -4,6 +4,7 @@
 import numpy as np
 import pytest
 from pygmt import Figure
+from pygmt.exceptions import GMTInvalidInput
 
 
 @pytest.mark.mpl_image_compare
@@ -23,7 +24,8 @@ def test_wiggle():
         y=y,
         z=z,
         scale="0.5c",
-        color=["red+p", "gray+n"],
+        fillpositive="red",
+        fillnegative="gray",
         pen="1.0p",
         track="0.5p",
         position="jRM+w2+lnT",
@@ -51,9 +53,65 @@ def test_wiggle_data_incols():
         projection="X8c",
         incols=[1, 0, 2],
         scale="0.5c",
-        color=["red+p", "gray+n"],
+        fillpositive="red",
+        fillnegative="gray",
         pen="1.0p",
         track="0.5p",
         position="jRM+w2+lnT",
     )
     return fig
+
+
+def test_wiggle_fill_multiple():
+    """
+    Check that wiggle fails when the parameters color and
+    fillpositive/fillnegative are used together.
+    """
+    x = np.arange(-2, 2, 0.02)
+    y = np.zeros(x.size)
+    z = np.cos(2 * np.pi * x)
+
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        fig.wiggle(
+            x=x,
+            y=y,
+            z=z,
+            region=[-4, 4, -1, 1],
+            projection="X8c",
+            incols=[1, 0, 2],
+            scale="0.5c",
+            color="blue",
+            fillpositive="red",
+            fillnegative="gray",
+            pen="1.0p",
+            track="0.5p",
+            position="jRM+w2+lnT",
+        )
+
+
+def test_wiggle_use_color():
+    """
+    Check that wiggle raises a warning when the deprecated parameter color is
+    used.
+    """
+    x = np.arange(-2, 2, 0.02)
+    y = np.zeros(x.size)
+    z = np.cos(2 * np.pi * x)
+
+    fig = Figure()
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        fig.wiggle(
+            x=x,
+            y=y,
+            z=z,
+            region=[-4, 4, -1, 1],
+            projection="X8c",
+            incols=[1, 0, 2],
+            scale="0.5c",
+            color="blue",
+            pen="1.0p",
+            track="0.5p",
+            position="jRM+w2+lnT",
+        )
+        assert len(record) == 1