Figure.wiggle: Deprecate parameters fillnegative/fillpositive to negative_fill/positive_fill (Will be removed in v0.20.0) (#4271)

Author: yvonnefroehlich

examples/gallery/lines/wiggle.py

@@ -6,7 +6,7 @@
 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 ``fillpositive`` and/or ``fillnegative``
+filled with color by setting the ``positive_fill`` and/or ``negative_fill``
 parameters.
 """
 
@@ -28,9 +28,9 @@
     # Set anomaly scale to 20 centimeters
     scale="20c",
     # Fill positive areas red
-    fillpositive="red",
+    positive_fill="red",
     # Fill negative areas gray
-    fillnegative="gray",
+    negative_fill="gray",
     # Set the outline width to 1.0 point
     pen="1.0p",
     # Draw a blue track with a width of 0.5 points

examples/gallery/symbols/patterns.py

@@ -17,7 +17,7 @@
 - :meth:`pygmt.Figure.ternary`: Symbols via ``fill``
 - :meth:`pygmt.Figure.velo`: Uncertainty wedges and velocity error ellipses via
   ``uncertaintyfill``
-- :meth:`pygmt.Figure.wiggle`: Anomalies via ``fillpositive`` and ``fillnegative``
+- :meth:`pygmt.Figure.wiggle`: Anomalies via ``positive_fill`` and ``negative_fill``
 
 GMT provides 90 predefined 1-bit patterns, which are numbered from 1 to 90. In addition,
 custom 1-, 8-, or 24-bit image raster files can also be used as patterns.

pygmt/src/wiggle.py

@@ -8,12 +8,12 @@
 from pygmt._typing import PathLike, TableLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
+from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
 
 
-def _parse_fills(fillpositive, fillnegative):
+def _parse_fills(positive_fill, negative_fill):
     """
-    Parse the fillpositive and fillnegative parameters.
+    Parse the positive_fill and negative_fill parameters.
 
     >>> _parse_fills("red", "blue")
     ['red+p', 'blue+n']
@@ -24,10 +24,10 @@ def _parse_fills(fillpositive, fillnegative):
     >>> _parse_fills(None, None)
     """
     _fills = []
-    if fillpositive is not None:
-        _fills.append(fillpositive + "+p")
-    if fillnegative is not None:
-        _fills.append(fillnegative + "+n")
+    if positive_fill is not None:
+        _fills.append(positive_fill + "+p")
+    if negative_fill is not None:
+        _fills.append(negative_fill + "+n")
 
     match len(_fills):
         case 0:
@@ -39,6 +39,12 @@ def _parse_fills(fillpositive, fillnegative):
 
 
 @fmt_docstring
+@deprecate_parameter(
+    "fillpositive", "positive_fill", "v0.18.0", remove_version="v0.20.0"
+)
+@deprecate_parameter(
+    "fillnegative", "negative_fill", "v0.18.0", remove_version="v0.20.0"
+)
 @use_alias(
     D="position",
     T="track",
@@ -58,8 +64,8 @@ def wiggle(  # noqa: PLR0913
     x=None,
     y=None,
     z=None,
-    fillpositive=None,
-    fillnegative=None,
+    positive_fill=None,
+    negative_fill=None,
     projection: str | None = None,
     region: Sequence[float | str] | str | None = None,
     frame: str | Sequence[str] | bool = False,
@@ -83,7 +89,7 @@ def wiggle(  # noqa: PLR0913
 
     $aliases
        - B = frame
-       - G = **+p**: fillpositive, **+n**: fillnegative
+       - G = **+p**: positive_fill, **+n**: negative_fill
        - J = projection
        - R = region
        - V = verbose
@@ -114,9 +120,9 @@ def wiggle(  # noqa: PLR0913
         **+w**\ *length*\ [**+j**\ *justify*]\ [**+al**\|\ **r**]\
         [**+o**\ *dx*\ [/*dy*]][**+l**\ [*label*]].
         Define the reference point on the map for the vertical scale bar.
-    fillpositive : str
+    positive_fill : str
         Set color or pattern for filling positive wiggles [Default is no fill].
-    fillnegative : str
+    negative_fill : str
         Set color or pattern for filling negative wiggles [Default is no fill].
     track : str
         Draw track [Default is no track]. Append pen attributes to use
@@ -138,10 +144,10 @@ def wiggle(  # noqa: PLR0913
     """
     self._activate_figure()
 
-    _fills = _parse_fills(fillpositive, fillnegative)
+    _fills = _parse_fills(positive_fill, negative_fill)
 
     aliasdict = AliasSystem(
-        G=Alias(_fills, name="fillpositive/fillnegative"),
+        G=Alias(_fills, name="positive_fill/negative_fill"),
     ).add_common(
         B=frame,
         J=projection,

pygmt/tests/test_wiggle.py

@@ -24,8 +24,8 @@ def test_wiggle():
         y=y,
         z=z,
         scale="0.5c",
-        fillpositive="red",
-        fillnegative="gray",
+        positive_fill="red",
+        negative_fill="gray",
         pen="1.0p",
         track="0.5p",
         position="jRM+w2+lnT",
@@ -54,8 +54,8 @@ def test_wiggle_data_incols():
         projection="X8c",
         incols=[1, 0, 2],
         scale="0.5c",
-        fillpositive="red",
-        fillnegative="gray",
+        positive_fill="red",
+        negative_fill="gray",
         pen="1.0p",
         track="0.5p",
         position="jRM+w2+lnT",