Add a new method to shift plot origins

doc/api/index.rst

@@ -30,6 +30,7 @@ Plotting data and laying out the map:
     Figure.grdimage
     Figure.logo
     Figure.image
+    Figure.shift_origin
 
 Saving and displaying the figure:
 

examples/tutorials/coastlines.py

@@ -60,7 +60,8 @@
 oahu = [-158.3, -157.6, 21.2, 21.8]
 fig = pygmt.Figure()
 for res in ["c", "l", "i", "h", "f"]:
-    fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5i", X="5i")
+    fig.coast(resolution=res, shorelines="1p", region=oahu, projection="M5i")
+    fig.shift_origin(xshift="5i")
 fig.show()
 
 ########################################################################################

pygmt/figure.py

@@ -284,6 +284,38 @@ def show(self, dpi=300, width=500, method="static"):
             img = Image(data=png, width=width)
         return img
 
+    def shift_origin(self, xshift=None, yshift=None):
+        """
+        Shift plot origin in x and/or y directions.
+
+        This method shifts plot origin relative to the current origin by (*xshift*,*yshift*)
+        and optionally append the length unit (**c**, **i**, or **p**).
+
+        Prepend **a** to shift the origin back to the original position
+        after plotting, prepend **c** to center the plot on the center of the
+        paper (optionally add shift), prepend **f** to shift the origin relative
+        to the fixed lower left corner of the page, or prepend **r** [Default] to
+        move the origin relative to its current location.
+
+        Detailed usage at http://gmt.soest.hawaii.edu/doc/latest/GMT_Docs.html#plot-positioning-and-layout-the-x-y-options
+
+        Parameters
+        ----------
+        xshift : str
+            Shift plot origin in x direction.
+        yshift : str
+            Shift plot origin in y direction.
+        """
+        self._preprocess()
+        args = ["-T"]
+        if xshift:
+            args.append("-X{}".format(xshift))
+        if yshift:
+            args.append("-Y{}".format(yshift))
+
+        with Session() as lib:
+            lib.call_module("plot", " ".join(args))
+
     def _preview(self, fmt, dpi, as_bytes=False, **kwargs):
         """
         Grab a preview of the figure.

pygmt/tests/test_figure.py

@@ -115,3 +115,17 @@ def test_figure_show():
     fig.basemap(R="10/70/-300/800", J="X3i/5i", B="af")
     img = fig.show(width=800)
     assert img.width == 800
+
+
+@pytest.mark.mpl_image_compare
+def test_shift_origin():
+    "Test if fig.shift_origin works"
+    fig = Figure()
+    fig.basemap(R="10/70/-300/300", J="X3i/5i", B="af")
+    fig.shift_origin(xshift="4i")
+    fig.basemap(R="10/70/-300/300", J="X3i/5i", B="af")
+    fig.shift_origin(yshift="6i")
+    fig.basemap(R="10/70/-300/300", J="X3i/5i", B="af")
+    fig.shift_origin(xshift="-4i", yshift="6i")
+    fig.basemap(R="10/70/-300/300", J="X3i/5i", B="af")
+    return fig