Figure.plot: Deprecate parameter "color" to "fill" (remove in v0.12.0) (

GenericMappingTools#2177)

pygmt/src/plot.py

@@ -6,6 +6,7 @@
 from pygmt.helpers import (
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -15,14 +16,15 @@
 
 
 @fmt_docstring
+@deprecate_parameter("color", "fill", "v0.8.0", "v0.12.0")
 @use_alias(
     A="straight_line",
     B="frame",
     C="cmap",
     D="offset",
     E="error_bar",
     F="connection",
-    G="color",
+    G="fill",
     I="intensity",
     J="projection",
     L="close",
@@ -59,7 +61,7 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
 
     Must provide either ``data`` or ``x``/``y``.
 
-    If providing data through ``x``/``y``, ``color`` can be a 1d array that
+    If providing data through ``x``/``y``, ``fill`` can be a 1d array that
     will be mapped to a colormap.
 
     If a symbol is selected and no symbol size given, then plot will
@@ -68,8 +70,8 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     symbol code (see ``style`` below) must be present as last column in the
     input. If ``style`` is not used, a line connecting the data points will
     be drawn instead. To explicitly close polygons, use ``close``. Select a
-    fill with ``color``. If ``color`` is set, ``pen`` will control whether the
-    polygon outline is drawn or not. If a symbol is selected, ``color`` and
+    fill with ``fill``. If ``fill`` is set, ``pen`` will control whether the
+    polygon outline is drawn or not. If a symbol is selected, ``fill`` and
     ``pen`` determines the fill and outline/no outline, respectively.
 
     Full option list at :gmt-docs:`plot.html`
@@ -81,7 +83,7 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     data : str or {table-like}
         Pass in either a file name to an ASCII data table, a 2D
         {table-classes}.
-        Use parameter ``incols`` to choose which columns are x, y, color, and
+        Use parameter ``incols`` to choose which columns are x, y, fill, and
         size, respectively.
     x/y : float or 1d arrays
         The x and y coordinates, or arrays of x and y coordinates of the
@@ -152,8 +154,8 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
         Instead of the codes **a**\|\ **f**\|\ **s**\|\ **r** you may append
         the coordinates of a *refpoint* which will serve as a fixed external
         reference point for all groups.
-    {color}
-        *color* can be a 1d array, but it is only valid if using ``x``/``y``
+    {fill}
+        *fill* can be a 1d array, but it is only valid if using ``x``/``y``
         and ``cmap=True`` is also required.
     intensity : float or bool or 1d array
         Provide an *intensity* value (nominally in the -1 to +1 range) to
@@ -189,11 +191,11 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     zvalue : str
         *value*\|\ *file*.
         Instead of specifying a symbol or polygon fill and outline color
-        via ``color`` and ``pen``, give both a *value* via ``zvalue`` and a
+        via ``fill`` and ``pen``, give both a *value* via ``zvalue`` and a
         color lookup table via ``cmap``.  Alternatively, give the name of a
         *file* with one z-value (read from the last column) for each
         polygon in the input data. To apply it to the fill color, use
-        ``color="+z"``. To apply it to the pen color, append **+z** to
+        ``fill="+z"``. To apply it to the pen color, append **+z** to
         ``pen``.
     {aspatial}
     {binary}
@@ -239,7 +241,7 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     if kwargs.get("G") is not None and is_nonstr_iter(kwargs["G"]):
         if kind != "vectors":
             raise GMTInvalidInput(
-                "Can't use arrays for color if data is matrix or file."
+                "Can't use arrays for fill if data is matrix or file."
             )
         extra_arrays.append(kwargs["G"])
         del kwargs["G"]