Figure.inset: Deprecate parameter margin to clearance (Will be removed in v0.20.0) (#4296)

Author: yvonnefroehlich

examples/gallery/embellishments/inset.py

@@ -3,9 +3,9 @@
 =====
 
 The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger
-figure. The method is called using a ``with`` statement, and its
-``position``, ``box``, ``offset``, and ``margin`` parameters are set. Plotting
-methods called within the ``with`` statement are applied to the inset figure.
+figure. The method is called using a ``with`` statement, and its ``position``,
+``box``, ``offset``, and ``clearance`` parameters are set. Plotting methods
+called within the ``with`` statement are applied to the inset figure.
 """
 
 # %%
@@ -18,9 +18,9 @@
 # adding a frame
 fig.coast(region="MG+r2", land="brown", water="lightblue", shorelines="thin", frame="a")
 # Create an inset, placing it in the Top Left (TL) corner with a width of 3.5 cm and
-# x- and y-offsets of 0.2 cm. The margin is set to 0, and the border is "gold" with a
+# x- and y-offsets of 0.2 cm. The clearance is set to 0, and the border is "gold" with a
 # pen size of 1.5 points.
-with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box=Box(pen="1.5p,gold")):
+with fig.inset(position="jTL+w3.5c+o0.2c", clearance=0, box=Box(pen="1.5p,gold")):
     # Create a figure in the inset using coast. This example uses the azimuthal
     # orthogonal projection centered at 47E, 20S. The land color is set to
     # "gray" and Madagascar is highlighted in "red3".

examples/gallery/embellishments/inset_rectangle_region.py

@@ -3,9 +3,9 @@
 ======================================
 
 The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger
-figure. The method is called using a ``with`` statement, and its
-``position``, ``box``, ``offset``, and ``margin`` can be customized. Plotting
-methods called within the ``with`` statement plot into the inset figure.
+figure. The method is called using a ``with`` statement, and its ``position``,
+``box``, ``offset``, and ``clearance`` can be customized. Plotting methods
+called within the ``with`` statement plot into the inset figure.
 """
 
 # %%

pygmt/src/inset.py

@@ -8,15 +8,22 @@
 
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 from pygmt.params import Box
 
 __doctest_skip__ = ["inset"]
 
 
 @fmt_docstring
+@deprecate_parameter("margin", "clearance", "v0.18.0", remove_version="v0.20.0")
 @contextlib.contextmanager
-@use_alias(D="position", M="margin")
+@use_alias(D="position", C="clearance")
 @kwargs_to_strings(D="sequence", M="sequence")
 def inset(
     self,
@@ -90,7 +97,7 @@ def inset(
         box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance,
         pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other
         box properties.
-    margin : float, str, or list
+    clearance : float, str, or list
         This is clearance that is added around the inside of the inset.
         Plotting will take place within the inner region only. The margins
         can be a single value, a pair of values separated (for setting
@@ -116,7 +123,7 @@ def inset(
     >>> fig.coast(region="MG+r2", water="lightblue", shorelines="thin")
     >>> # Use a "with" statement to initialize the inset context manager
     >>> # Setting the position to Top Left and a width of 3.5 centimeters
-    >>> with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box=Box(pen="green")):
+    >>> with fig.inset(position="jTL+w3.5c+o0.2c", clearance=0, box=Box(pen="green")):
     ...     # Map elements under the "with" statement are plotted in the inset
     ...     fig.coast(
     ...         region="g",

pygmt/tests/test_inset.py

@@ -15,7 +15,7 @@ def test_inset_aliases():
     """
     fig = Figure()
     fig.basemap(region="MG+r2", frame="afg")
-    with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box=Box(pen="green")):
+    with fig.inset(position="jTL+w3.5c+o0.2c", clearance=0, box=Box(pen="green")):
         fig.basemap(region="g", projection="G47/-20/4c", frame="afg")
     return fig
 
@@ -28,7 +28,7 @@ def test_inset_context_manager():
     """
     fig = Figure()
     fig.basemap(region=[-74, -69.5, 41, 43], projection="M9c", frame=True)
-    with fig.inset(position="jBL+w3c+o0.2c", margin=0, box=Box(pen="black")):
+    with fig.inset(position="jBL+w3c+o0.2c", clearance=0, box=Box(pen="black")):
         fig.basemap(region=[-80, -65, 35, 50], projection="M3c", frame="afg")
     fig.basemap(rose="jTR+w3c")  # Pass rose argument with basemap after the inset
     return fig