Figure.plot: Deprecate parameter "sizes" to "size" (remove in v0.6.0) (…

…#1254)

* Rename sizes to size in Figure.plot()
* Updates tests and examples to use the new parameter name
* Use the deprecate_parameter decorator for backward-compatibility
* Add a test for checking 'sizes' backward compatibility

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

examples/gallery/symbols/points_categorical.py

@@ -53,7 +53,7 @@
     x=df.bill_length_mm,
     y=df.bill_depth_mm,
     # Vary each symbol size according to another feature (body mass, scaled by 7.5*10e-5)
-    sizes=df.body_mass_g * 7.5e-5,
+    size=df.body_mass_g * 7.5e-5,
     # Points colored by categorical number code
     color=df.species.cat.codes.astype(int),
     # Use colormap created by makecpt

examples/gallery/symbols/scatter.py

@@ -23,13 +23,13 @@
 )
 for color in ["gray73", "darkorange", "slateblue"]:
     x, y = np.random.rand(2, n)  # random X and Y data in [0,1]
-    sizes = np.random.rand(n) * 0.5  # random size [0,0.5], in cm
+    size = np.random.rand(n) * 0.5  # random size [0,0.5], in cm
     # plot data points as circles (style="c"), with different sizes
     fig.plot(
         x=x,
         y=y,
         style="c",
-        sizes=sizes,
+        size=size,
         color=color,
         # Set the legend label,
         # and set the symbol size to be 0.25 cm (+S0.25c) in legend

examples/tutorials/plot.py

@@ -45,7 +45,7 @@
 # parameter controls the outline of the symbols and the ``color`` parameter controls the fill.
 #
 # We can map the size of the circles to the earthquake magnitude by passing an array to
-# the ``sizes`` parameter. Because the magnitude is on a logarithmic scale, it helps to
+# the ``size`` parameter. Because the magnitude is on a logarithmic scale, it helps to
 # show the differences by scaling the values using a power law.
 
 fig = pygmt.Figure()
@@ -54,7 +54,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    sizes=0.02 * (2 ** data.magnitude),
+    size=0.02 * (2 ** data.magnitude),
     style="cc",
     color="white",
     pen="black",
@@ -63,7 +63,7 @@
 
 ########################################################################################
 # Notice that we didn't include the size in the ``style`` parameter this time, just the
-# symbol ``c`` (circles) and the unit ``c`` (centimeter). So in this case, the sizes
+# symbol ``c`` (circles) and the unit ``c`` (centimeter). So in this case, the size
 # will be interpreted as being in centimeters.
 #
 # We can also map the colors of the markers to the depths by passing an array to the
@@ -82,7 +82,7 @@
 fig.plot(
     x=data.longitude,
     y=data.latitude,
-    sizes=0.02 * 2 ** data.magnitude,
+    size=0.02 * 2 ** data.magnitude,
     color=data.depth_km,
     cmap=True,
     style="cc",

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,
@@ -43,7 +44,8 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
+@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
+def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
     r"""
     Plot lines, polygons, and symbols in 2-D.
 
@@ -78,8 +80,8 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         Either a data file name or a 2d numpy array with the tabular data.
         Use parameter ``columns`` to choose which columns are x, y, color,
         and size, respectively.
-    sizes : 1d array
-        The sizes of the data points in units specified using ``style``.
+    size : 1d array
+        The size of the data points in units specified using ``style``.
         Only valid if using ``x``/``y``.
     direction : list of two 1d arrays
         If plotting vectors (using ``style='V'`` or ``style='v'``), then
@@ -215,12 +217,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             )
         extra_arrays.append(kwargs["G"])
         del kwargs["G"]
-    if sizes is not None:
+    if size is not None:
         if kind != "vectors":
             raise GMTInvalidInput(
-                "Can't use arrays for sizes if data is matrix or file."
+                "Can't use arrays for 'size' if data is a matrix or file."
             )
-        extra_arrays.append(sizes)
+        extra_arrays.append(size)
 
     for flag in ["I", "t"]:
         if flag in kwargs and is_nonstr_iter(kwargs[flag]):

pygmt/tests/test_plot.py

@@ -93,15 +93,15 @@ def test_plot_fail_no_data(data):
 
 def test_plot_fail_color_size_intensity(data):
     """
-    Should raise an exception if array color, sizes and intensity are used with
+    Should raise an exception if array color, size and intensity are used with
     matrix.
     """
     fig = Figure()
     kwargs = dict(data=data, region=region, projection="X10c", frame="afg")
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", color=data[:, 2], **kwargs)
     with pytest.raises(GMTInvalidInput):
-        fig.plot(style="cc", sizes=data[:, 2], color="red", **kwargs)
+        fig.plot(style="cc", size=data[:, 2], color="red", **kwargs)
     with pytest.raises(GMTInvalidInput):
         fig.plot(style="c0.2c", color="red", intensity=data[:, 2], **kwargs)
 
@@ -152,7 +152,7 @@ def test_plot_sizes(data, region):
     fig.plot(
         x=data[:, 0],
         y=data[:, 1],
-        sizes=0.5 * data[:, 2],
+        size=0.5 * data[:, 2],
         region=region,
         projection="X10c",
         style="cc",
@@ -172,7 +172,7 @@ def test_plot_colors_sizes(data, region):
         x=data[:, 0],
         y=data[:, 1],
         color=data[:, 2],
-        sizes=0.5 * data[:, 2],
+        size=0.5 * data[:, 2],
         region=region,
         projection="X10c",
         style="cc",
@@ -193,7 +193,7 @@ def test_plot_colors_sizes_proj(data, region):
         x=data[:, 0],
         y=data[:, 1],
         color=data[:, 2],
-        sizes=0.5 * data[:, 2],
+        size=0.5 * data[:, 2],
         style="cc",
         cmap="copper",
     )
@@ -288,7 +288,7 @@ def test_plot_sizes_colors_transparencies():
         frame=True,
         style="cc",
         color=color,
-        sizes=size,
+        size=size,
         cmap="gray",
         transparency=transparency,
     )
@@ -446,3 +446,27 @@ def test_plot_datetime():
     y = [8.5, 9.5]
     fig.plot(x, y, style="i0.2c", pen="1p")
     return fig
+
+
+@pytest.mark.mpl_image_compare(filename="test_plot_sizes.png")
+def test_plot_deprecate_sizes_to_size(data, region):
+    """
+    Make sure that the old parameter "sizes" is supported and it reports an
+    warning.
+
+    Modified from the test_plot_sizes() test.
+    """
+    fig = Figure()
+    with pytest.warns(expected_warning=FutureWarning) as record:
+        fig.plot(
+            x=data[:, 0],
+            y=data[:, 1],
+            sizes=0.5 * data[:, 2],
+            region=region,
+            projection="X10c",
+            style="cc",
+            color="blue",
+            frame="af",
+        )
+        assert len(record) == 1  # check that only one warning was raised
+    return fig