From 4777a6f11a6dc329bab88636b2b98c0829aa50fe Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 7 May 2021 00:06:21 -0400 Subject: [PATCH] Figure.plot3d: Deprecate parameter "sizes" to "size" (remove in v0.6.0) (#1258) * Rename 'sizes' to 'size' * 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: Michael Grund <23025878+michaelgrund@users.noreply.github.com> Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- examples/gallery/3d_plots/scatter3d.py | 2 +- pygmt/src/plot3d.py | 14 +++++---- pygmt/tests/test_plot3d.py | 39 ++++++++++++++++++++++---- 3 files changed, 42 insertions(+), 13 deletions(-) diff --git a/examples/gallery/3d_plots/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py index 568c2de7cbd..0c70581fe32 100644 --- a/examples/gallery/3d_plots/scatter3d.py +++ b/examples/gallery/3d_plots/scatter3d.py @@ -47,7 +47,7 @@ y=df.sepal_length, z=df.petal_length, # Vary each symbol size according to another feature (sepal width, scaled by 0.1) - sizes=0.1 * df.sepal_width, + size=0.1 * df.sepal_width, # Use 3D cubes ("u") as symbols, with size in centimeter units ("c") style="uc", # Points colored by categorical number code diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index 85b4826cae4..e6944c8e152 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.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,8 +44,9 @@ t="transparency", ) @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence") +@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0") def plot3d( - self, x=None, y=None, z=None, data=None, sizes=None, direction=None, **kwargs + self, x=None, y=None, z=None, data=None, size=None, direction=None, **kwargs ): r""" Plot lines, polygons, and symbols in 3-D. @@ -80,8 +82,8 @@ def plot3d( Either a data file name or a 2d numpy array with the tabular data. Use parameter ``columns`` to choose which columns are x, y, z, color, and size, respectively. - sizes : 1d array - The sizes of the data points in units specified in ``style``. + size : 1d array + The size of the data points in units specified in ``style``. Only valid if using ``x``/``y``/``z``. direction : list of two 1d arrays If plotting vectors (using ``style='V'`` or ``style='v'``), then @@ -179,12 +181,12 @@ def plot3d( ) 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 a file." ) - extra_arrays.append(sizes) + extra_arrays.append(size) for flag in ["I", "t"]: if flag in kwargs and is_nonstr_iter(kwargs[flag]): diff --git a/pygmt/tests/test_plot3d.py b/pygmt/tests/test_plot3d.py index 492e95a9ca5..05708f7f67a 100644 --- a/pygmt/tests/test_plot3d.py +++ b/pygmt/tests/test_plot3d.py @@ -110,7 +110,7 @@ def test_plot3d_fail_no_data(data, region): def test_plot3d_fail_color_size_intensity(data, region): """ - 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() @@ -118,7 +118,7 @@ def test_plot3d_fail_color_size_intensity(data, region): with pytest.raises(GMTInvalidInput): fig.plot3d(style="c0.2c", color=data[:, 2], **kwargs) with pytest.raises(GMTInvalidInput): - fig.plot3d(style="cc", sizes=data[:, 2], color="red", **kwargs) + fig.plot3d(style="cc", size=data[:, 2], color="red", **kwargs) with pytest.raises(GMTInvalidInput): fig.plot3d(style="cc", intensity=data[:, 2], color="red", **kwargs) @@ -178,7 +178,7 @@ def test_plot3d_sizes(data, region): z=data[:, 2], zscale=5, perspective=[225, 30], - sizes=0.5 * data[:, 2], + size=0.5 * data[:, 2], region=region, projection="X10c", # Using inches instead of cm because of upstream bug at @@ -203,7 +203,7 @@ def test_plot3d_colors_sizes(data, region): zscale=5, perspective=[225, 30], color=data[:, 2], - sizes=0.5 * data[:, 2], + size=0.5 * data[:, 2], region=region, projection="X6c", # Using inches instead of cm because of upstream bug at @@ -231,7 +231,7 @@ def test_plot3d_colors_sizes_proj(data, region): projection="M20c", frame=["af", "zaf"], color=data[:, 2], - sizes=data[:, 2], + size=data[:, 2], # Using inches instead of cm because of upstream bug at # https://github.com/GenericMappingTools/gmt/issues/4386 style="ui", @@ -343,7 +343,7 @@ def test_plot3d_sizes_colors_transparencies(): frame=True, style="uc", color=color, - sizes=size, + size=size, cmap="gray", transparency=transparency, ) @@ -458,3 +458,30 @@ def test_plot3d_scalar_xyz(): x=1.5, y=-1.5, z=1.5, style="s1c", color="blue", zscale=True, perspective=True ) return fig + + +@pytest.mark.mpl_image_compare(filename="test_plot3d_sizes.png") +def test_plot3d_deprecate_sizes_to_size(data, region): + """ + Make sure that the old parameter "sizes" is supported and it reports an + warning. + + Modified from the test_plot3d_sizes() test. + """ + fig = Figure() + with pytest.warns(expected_warning=FutureWarning) as record: + fig.plot3d( + x=data[:, 0], + y=data[:, 1], + z=data[:, 2], + zscale=5, + perspective=[225, 30], + sizes=0.5 * data[:, 2], + region=region, + projection="X10c", + style="ui", + color="blue", + frame=["af", "zaf"], + ) + assert len(record) == 1 # check that only one warning was raised + return fig