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}

pygmt/src/image.py

@@ -14,8 +14,6 @@
     M="monochrome",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -57,7 +55,6 @@ def image(self, imagefile, **kwargs):
         YIQ-transformation.
     {timestamp}
     {verbose}
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/legend.py

@@ -21,8 +21,6 @@
     F="box",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -67,7 +65,6 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         1p black pen and adds a white background.
     {timestamp}
     {verbose}
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/logo.py

@@ -15,8 +15,6 @@
     S="style",
     U="timestamp",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     t="transparency",
 )
@@ -55,7 +53,6 @@ def logo(self, **kwargs):
         - **u** to place the URL to the GMT site
     {timestamp}
     {verbose}
-    {xyshift}
     {panel}
     {transparency}
     """

pygmt/src/meca.py

@@ -81,8 +81,6 @@ def data_format_code(convention, component="full"):
     B="frame",
     N="no_clip",
     V="verbose",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -220,7 +218,6 @@ def meca(
     {region}
     {frame}
     {verbose}
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/plot.py

@@ -34,8 +34,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     Z="zvalue",
     a="aspatial",
     b="binary",
@@ -187,7 +185,6 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     {pen}
     {timestamp}
     {verbose}
-    {xyshift}
     zvalue : str
         *value*\|\ *file*.
         Instead of specifying a symbol or polygon fill and outline color

pygmt/src/plot3d.py

@@ -34,8 +34,6 @@
     S="style",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     Z="zvalue",
     a="aspatial",
     b="binary",
@@ -156,7 +154,6 @@ def plot3d(
     {timestamp}
     {verbose}
     {pen}
-    {xyshift}
     zvalue : str
         *value*\|\ *file*.
         Instead of specifying a symbol or polygon fill and outline color

pygmt/src/rose.py

@@ -33,8 +33,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     Z="scale",
     b="binary",
     d="nodata",
@@ -193,7 +191,6 @@ def rose(self, data=None, length=None, azimuth=None, **kwargs):
 
     {timestamp}
     {verbose}
-    {xyshift}
     {binary}
     {panel}
     {nodata}

pygmt/src/solar.py

@@ -18,8 +18,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -60,7 +58,6 @@ def solar(self, terminator="d", terminator_datetime=None, **kwargs):
         Set pen attributes for lines [Default is ``"0.25p,black,solid"``].
     {timestamp}
     {verbose}
-    {xyshift}
     {panel}
     {perspective}
     {transparency}

pygmt/src/subplot.py

@@ -29,8 +29,6 @@
     SR="sharey",
     T="title",
     V="verbose",
-    X="xshift",
-    Y="yshift",
 )
 @kwargs_to_strings(Ff="sequence", Fs="sequence", M="sequence", R="sequence")
 def subplot(self, nrows=1, ncols=1, **kwargs):
@@ -146,7 +144,6 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         ``frame``), the entire figure may also have an overarching *heading*
         [no heading]. Font is determined by setting :gmt-term:`FONT_HEADING`.
     {verbose}
-    {xyshift}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
 

pygmt/src/ternary.py

@@ -16,8 +16,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     c="panel",
     p="perspective",
     t="transparency",
@@ -66,7 +64,6 @@ def ternary(self, data, alabel=None, blabel=None, clabel=None, **kwargs):
         *symbol*\[\ *size*].
         Plot individual symbols in a ternary diagram.
     {pen}
-    {xyshift}
     {timestamp}
     {verbose}
     {panel}

pygmt/src/text.py

@@ -28,8 +28,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     a="aspatial",
     c="panel",
     e="find",
@@ -153,7 +151,6 @@ def text_(
         Do NOT clip text at map boundaries [Default is with clip].
     {timestamp}
     {verbose}
-    {xyshift}
     {aspatial}
     {panel}
     {find}

pygmt/src/velo.py

@@ -26,8 +26,6 @@
     U="timestamp",
     V="verbose",
     W="pen",
-    X="xshift",
-    Y="yshift",
     Z="zvalue",
     c="panel",
     d="nodata",
@@ -218,7 +216,6 @@ def velo(self, data=None, **kwargs):
         updated from the CPT (see ``cmap``). If instead modifier **+cf** is
         appended then the color from the cpt file is applied to symbol fill
         only [Default].  Use just **+c** to set both pen and fill color.
-    {xyshift}
     zvalue : str
         [**m**\|\ **e**\|\ **n**\|\ **u**\ ][**+e**].
         Select the quantity that will be used with the CPT given via ``cmap``