Deprecate xshift (X) and yshift (Y) aliases from all plotting modules (remove in v0.12.0) (#2071)

Co-authored-by: Dongdong Tian <[email protected]>

Author: michaelgrund

examples/gallery/3d_plots/scatter3d.py

@@ -90,7 +90,9 @@
     zscale=1.5,
 )
 
+# Shift plot origin in x direction
+fig.shift_origin(xshift=3.1)
 # Add colorbar legend
-fig.colorbar(xshift=3.1)
+fig.colorbar()
 
 fig.show()

pygmt/helpers/decorators.py

@@ -97,15 +97,6 @@
     "pen": """\
         pen : str
             Set pen attributes for lines or the outline of symbols.""",
-    "xyshift": r"""
-        xshift : str
-            [**a**\|\ **c**\|\ **f**\|\ **r**\][*xshift*].
-            Shift plot origin in x-direction.
-        yshift : str
-            [**a**\|\ **c**\|\ **f**\|\ **r**\][*yshift*].
-            Shift plot origin in y-direction. Full documentation is at
-            :gmt-docs:`gmt.html#xy-full`.
-         """,
     "aspatial": r"""
         aspatial : bool or str
             [*col*\ =]\ *name*\ [,...].
@@ -577,6 +568,29 @@ def new_module(*args, **kwargs):
                         f"Use long-form parameter '{long_alias}' instead."
                     )
                     warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+
+            # xshift (X) is deprecated since v0.8.0.
+            if "X" in kwargs or "xshift" in kwargs:
+                if "xshift" in kwargs:
+                    kwargs["X"] = kwargs.pop("xshift")
+                msg = (
+                    "Parameters 'X' and 'xshift' are deprecated since v0.8.0 "
+                    "and will be removed in v0.12.0. "
+                    "Use Figure.shift_origin(xshift=...) instead."
+                )
+                warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+
+            # yshift (Y) is deprecated since v0.8.0.
+            if "Y" in kwargs or "yshift" in kwargs:
+                if "yshift" in kwargs:
+                    kwargs["Y"] = kwargs.pop("yshift")
+                msg = (
+                    "Parameters 'Y' and 'yshift' are deprecated since v0.8.0. "
+                    "and will be removed in v0.12.0. "
+                    "Use Figure.shift_origin(yshift=...) instead."
+                )
+                warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+
             return module_func(*args, **kwargs)
 
         new_module.aliases = aliases

pygmt/src/basemap.py

@@ -25,8 +25,6 @@
     Tm="compass",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     f="coltypes",
     p="perspective",
@@ -84,7 +82,6 @@ def basemap(self, **kwargs):
         reference and anchor points
     {timestamp}
     {verbose}
-    {xyshift}
     {panel}
     {coltypes}
     {perspective}

pygmt/src/coast.py

@@ -32,8 +32,6 @@
     S="water",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -177,7 +175,6 @@ def coast(self, **kwargs):
         [Default is no fill]. Append **+l**\|\ **+L** to =\ *continent* to
         only list countries in that continent; repeat if more than one
         continent is requested.
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/colorbar.py

@@ -18,8 +18,6 @@
     I="shading",
     W="scale",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -100,7 +98,6 @@ def colorbar(self, **kwargs):
         asymmetric intensity range from *low* to *high*. [Default is no
         illumination].
     {verbose}
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/contour.py

@@ -20,8 +20,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     b="binary",
     c="panel",
     d="nodata",
@@ -106,7 +104,6 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
         separator for the two labels instead.
     {timestamp}
     {verbose}
-    {xyshift}
     {binary}
     {panel}
     {nodata}

pygmt/src/grdcontour.py

@@ -22,8 +22,6 @@
     V="verbose",
     W="pen",
     l="label",
-    X="xshift",
-    Y="yshift",
     c="panel",
     f="coltypes",
     p="perspective",
@@ -85,7 +83,6 @@ def grdcontour(self, grid, **kwargs):
     {timestamp}
     {verbose}
     {pen}
-    {xyshift}
     {panel}
     {coltypes}
     label : str

pygmt/src/grdimage.py

@@ -31,8 +31,6 @@
     R="region",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     n="interpolation",
     c="panel",
     f="coltypes",
@@ -156,7 +154,6 @@ def grdimage(self, grid, **kwargs):
         3).
     {region}
     {verbose}
-    {xyshift}
     {panel}
     {coltypes}
     {interpolation}

pygmt/src/grdview.py

@@ -30,8 +30,6 @@
     Wf="facadepen",
     I="shading",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     f="coltypes",
     n="interpolation",
@@ -114,7 +112,6 @@ def grdview(self, grid, **kwargs):
         or just give **+d** to select the default arguments
         [Default is **+a**\ -45\ **+nt**\ 1\ **+m**\ 0].
     {verbose}
-    {xyshift}
     {panel}
     {coltypes}
     {interpolation}

pygmt/src/histogram.py

@@ -24,8 +24,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     Z="histtype",
     b="binary",
     c="panel",
@@ -124,7 +122,6 @@ def histogram(self, data, **kwargs):
 
         To use weights provided as a second data column instead of pure counts,
         append **+w**.
-    {xyshift}
     {timestamp}
     {verbose}
     {binary}