DOC: Update Figure.inset in tutorials/gallery examples to the Pythonic syntax

examples/gallery/embellishments/inset.py

@@ -2,33 +2,32 @@
 Inset
 =====
 
-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 ``clearance`` parameters are set. Plotting methods
-called within the ``with`` statement are applied to the inset figure.
+The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger figure. The
+method is called using a ``with`` statement. Plotting methods called within the ``with``
+statement are applied to the inset figure.
 """
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 fig = pygmt.Figure()
-# Create the primary figure, setting the region to Madagascar, the land color
-# to "brown", the water to "lightblue", the shorelines width to "thin", and
-# adding a frame
+# Create the primary figure, setting the region to Madagascar, the land color to
+# "brown", the water to "lightblue", the shorelines width to "thin", and 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 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", clearance=0, box=Box(pen="1.5p,gold")):
+# pen thickness of 1.5 points.
+with fig.inset(
+    position=Position("TL", offset=0.2),
+    width=3.5,
+    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".
+    # orthogonal projection centered at 47E, 20S. The land color is set to "gray" and
+    # Madagascar is highlighted in "red3".
     fig.coast(
-        region="g",
-        projection="G47/-20/?",
-        land="gray",
-        water="white",
-        dcw="MG+gred3",
+        region="g", projection="G47/-20/?", land="gray", water="white", dcw="MG+gred3"
     )
 fig.show()

examples/gallery/embellishments/inset_rectangle_region.py

@@ -2,54 +2,44 @@
 Inset map showing a rectangular region
 ======================================
 
-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 ``clearance`` can be customized. Plotting methods
-called within the ``with`` statement plot into the inset figure.
+The :meth:`pygmt.Figure.inset` method adds an inset figure inside a larger figure. The
+method is called using a ``with`` statement. Plotting methods called within the ``with``
+statement plot into the inset figure.
 """
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 # Set the region of the main figure
 region = [137.5, 141, 34, 37]
 
 fig = pygmt.Figure()
-
-# Plot the base map of the main figure. Universal Transverse Mercator (UTM)
-# projection is used and the UTM zone is set to be "54S".
+# Plot the base map of the main figure. Universal Transverse Mercator (UTM) projection
+# is used and the UTM zone is set to be "54S".
 fig.basemap(region=region, projection="U54S/12c", frame=["WSne", "af"])
 
-# Set the land color to "lightbrown", the water color to "azure1", the
-# shoreline width to "2p", and the area threshold to 1000 km^2 for the main
-# figure
+# Set the land color to "lightbrown", the water color to "azure1", the shoreline width
+# to "2p", and the area threshold to 1000 km^2 for the main figure.
 fig.coast(land="lightbrown", water="azure1", shorelines="2p", area_thresh=1000)
 
-# Create an inset map, placing it in the Bottom Right (BR) corner with x- and
-# y-offsets of 0.1 cm, respectively.
-# The inset map contains the Japan main land. "U54S/3c" means UTM projection
-# with a map width of 3 cm. The inset width and height are automatically
-# calculated from the specified ``region`` and ``projection`` parameters.
-# Draws a rectangular box around the inset with a fill color of "white" and
-# a pen of "1p".
+# Create an inset map, placing it in the Bottom Right (BR) corner with x- and y-offsets
+# of 0.1 cm, respectively. The inset map contains the Japan main land. "U54S/3c" means
+# UTM projection with a map width of 3 cm. The inset width and height are automatically
+# calculated from the specified ``region`` and ``projection`` parameters. Draws a
+# rectangular box around the inset with a fill color of "white" and a pen of "1p".
 with fig.inset(
-    position="jBR+o0.1c",
+    position=Position("BR", offset=0.1),
     box=Box(fill="white", pen="1p"),
     region=[129, 146, 30, 46],
     projection="U54S/3c",
 ):
-    # Highlight the Japan area in "lightbrown"
-    # and draw its outline with a pen of "0.2p".
-    fig.coast(
-        dcw="JP+glightbrown+p0.2p",
-        area_thresh=10000,
-    )
-    # Plot a rectangle ("r") in the inset map to show the area of the main
-    # figure. "+s" means that the first two columns are the longitude and
-    # latitude of the bottom left corner of the rectangle, and the last two
-    # columns the longitude and latitude of the upper right corner.
+    # Highlight the Japan area in "lightbrown" and draw its outline with a pen of "0.2p"
+    fig.coast(dcw="JP+glightbrown+p0.2p", area_thresh=10000)
+    # Plot a rectangle ("r") in the inset map to show the area of the main figure.
+    # "+s" means that the first two columns are the longitude and latitude of the bottom
+    # left corner of the rectangle, and the last two columns the longitude and latitude
+    # of the upper right corner.
     rectangle = [[region[0], region[2], region[1], region[3]]]
     fig.plot(data=rectangle, style="r+s", pen="2p,blue")
-
 fig.show()

examples/tutorials/advanced/insets.py

@@ -3,19 +3,19 @@
 =============================
 
 To plot an inset figure inside another larger figure, we can use the
-:meth:`pygmt.Figure.inset` method. After a large figure has been created,
-call ``inset`` using a ``with`` statement, and new plot elements will be
-added to the inset figure instead of the larger figure.
+:meth:`pygmt.Figure.inset` method. After a large figure has been created, call ``inset``
+using a ``with`` statement, and new plot elements will be added to the inset figure
+instead of the larger figure.
 """
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 # %%
-# Prior to creating an inset figure, a larger figure must first be plotted. In
-# the example below, :meth:`pygmt.Figure.coast` is used to create a map of the
-# US state of Massachusetts.
+# Prior to creating an inset figure, a larger figure must first be plotted. In the
+# example below, :meth:`pygmt.Figure.coast` is used to create a map of the US state of
+# Massachusetts.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -30,15 +30,11 @@
 fig.show()
 
 # %%
-# The :meth:`pygmt.Figure.inset` method uses a context manager, and is called
-# using a ``with`` statement. The ``position`` parameter, including the inset
-# width, is required to plot the inset. Using the **j** modifier, the location
-# of the inset is set to one of the 9 anchors (Top - Middle - Bottom and Left -
-# Center - Right). In the example below, ``BL`` places the inset at the Bottom
-# Left corner. The ``box`` parameter can set the fill and border of the inset.
-# In the example below, ``+pblack`` sets the border color to black and
-# ``+glightred`` sets the fill to light red.
-
+# The :meth:`pygmt.Figure.inset` method uses a context manager, and is called using a
+# ``with`` statement. The ``position`` parameter, including the inset width, is required
+# to plot the inset. In the example below, the inset is placed at the Bottom Left
+# (``BL``) inside the plot. The ``box`` parameter can set the fill and border of the
+# inset.
 fig = pygmt.Figure()
 fig.coast(
     region=[-74, -69.5, 41, 43],
@@ -49,19 +45,17 @@
     water="lightblue",
     frame="a",
 )
-with fig.inset(position="jBL+w3c", box=Box(pen="black", fill="lightred")):
-    # pass is used to exit the with statement as no plotting methods are
-    # called
+with fig.inset(position=Position("BL"), width=3, box=Box(pen="black", fill="lightred")):
+    # pass is used to exit the with statement as no plotting methods are called
     pass
 fig.show()
 
 # %%
-# When using **j** to set the anchor of the inset, the default location is in
-# contact with the nearby axis or axes. The offset of the inset can be set with
-# **+o**, followed by the offsets along the x- and y-axes. If only one offset
-# is passed, it is applied to both axes. Each offset can have its own unit. In
-# the example below, the inset is shifted 0.5 centimeters on the x-axis and
-# 0.2 centimeters on the y-axis.
+# When placed at the Bottom Left corner inside the plot, the default location is in
+# contact with the nearby axis or axes. The offsets along the x- and y-axes can be set
+# with the ``offset`` parameter of the ``Position`` class. If only one offset is passed,
+# it is applied to both axes. Each offset can have its own unit. In the example below,
+# the inset is shifted 0.5 centimeters on the x-axis and 0.2 centimeters on the y-axis.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -73,15 +67,19 @@
     water="lightblue",
     frame="a",
 )
-with fig.inset(position="jBL+w3c+o0.5c/0.2c", box=Box(pen="black", fill="lightred")):
+with fig.inset(
+    position=Position("BL", offset=(0.5, 0.2)),
+    width=3,
+    box=Box(pen="black", fill="lightred"),
+):
     pass
 fig.show()
 
 # %%
-# Standard plotting methods can be called from within the ``inset`` context
-# manager. The example below uses :meth:`pygmt.Figure.coast` to plot a zoomed
-# out map that selectively paints the state of Massachusetts to show its
-# location relative to other states.
+# Standard plotting methods can be called from within the ``inset`` context manager. The
+# example below uses :meth:`pygmt.Figure.coast` to plot a zoomed out map that
+# selectively paints the state of Massachusetts to show its location relative to other
+# states.
 
 fig = pygmt.Figure()
 fig.coast(
@@ -93,11 +91,10 @@
     water="lightblue",
     frame="a",
 )
-# This does not include an inset fill as it is covered by the inset figure
-# Inset width/height are determined by the ``region`` and ``projection``
-# parameters.
+# This does not include an inset fill as it is covered by the inset figure. Inset
+# width/height are determined by the ``region`` and ``projection`` parameters.
 with fig.inset(
-    position="jBL+o0.5c/0.2c",
+    position=Position("BL", offset=(0.5, 0.2)),
     box=Box(pen="black"),
     region=[-80, -65, 35, 50],
     projection="M3c",
@@ -108,8 +105,7 @@
         borders=[1, 2],
         shorelines="1/thin",
         water="white",
-        # Use dcw to selectively highlight an area
-        dcw="US.MA+gred",
+        dcw="US.MA+gred",  # Use dcw to selectively highlight an area
     )
 fig.show()