Add common aliases xshift (X) and yshift (Y) (#624)

Used for shifting plots along the x and y dimensions.

* Merge {X} and {Y} into a single {XY} common option

Also added link to full documentation of xshift/yshift
at https://docs.generic-mapping-tools.org/latest/gmt.html#xy-full

* Add xshift/yshift long alias to all plotting functions

Author: weiji14

pygmt/base_plotting.py

@@ -68,6 +68,8 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         G="land",
         S="water",
         U="timestamp",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -129,6 +131,7 @@ def coast(self, **kwargs):
         shorelines : str
             ``'[level/]pen'``
             Draw shorelines [Default is no shorelines]. Append pen attributes.
+        {XY}
         {t}
 
         """
@@ -146,6 +149,8 @@ def coast(self, **kwargs):
         F="box",
         G="truncate",
         W="scale",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", G="sequence")
@@ -208,6 +213,7 @@ def colorbar(self, **kwargs):
         scale : float
             Multiply all z-values in the CPT by the provided scale. By default
             the CPT is used as is.
+        {XY}
         {t}
 
         """
@@ -229,6 +235,8 @@ def colorbar(self, **kwargs):
         U="timestamp",
         W="pen",
         l="label",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus")
@@ -279,6 +287,7 @@ def grdcontour(self, grid, **kwargs):
         {G}
         {U}
         {W}
+        {XY}
         label : str
             Add a legend entry for the contour being plotted. Normally, the
             annotated contour is selected for the legend. You can select the
@@ -309,6 +318,8 @@ def grdcontour(self, grid, **kwargs):
         B="frame",
         I="shading",
         C="cmap",
+        X="xshift",
+        Y="yshift",
         t="transparency",
         x="cores",
     )
@@ -327,6 +338,7 @@ def grdimage(self, grid, **kwargs):
         ----------
         grid : str or xarray.DataArray
             The file name of the input grid or the grid loaded as a DataArray.
+        {XY}
         {t}
         {x}
 
@@ -360,6 +372,8 @@ def grdimage(self, grid, **kwargs):
         Wf="facadepen",
         p="perspective",
         I="shading",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", p="sequence")
@@ -437,6 +451,7 @@ def grdview(self, grid, **kwargs):
             intensity, and ambient arguments for that module, or just give
             ``+d`` to select the default arguments (``+a-45+nt1+m0``).
 
+        {XY}
         {t}
 
         """
@@ -478,6 +493,8 @@ def grdview(self, grid, **kwargs):
         l="label",
         C="cmap",
         U="timestamp",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", i="sequence_comma")
@@ -546,6 +563,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             quoted lines).
         {W}
         {U}
+        {XY}
         label : str
             Add a legend entry for the symbol or line being plotted.
 
@@ -599,6 +617,8 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         i="columns",
         l="label",
         C="levels",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", i="sequence_comma")
@@ -657,6 +677,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
             to be of the format [*annotcontlabel*][/*contlabel*]. If either
             label contains a slash (/) character then use ``|`` as the
             separator for the two labels instead.
+        {XY}
         {t}
 
         """
@@ -688,6 +709,8 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         Td="rose",
         Tm="compass",
         U="timestamp",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -722,6 +745,7 @@ def basemap(self, **kwargs):
             Draws a map magnetic rose on the map at the location defined by the
             reference and anchor points
         {U}
+        {XY}
         {t}
 
         """
@@ -738,6 +762,8 @@ def basemap(self, **kwargs):
         U="timestamp",
         D="position",
         F="box",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -765,6 +791,7 @@ def logo(self, **kwargs):
             Without further options, draws a rectangular border around the
             GMT logo.
         {U}
+        {XY}
         {t}
 
         """
@@ -781,6 +808,8 @@ def logo(self, **kwargs):
         D="position",
         F="box",
         M="monochrome",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -816,6 +845,7 @@ def image(self, imagefile, **kwargs):
         monochrome : bool
             Convert color image to monochrome grayshades using the (television)
             YIQ-transformation.
+        {XY}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -829,6 +859,8 @@ def image(self, imagefile, **kwargs):
         J="projection",
         D="position",
         F="box",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -865,6 +897,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
             rectangular border around the legend using **MAP_FRAME_PEN**. By
             default, uses '+gwhite+p1p' which draws a box around the legend
             using a 1 point black pen and adds a white background.
+        {XY}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -894,6 +927,8 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         D="offset",
         G="fill",
         W="pen",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(
@@ -1000,6 +1035,7 @@ def text(
             Sets the pen used to draw a rectangle around the text string
             (see *clearance*) [Default is width = default, color = black,
             style = solid].
+        {XY}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -1055,6 +1091,8 @@ def text(
         J="projection",
         B="frame",
         C="offset",
+        X="xshift",
+        Y="yshift",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence")
@@ -1152,6 +1190,7 @@ def meca(
         {J}
         {R}
         {B}
+        {XY}
         {t}
         """
 

pygmt/helpers/decorators.py

@@ -53,6 +53,15 @@
     "W": """\
         pen : str
             Set pen attributes for lines or the outline of symbols.""",
+    "XY": """\
+        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`.
+         """,
     "j": """\
         distcalc : str
             ``e|f|g``.