From 9087c6e4eb791b0434c1e25ed89b1937637230b3 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 20 Dec 2025 20:42:25 +0800
Subject: [PATCH 01/16] Figure.subplot: Pythonic implemention for the subplot
 tagging

---
 pygmt/src/subplot.py        | 148 +++++++++++++++++++++++++++++-------
 pygmt/tests/test_subplot.py |  54 ++++++++++++-
 2 files changed, 174 insertions(+), 28 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 0ef2ed37e34..dba64030baf 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -6,10 +6,55 @@
 from collections.abc import Sequence
 from typing import Literal
 
+from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.params import Box, Position
+from pygmt.src._common import _parse_position
+
+
+def _alias_option_A(  # noqa: N802
+    autotag: str | bool = False,
+    tag_position: AnchorCode | Position | None = None,
+    tag_box: Box | None = None,
+    tag_number_style: Literal["arabic", "roman", "Roman"] | None = None,
+    tag_orientation: Literal["horizontal", "vertical"] | None = None,
+    autolabel: str | bool = False,
+):
+    """Helper function to create Alias for option A in subplot."""
+    # Check conflicts with deprecated 'autolabel' parameter.
+    if autolabel:
+        if any(
+            v is not None and v is not False
+            for v in [autotag, tag_position, tag_box, tag_number_style, tag_orientation]
+        ):
+            msg = (
+                "The 'autolabel' parameter is deprecated since v0.18.0. "
+                "Please use the parameters 'autotag', 'tag_position', 'tag_box', "
+                "'tag_number_style', 'tag_orientation', and 'tag_font' instead."
+            )
+            raise GMTInvalidInput(msg)
+        return Alias(autolabel, name="autolabel")
+
+    return [
+        Alias(autotag, name="autotag"),
+        Alias(
+            _parse_position(tag_position), name="tag_position", prefix="+"
+        ),  # Prefix is "+".
+        Alias(tag_box, name="tag_box"),
+        Alias(
+            tag_number_style,
+            name="tag_number_style",
+            mapping={"arabic": "", "roman": "+r", "Roman": "+R"},
+        ),
+        Alias(
+            tag_orientation,
+            name="tag_orientation",
+            mapping={"horizontal": "", "vertical": "+v"},
+        ),
+    ]
 
 
 @fmt_docstring
@@ -17,16 +62,22 @@
 @use_alias(
     Ff="figsize",
     Fs="subsize",
-    A="autolabel",
     C="clearance",
     SC="sharex",
     SR="sharey",
 )
 @kwargs_to_strings(Ff="sequence", Fs="sequence")
-def subplot(
+def subplot(  # noqa: PLR0913
     self,
     nrows: int = 1,
     ncols: int = 1,
+    autotag: str | bool = False,
+    tag_position: AnchorCode | Position | None = None,
+    tag_box: Box | None = None,
+    tag_orientation: Literal["horizontal", "vertical"] | None = None,
+    tag_number_style: Literal["arabic", "roman", "Roman"] | None = None,
+    tag_font: str | None = None,
+    autolabel: str | bool = False,
     margins: float | str | Sequence[float | str] | None = None,
     title: str | None = None,
     projection: str | None = None,
@@ -67,31 +118,59 @@ def subplot(
         Specify the dimensions of each subplot directly as [*width*, *height*].
         Note that only one of ``figsize`` or ``subsize`` can be provided at
         once.
+    autolabel
+        Specify automatic tagging of each subplot.
+
+        .. deprecated:: v0.18.0
+
+           Use the parameters ``autotag``, ``tag_position``, ``tag_box``,
+           ``tag_number_style``, ``tag_orientation``, and ``tag_font`` instead.
+    autotag
+        Specify automatic tagging of each subplot. It can accept a number, or a letter.
+        The number or letter can be surrounded by parentheses on any side if these
+        should be typeset as part of the tag. This sets the tag of the first, top-left
+        subplot and others follow sequentially. If set to ``True``, default to ``"a)"``.
+
+        Examples are:
 
-    autolabel : bool or str
-        [*autolabel*][**+c**\ *dx*\ [/*dy*]][**+g**\ *fill*][**+j**\|\ **J**\
-        *refpoint*][**+o**\ *dx*\ [/*dy*]][**+p**\ *pen*][**+r**\|\ **R**]\ [**+v**].
-        Specify automatic tagging of each subplot. Append either a number or letter
-        [Default is ``"a"``]. This sets the tag of the first, top-left subplot and
-        others follow sequentially. Surround the number or letter by parentheses on
-        any side if these should be typeset as part of the tag [Default is ``")"``].
-        Use **+j**\|\ **J** for setting *refpoint* via a
-        :doc:`2-character justification code </techref/justification_codes>`
-        to specify where the tag should be placed in the subplot [Default is ``"TL"``
-        for the Top Left corner]. **Note**: **+j** sets the justification of the tag
-        to *refpoint* (suitable for interior tags) while **+J** instead selects the
-        mirror opposite (suitable for exterior tags). Append **+c**\ *dx*\[/*dy*] to
-        set the clearance between the tag and a surrounding text box requested via
-        **+g** or **+p** [Default is ``"3p/3p"``, i.e., 15 % of the
-        :gmt-term:`FONT_TAG` size dimension]. Append **+g**\ *fill* to paint the tag's
-        text box with *fill* [Default is no fill]. Append **+o**\ *dx*\ [/*dy*] to
-        offset the tag's reference point in the direction implied by the justification
-        [Default is ``"4p/4p"``, i.e., 20 % of the :gmt-term:`FONT_TAG` size]. Append
-        **+p**\ *pen* to draw the outline of the tag's text box using the selected *pen*
-        [Default is no outline]. Append **+r** to typeset your tag numbers using
-        lowercase Roman numerals; use **+R** for uppercase Roman numerals [Default is
-        Arabic numerals]. Append **+v** to increase tag numbers vertically down columns
-        [Default is horizontally across rows].
+        - ``autotag="a"``: tags are ``a``, ``b``, ``c``, ...
+        - ``autotag="1"``: tags are ``1``, ``2``, ``3``, ...
+        - ``autotag="a)"``: tags are ``a)``, ``b)``, ``c)``, ...
+        - ``autotag="(c)"``: tags are ``(c)``, ``(d)``, ``(e)``, ...
+        - ``autotag=True``: same as ``autotag="a)"``.
+    tag_position
+        Position of the subplot tag on the plot. It can be specified in two ways:
+
+        - A :doc:`2-character justification code </techref/justification_codes>` for a
+          position inside the plot, e.g., ``"TL"`` for Top Left corner inside the plot.
+        - A :class:`pygmt.params.Position` object to fully control the position and
+          offset. **Note**: the ``refpoint`` propterty of the Position object must be
+          an two-character justification code, and ``cstype`` must be set to either
+          ``"inside"`` or ``"outside"``,
+
+        If not specified, defaults to Top Left corner inside the plot with the offset
+        default to ``("4p", "4p")``, i.e., 20% of the :gmt-term:`FONT_TAG` size.
+    tag_box
+        Draw a box around the subplot tag. See :class:`pygmt.params.Box` for details on
+        how to specify the box.
+
+        **Notes on the use of the ``Box`` class:**
+
+        - The property ``clearance`` only accept one or two values.
+        - The property ``inner_pen``/``inner_gap``/``radius`` is not supported.
+    tag_number_style
+        Style of the subplot tag numbers. It can be:
+
+        - ``"arabic"``: Arabic numerals: 1, 2, 3, ... [Default].
+        - ``"roman"``: Lowercase Roman numerals: i, ii, iii, ...
+        - ``"Roman"``: Uppercase Roman numerals: I, II, III, ...
+    tag_orientation
+        Orientation of the subplot tag. It can be:
+
+        - ``"horizontal"``: Increase tag numbers horizontally across rows [Default].
+        - ``"vertical"``: Increase tag numbers vertically down columns.
+    tag_font
+        Font for the subplot tag [Default to ``"20p,Helvetica,black"``].
     clearance : str or list
         [*side*]\ *clearance*.
         Reserve a space of dimension *clearance* between the margin and the
@@ -170,6 +249,14 @@ def subplot(
         raise GMTInvalidInput(msg)
 
     aliasdict = AliasSystem(
+        A=_alias_option_A(
+            autotag=autotag,
+            tag_position=tag_position,
+            tag_box=tag_box,
+            tag_number_style=tag_number_style,
+            tag_orientation=tag_orientation,
+            autolabel=autolabel,
+        ),
         M=Alias(margins, name="margins", sep="/", size=(2, 4)),
         T=Alias(title, name="title"),
     ).add_common(
@@ -180,6 +267,9 @@ def subplot(
     )
     aliasdict.merge(kwargs)
 
+    # Configure FONT_TAG if tag_font is set
+    confdict = {"FONT_TAG": tag_font} if tag_font is not None else {}
+
     # Need to use separate sessions for "subplot begin" and "subplot end".
     # Otherwise, "subplot end" will use the last session, which may cause
     # strange positioning issues for later plotting calls.
@@ -188,7 +278,11 @@ def subplot(
         with Session() as lib:
             lib.call_module(
                 module="subplot",
-                args=["begin", f"{nrows}x{ncols}", *build_arg_list(aliasdict)],
+                args=[
+                    "begin",
+                    f"{nrows}x{ncols}",
+                    *build_arg_list(aliasdict, confdict=confdict),
+                ],
             )
             yield
     finally:
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index b6143c1ac21..a547e1e445d 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -4,8 +4,10 @@
 
 import pytest
 from pygmt import Figure
+from pygmt.alias import AliasSystem
 from pygmt.exceptions import GMTInvalidInput, GMTValueError
-from pygmt.params import Position
+from pygmt.params import Box, Position
+from pygmt.src.subplot import _alias_option_A
 
 
 @pytest.mark.benchmark
@@ -125,3 +127,53 @@ def test_subplot_outside_plotting_positioning():
         frame=True,
     )
     return fig
+
+
+def test_alias_option_A():  # noqa: N802
+    """
+    Test _alias_option_A with only autotag parameter.
+    """
+
+    def alias_wrapper(**kwargs):
+        """
+        A wrapper function for testing the parameters of -A option.
+        """
+        return AliasSystem(A=_alias_option_A(**kwargs)).get("A")
+
+    assert alias_wrapper(autotag=True) == ""
+    assert alias_wrapper(autotag="a)") == "a)"
+    assert alias_wrapper(autotag="(a)", tag_position="TL") == "(a)+jTL"
+    assert alias_wrapper(autotag="i)", tag_number_style="roman") == "i)+r"
+    assert alias_wrapper(autotag="i)", tag_number_style="Roman") == "i)+R"
+    assert alias_wrapper(autotag="a)", tag_orientation="vertical") == "a)+v"
+
+    tag = alias_wrapper(autotag="i)", tag_box=Box(pen="1p,red", clearance="2p"))
+    assert tag == "i)+c2p+p1p,red"
+
+    tag = alias_wrapper(
+        autotag="a)", tag_position=Position("BL", cstype="outside", offset=("3p", "3p"))
+    )
+    assert tag == "a)+JBL+o3p/3p"
+
+
+def test_deprecated_autolabel():
+    """
+    Test that using the deprecated autolabel parameter raises a warning when conflicted
+    with tag parameters.
+    """
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, autotag="a)"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_box=True):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_orientation="vertical"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_number_style="roman"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_position="TL"):
+            pass

From 6a0508590ac4cbba8b674d9ac00cda0cb5e224d6 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 20 Dec 2025 20:42:25 +0800
Subject: [PATCH 02/16] Figure.subplot: Pythonic implemention for the subplot
 tagging

---
 pygmt/src/subplot.py        | 174 ++++++++++++++++++++++++++++++------
 pygmt/tests/test_subplot.py |  23 +++++
 2 files changed, 170 insertions(+), 27 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 0ef2ed37e34..38777d0b7f0 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -6,10 +6,81 @@
 from collections.abc import Sequence
 from typing import Literal
 
+from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput, GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.params import Box, Position
+from pygmt.src._common import _parse_position
+
+
+def _alias_option_A(  # noqa: N802
+    autotag: str | bool = False,
+    tag_position: AnchorCode | Position | None = None,
+    tag_box: Box | None = None,
+    tag_number_style: Literal["arabic", "roman", "Roman"] | None = None,
+    tag_orientation: Literal["horizontal", "vertical"] | None = None,
+    autolabel: str | bool = False,
+):
+    """
+    Helper function to create Alias for option A in subplot.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return AliasSystem(A=_alias_option_A(**kwargs)).get("A")
+    >>> parse(autotag=True)
+    ''
+    >>> parse(autotag="a)")
+    'a)'
+    >>> parse(autotag="(a)", tag_position="TL")
+    '(a)+jTL'
+    >>> parse(autotag="i)", tag_number_style="roman")
+    'i)+r'
+    >>> parse(autotag="i)", tag_number_style="Roman")
+    'i)+R'
+    >>> parse(autotag="a)", tag_orientation="vertical")
+    'a)+v'
+    >>> parse(autotag="i)", tag_box=Box(pen="1p,red", clearance="2p"))
+    'i)+c2p+p1p,red'
+    >>> parse(
+    ...     autotag="a)",
+    ...     tag_position=Position("BL", cstype="outside", offset=("3p", "3p")),
+    ... )
+    'a)+JBL+o3p/3p'
+    """
+    # Check conflicts with deprecated 'autolabel' parameter.
+    if autolabel:
+        if any(
+            v is not None and v is not False
+            for v in [autotag, tag_position, tag_box, tag_number_style, tag_orientation]
+        ):
+            msg = (
+                "The 'autolabel' parameter is deprecated since v0.18.0. "
+                "Please use the parameters 'autotag', 'tag_position', 'tag_box', "
+                "'tag_number_style', 'tag_orientation', and 'tag_font' instead."
+            )
+            raise GMTInvalidInput(msg)
+        return Alias(autolabel, name="autolabel")
+
+    return [
+        Alias(autotag, name="autotag"),
+        Alias(
+            _parse_position(tag_position), name="tag_position", prefix="+"
+        ),  # Prefix is "+".
+        Alias(tag_box, name="tag_box"),
+        Alias(
+            tag_number_style,
+            name="tag_number_style",
+            mapping={"arabic": "", "roman": "+r", "Roman": "+R"},
+        ),
+        Alias(
+            tag_orientation,
+            name="tag_orientation",
+            mapping={"horizontal": "", "vertical": "+v"},
+        ),
+    ]
 
 
 @fmt_docstring
@@ -17,16 +88,22 @@
 @use_alias(
     Ff="figsize",
     Fs="subsize",
-    A="autolabel",
     C="clearance",
     SC="sharex",
     SR="sharey",
 )
 @kwargs_to_strings(Ff="sequence", Fs="sequence")
-def subplot(
+def subplot(  # noqa: PLR0913
     self,
     nrows: int = 1,
     ncols: int = 1,
+    autotag: str | bool = False,
+    tag_position: AnchorCode | Position | None = None,
+    tag_box: Box | None = None,
+    tag_orientation: Literal["horizontal", "vertical"] | None = None,
+    tag_number_style: Literal["arabic", "roman", "Roman"] | None = None,
+    tag_font: str | None = None,
+    autolabel: str | bool = False,
     margins: float | str | Sequence[float | str] | None = None,
     title: str | None = None,
     projection: str | None = None,
@@ -67,31 +144,59 @@ def subplot(
         Specify the dimensions of each subplot directly as [*width*, *height*].
         Note that only one of ``figsize`` or ``subsize`` can be provided at
         once.
+    autolabel
+        Specify automatic tagging of each subplot.
+
+        .. deprecated:: v0.18.0
 
-    autolabel : bool or str
-        [*autolabel*][**+c**\ *dx*\ [/*dy*]][**+g**\ *fill*][**+j**\|\ **J**\
-        *refpoint*][**+o**\ *dx*\ [/*dy*]][**+p**\ *pen*][**+r**\|\ **R**]\ [**+v**].
-        Specify automatic tagging of each subplot. Append either a number or letter
-        [Default is ``"a"``]. This sets the tag of the first, top-left subplot and
-        others follow sequentially. Surround the number or letter by parentheses on
-        any side if these should be typeset as part of the tag [Default is ``")"``].
-        Use **+j**\|\ **J** for setting *refpoint* via a
-        :doc:`2-character justification code </techref/justification_codes>`
-        to specify where the tag should be placed in the subplot [Default is ``"TL"``
-        for the Top Left corner]. **Note**: **+j** sets the justification of the tag
-        to *refpoint* (suitable for interior tags) while **+J** instead selects the
-        mirror opposite (suitable for exterior tags). Append **+c**\ *dx*\[/*dy*] to
-        set the clearance between the tag and a surrounding text box requested via
-        **+g** or **+p** [Default is ``"3p/3p"``, i.e., 15 % of the
-        :gmt-term:`FONT_TAG` size dimension]. Append **+g**\ *fill* to paint the tag's
-        text box with *fill* [Default is no fill]. Append **+o**\ *dx*\ [/*dy*] to
-        offset the tag's reference point in the direction implied by the justification
-        [Default is ``"4p/4p"``, i.e., 20 % of the :gmt-term:`FONT_TAG` size]. Append
-        **+p**\ *pen* to draw the outline of the tag's text box using the selected *pen*
-        [Default is no outline]. Append **+r** to typeset your tag numbers using
-        lowercase Roman numerals; use **+R** for uppercase Roman numerals [Default is
-        Arabic numerals]. Append **+v** to increase tag numbers vertically down columns
-        [Default is horizontally across rows].
+           Use the parameters ``autotag``, ``tag_position``, ``tag_box``,
+           ``tag_number_style``, ``tag_orientation``, and ``tag_font`` instead.
+    autotag
+        Specify automatic tagging of each subplot. It can accept a number, or a letter.
+        The number or letter can be surrounded by parentheses on any side if these
+        should be typeset as part of the tag. This sets the tag of the first, top-left
+        subplot and others follow sequentially. If set to ``True``, default to ``"a)"``.
+
+        Examples are:
+
+        - ``autotag="a"``: tags are ``a``, ``b``, ``c``, ...
+        - ``autotag="1"``: tags are ``1``, ``2``, ``3``, ...
+        - ``autotag="a)"``: tags are ``a)``, ``b)``, ``c)``, ...
+        - ``autotag="(c)"``: tags are ``(c)``, ``(d)``, ``(e)``, ...
+        - ``autotag=True``: same as ``autotag="a)"``.
+    tag_position
+        Position of the subplot tag on the plot. It can be specified in two ways:
+
+        - A :doc:`2-character justification code </techref/justification_codes>` for a
+          position inside the plot, e.g., ``"TL"`` for Top Left corner inside the plot.
+        - A :class:`pygmt.params.Position` object to fully control the position and
+          offset. **Note**: the ``refpoint`` propterty of the Position object must be
+          an two-character justification code, and ``cstype`` must be set to either
+          ``"inside"`` or ``"outside"``,
+
+        If not specified, defaults to Top Left corner inside the plot with the offset
+        default to ``("4p", "4p")``, i.e., 20% of the :gmt-term:`FONT_TAG` size.
+    tag_box
+        Draw a box around the subplot tag. See :class:`pygmt.params.Box` for details on
+        how to specify the box.
+
+        **Notes on the use of the ``Box`` class:**
+
+        - The property ``clearance`` only accept one or two values.
+        - The property ``inner_pen``/``inner_gap``/``radius`` is not supported.
+    tag_number_style
+        Style of the subplot tag numbers. It can be:
+
+        - ``"arabic"``: Arabic numerals: 1, 2, 3, ... [Default].
+        - ``"roman"``: Lowercase Roman numerals: i, ii, iii, ...
+        - ``"Roman"``: Uppercase Roman numerals: I, II, III, ...
+    tag_orientation
+        Orientation of the subplot tag. It can be:
+
+        - ``"horizontal"``: Increase tag numbers horizontally across rows [Default].
+        - ``"vertical"``: Increase tag numbers vertically down columns.
+    tag_font
+        Font for the subplot tag [Default to ``"20p,Helvetica,black"``].
     clearance : str or list
         [*side*]\ *clearance*.
         Reserve a space of dimension *clearance* between the margin and the
@@ -170,6 +275,14 @@ def subplot(
         raise GMTInvalidInput(msg)
 
     aliasdict = AliasSystem(
+        A=_alias_option_A(
+            autotag=autotag,
+            tag_position=tag_position,
+            tag_box=tag_box,
+            tag_number_style=tag_number_style,
+            tag_orientation=tag_orientation,
+            autolabel=autolabel,
+        ),
         M=Alias(margins, name="margins", sep="/", size=(2, 4)),
         T=Alias(title, name="title"),
     ).add_common(
@@ -180,6 +293,9 @@ def subplot(
     )
     aliasdict.merge(kwargs)
 
+    # Configure FONT_TAG if tag_font is set
+    confdict = {"FONT_TAG": tag_font} if tag_font is not None else {}
+
     # Need to use separate sessions for "subplot begin" and "subplot end".
     # Otherwise, "subplot end" will use the last session, which may cause
     # strange positioning issues for later plotting calls.
@@ -188,7 +304,11 @@ def subplot(
         with Session() as lib:
             lib.call_module(
                 module="subplot",
-                args=["begin", f"{nrows}x{ncols}", *build_arg_list(aliasdict)],
+                args=[
+                    "begin",
+                    f"{nrows}x{ncols}",
+                    *build_arg_list(aliasdict, confdict=confdict),
+                ],
             )
             yield
     finally:
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index b6143c1ac21..a477623a85f 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -125,3 +125,26 @@ def test_subplot_outside_plotting_positioning():
         frame=True,
     )
     return fig
+
+
+def test_deprecated_autolabel():
+    """
+    Test that using the deprecated autolabel parameter raises a warning when conflicted
+    with tag parameters.
+    """
+    fig = Figure()
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, autotag="a)"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_box=True):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_orientation="vertical"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_number_style="roman"):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_position="TL"):
+            pass

From b316a22415feb3b6605c946be317361adaa75ca8 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 30 Jan 2026 17:53:36 +0800
Subject: [PATCH 03/16] Checking tag_position and tag_box

---
 pygmt/src/subplot.py | 47 +++++++++++++++++++++++++++++++-------------
 1 file changed, 33 insertions(+), 14 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index dba64030baf..b12112c9d36 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -38,6 +38,31 @@ def _alias_option_A(  # noqa: N802
             raise GMTInvalidInput(msg)
         return Alias(autolabel, name="autolabel")
 
+    # Validate tag_box if provided.
+    if tag_box:
+        if any(
+            v is not None
+            for v in {tag_box.inner_pen, tag_box.inner_gap, tag_box.radius}
+        ):
+            raise GMTValueError(
+                tag_box,
+                description="Box properties for 'tag_box' in 'Figure.subplot'.",
+                reason="The 'inner_pen', 'inner_gap', and 'radius' properties are not supported.",
+            )
+        if tag_box.clearance and len(tag_box.clearance) > 2:
+            raise GMTValueError(
+                tag_box,
+                description="Box 'clearance' property for 'tag_box' in 'Figure.subplot'.",
+                reason="Only one or two values are accepted.",
+            )
+    # Validate the tag_position if provided.
+    if tag_position and tag_position.cstype in {"mapcoords", "plotcoords", "boxcoords"}:
+        raise GMTValueError(
+            tag_position,
+            description="tag position for 'Figure.subplot'.",
+            reason="Only 'inside' or 'outside' cstype is allowed.",
+        )
+
     return [
         Alias(autotag, name="autotag"),
         Alias(
@@ -59,13 +84,7 @@ def _alias_option_A(  # noqa: N802
 
 @fmt_docstring
 @contextlib.contextmanager
-@use_alias(
-    Ff="figsize",
-    Fs="subsize",
-    C="clearance",
-    SC="sharex",
-    SR="sharey",
-)
+@use_alias(Ff="figsize", Fs="subsize", C="clearance", SC="sharex", SR="sharey")
 @kwargs_to_strings(Ff="sequence", Fs="sequence")
 def subplot(  # noqa: PLR0913
     self,
@@ -118,13 +137,6 @@ def subplot(  # noqa: PLR0913
         Specify the dimensions of each subplot directly as [*width*, *height*].
         Note that only one of ``figsize`` or ``subsize`` can be provided at
         once.
-    autolabel
-        Specify automatic tagging of each subplot.
-
-        .. deprecated:: v0.18.0
-
-           Use the parameters ``autotag``, ``tag_position``, ``tag_box``,
-           ``tag_number_style``, ``tag_orientation``, and ``tag_font`` instead.
     autotag
         Specify automatic tagging of each subplot. It can accept a number, or a letter.
         The number or letter can be surrounded by parentheses on any side if these
@@ -171,6 +183,13 @@ def subplot(  # noqa: PLR0913
         - ``"vertical"``: Increase tag numbers vertically down columns.
     tag_font
         Font for the subplot tag [Default to ``"20p,Helvetica,black"``].
+    autolabel
+        Specify automatic tagging of each subplot.
+
+        .. deprecated:: v0.19.0
+
+           Use the parameters ``autotag``, ``tag_position``, ``tag_box``,
+           ``tag_number_style``, ``tag_orientation``, and ``tag_font`` instead.
     clearance : str or list
         [*side*]\ *clearance*.
         Reserve a space of dimension *clearance* between the margin and the

From 58e804457de7d54e97eff4fd0435ef74368d7d2d Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 30 Jan 2026 18:10:07 +0800
Subject: [PATCH 04/16] Add doctests

---
 pygmt/src/subplot.py | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index b12112c9d36..b91d5d8b941 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -23,7 +23,36 @@ def _alias_option_A(  # noqa: N802
     tag_orientation: Literal["horizontal", "vertical"] | None = None,
     autolabel: str | bool = False,
 ):
-    """Helper function to create Alias for option A in subplot."""
+    """
+    Helper function to create the alias list for the -A option.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return AliasSystem(A=_alias_option_A(**kwargs)).get("A")
+    >>> parse(autotag="a)")
+    'a)'
+    >>> parse(tag_position="TL")
+    '+jTL'
+    >>> parse(tag_position=Position("TL", cstype="inside", offset=("2c", "2c")))
+    '+jTL+o2c/2c'
+    >>> parse(tag_position=Position("TL", cstype="outside", offset=("2c", "2c")))
+    '+JTL+o2c/2c'
+    >>> parse(tag_box=Box(pen="1p,red", clearance="2c"))
+    '+c2c+p1p,red'
+    >>> parse(tag_number_style="roman")
+    '+r'
+    >>> parse(tag_orientation="vertical")
+    '+v'
+    >>> parse(
+    ...     autotag="(1)",
+    ...     tag_position="TL",
+    ...     tag_box=Box(pen="1p,red"),
+    ...     tag_number_style="Roman",
+    ...     tag_orientation="horizontal",
+    ... )
+    '(1)+jTL+p1p,red+R'
+    """
     # Check conflicts with deprecated 'autolabel' parameter.
     if autolabel:
         if any(
@@ -41,22 +70,26 @@ def _alias_option_A(  # noqa: N802
     # Validate tag_box if provided.
     if tag_box:
         if any(
-            v is not None
+            v is not None and v is not False
             for v in {tag_box.inner_pen, tag_box.inner_gap, tag_box.radius}
         ):
             raise GMTValueError(
                 tag_box,
-                description="Box properties for 'tag_box' in 'Figure.subplot'.",
+                description="Box properties for 'tag_box' in 'Figure.subplot'",
                 reason="The 'inner_pen', 'inner_gap', and 'radius' properties are not supported.",
             )
         if tag_box.clearance and len(tag_box.clearance) > 2:
             raise GMTValueError(
                 tag_box,
-                description="Box 'clearance' property for 'tag_box' in 'Figure.subplot'.",
+                description="Box 'clearance' property for 'tag_box' in 'Figure.subplot'",
                 reason="Only one or two values are accepted.",
             )
     # Validate the tag_position if provided.
-    if tag_position and tag_position.cstype in {"mapcoords", "plotcoords", "boxcoords"}:
+    if getattr(tag_position, "cstype", None) in {
+        "mapcoords",
+        "plotcoords",
+        "boxcoords",
+    }:
         raise GMTValueError(
             tag_position,
             description="tag position for 'Figure.subplot'.",

From 7096da6ea1711746dd251490981ad187b814fb72 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 30 Jan 2026 18:37:35 +0800
Subject: [PATCH 05/16] Update tests and gallery examples

---
 .../embellishments/colorbars_multiple.py      | 33 +++++++++----------
 examples/tutorials/advanced/subplots.py       | 22 ++++++-------
 pygmt/tests/test_subplot.py                   |  6 ++--
 3 files changed, 29 insertions(+), 32 deletions(-)

diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py
index de3eb3f6d0a..d3c29512b1c 100644
--- a/examples/gallery/embellishments/colorbars_multiple.py
+++ b/examples/gallery/embellishments/colorbars_multiple.py
@@ -2,10 +2,9 @@
 Multiple colormaps
 ==================
 
-This gallery example shows how to create multiple colormaps for different
-subplots. To better understand how GMT modern mode maintains several levels of
-colormaps, please refer to
-:gmt-docs:`reference/features.html#gmt-modern-mode-hierarchical-levels` for
+This gallery example shows how to create multiple colormaps for different subplots. To
+better understand how GMT modern mode maintains several levels of colormaps, please
+refer to :gmt-docs:`reference/features.html#gmt-modern-mode-hierarchical-levels` for
 details.
 """
 
@@ -19,26 +18,24 @@
 subset_region = [-14, 30, 35, 60]
 grid_subset = pygmt.datasets.load_earth_relief(resolution="10m", region=subset_region)
 
-# Define a 1-row, 2-column subplot layout. The overall figure dimensions are
-# set to be 15 cm wide and 8 cm high. Each subplot is automatically labelled.
-# The space between the subplots is set to be 0.5 cm.
-with fig.subplot(
-    nrows=1, ncols=2, figsize=("15c", "8c"), autolabel=True, margins="0.5c"
-):
-    # Activate the first panel so that the colormap created by the makecpt
-    # function is a panel-level CPT
+# Define a 1-row, 2-column subplot layout. The overall figure dimensions are set to be
+# 15 cm wide and 8 cm high. Each subplot is automatically labelled. The space between
+# the subplots is set to be 0.5 cm.
+with fig.subplot(nrows=1, ncols=2, figsize=("15c", "8c"), autotag=True, margins="0.5c"):
+    # Activate the first panel so that the colormap created by the makecpt function is
+    # a panel-level CPT
     with fig.set_panel(panel=0):
         pygmt.makecpt(cmap="gmt/geo", series=[-8000, 8000])
-        # "R?" means Winkel Tripel projection with map width automatically
-        # determined from the subplot width.
+        # "R?" means Winkel Tripel projection with map width automatically determined
+        # from the subplot width.
         fig.grdimage(grid=grid_globe, projection="R?", region="g", frame="a")
         fig.colorbar(frame=["a4000f2000", "x+lElevation", "y+lm"])
-    # Activate the second panel so that the colormap created by the makecpt
-    # function is a panel-level CPT
+    # Activate the second panel so that the colormap created by the makecpt function is
+    # a panel-level CPT
     with fig.set_panel(panel=1):
         pygmt.makecpt(cmap="gmt/globe", series=[-6000, 3000])
-        # "M?" means Mercator projection with map width also automatically
-        # determined from the subplot width.
+        # "M?" means Mercator projection with map width also automatically determined
+        # from the subplot width.
         fig.grdimage(grid=grid_subset, projection="M?", region=subset_region, frame="a")
         fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
 
diff --git a/examples/tutorials/advanced/subplots.py b/examples/tutorials/advanced/subplots.py
index 1fb43fc02a4..7460432e422 100644
--- a/examples/tutorials/advanced/subplots.py
+++ b/examples/tutorials/advanced/subplots.py
@@ -3,7 +3,7 @@
 ===============
 
 When you're preparing a figure for a paper, there will often be times when
-you'll need to put many individual plots into one large figure, and label them
+you'll need to put many individual plots into one large figure, and tag them
 'abcd'. These individual plots are called subplots.
 
 There are two main ways to create subplots in GMT:
@@ -100,7 +100,7 @@
     nrows=2,
     ncols=2,
     figsize=("15c", "6c"),
-    autolabel=True,
+    autotag=True,
     frame=["af", "WSne"],
     margins=["0.1c", "0.2c"],
     title="My Subplot Heading",
@@ -117,7 +117,7 @@
 # 15 cm wide and 6 cm high (``figsize=["15c", "6c"]``). In addition, we use
 # some optional parameters to fine-tune some details of the figure creation:
 #
-# - ``autolabel=True``: Each subplot is automatically labelled 'abcd'.
+# - ``autotag=True``: Each subplot is automatically tagged 'abcd'.
 # - ``margins=["0.1c", "0.2c"]``: Adjusts the space between adjacent subplots.
 #   In this case, it is set as 0.1 cm in the x-direction and 0.2 cm in the
 #   y-direction.
@@ -168,7 +168,7 @@
     nrows=2,
     ncols=2,
     figsize=("15c", "6c"),  # width of 15 cm, height of 6 cm
-    autolabel=True,
+    autotag=True,
     margins=["0.3c", "0.2c"],  # horizontal 0.3 cm and vertical 0.2 cm margins
     title="My Subplot Heading",
     sharex="b",  # shared x-axis on the bottom side
@@ -204,7 +204,7 @@
 
 fig = pygmt.Figure()
 # Bottom row, two subplots
-with fig.subplot(nrows=1, ncols=2, figsize=("15c", "3c"), autolabel="b)"):
+with fig.subplot(nrows=1, ncols=2, figsize=("15c", "3c"), autotag="b)"):
     fig.basemap(
         region=[0, 5, 0, 5], projection="X?", frame=["af", "WSne"], panel=[0, 0]
     )
@@ -214,7 +214,7 @@
 # Move plot origin by 1 cm above the height of the entire figure
 fig.shift_origin(yshift="h+1c")
 # Top row, one subplot
-with fig.subplot(nrows=1, ncols=1, figsize=("15c", "3c"), autolabel="a)"):
+with fig.subplot(nrows=1, ncols=1, figsize=("15c", "3c"), autotag="a)"):
     fig.basemap(
         region=[0, 10, 0, 10], projection="X?", frame=["af", "WSne"], panel=[0, 0]
     )
@@ -223,20 +223,20 @@
 fig.show()
 
 # %%
-# We start by drawing the bottom two subplots, setting ``autolabel="b)"`` so
-# that the subplots are labelled 'b)' and 'c)'. Next, we use
+# We start by drawing the bottom two subplots, setting ``autotag="b)"`` so
+# that the subplots are tagged 'b)' and 'c)'. Next, we use
 # :meth:`pygmt.Figure.shift_origin` to move the plot origin 1 cm above the
 # **h**\ eight of the entire figure that is currently plotted (i.e. the bottom
 # row subplots). A single subplot is then plotted on the top row. You may need
 # to adjust the ``yshift`` parameter to make your plot look nice. This top row
-# uses ``autolabel="a)"``, and we also plotted some text inside. Note that
+# uses ``autotag="a)"``, and we also plotted some text inside. Note that
 # ``projection="X?"`` was used to let GMT automatically determine the size of
 # the subplot according to the size of the subplot area.
 
 # %%
-# You can also manually override the ``autolabel`` for each subplot using for
+# You can also manually override the ``autotag`` for each subplot using for
 # example, ``fig.set_panel(..., fixedlabel="b) Panel 2")`` which would allow
-# you to manually label a single subplot as you wish. This can be useful for
+# you to manually tag a single subplot as you wish. This can be useful for
 # adding a more descriptive subtitle to individual subplots.
 
 # sphinx_gallery_thumbnail_number = 3
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index a477623a85f..68d9fef40dd 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -39,9 +39,9 @@ def test_subplot_direct():
 
 
 @pytest.mark.mpl_image_compare
-def test_subplot_autolabel_margins_title():
+def test_subplot_autotag_margins_title():
     """
-    Make subplot figure with autolabels, setting some margins and a title.
+    Make subplot figure with autotags, setting some margins and a title.
     """
     fig = Figure()
 
@@ -49,7 +49,7 @@ def test_subplot_autolabel_margins_title():
         nrows=2,
         ncols=1,
         figsize=("15c", "6c"),
-        autolabel=True,
+        autotag=True,
         margins=["0.3c", "0.1c"],
         title="Subplot Title",
     ):

From 834082958d7782fe02c2234e073d30ed3a8724a9 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 30 Jan 2026 18:45:56 +0800
Subject: [PATCH 06/16] Fix the validation logic for tag_position

---
 pygmt/src/subplot.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index d67f2a73a55..b91d5d8b941 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -85,7 +85,11 @@ def _alias_option_A(  # noqa: N802
                 reason="Only one or two values are accepted.",
             )
     # Validate the tag_position if provided.
-    if tag_position.cstype in {"mapcoords", "plotcoords", "boxcoords"}:
+    if getattr(tag_position, "cstype", None) in {
+        "mapcoords",
+        "plotcoords",
+        "boxcoords",
+    }:
         raise GMTValueError(
             tag_position,
             description="tag position for 'Figure.subplot'.",

From 9d2717869b7f30aac5ef50e126782299e150435c Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 30 Jan 2026 19:10:47 +0800
Subject: [PATCH 07/16] Rename  test_subplot_autolabel_margins_title.png.dvc ->
 test_subplot_autotag_margins_title.png.dvc

---
 ...title.png.dvc => test_subplot_autotag_margins_title.png.dvc} | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 rename pygmt/tests/baseline/{test_subplot_autolabel_margins_title.png.dvc => test_subplot_autotag_margins_title.png.dvc} (59%)

diff --git a/pygmt/tests/baseline/test_subplot_autolabel_margins_title.png.dvc b/pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc
similarity index 59%
rename from pygmt/tests/baseline/test_subplot_autolabel_margins_title.png.dvc
rename to pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc
index 1b3ba8b2e22..713e5f3a32e 100644
--- a/pygmt/tests/baseline/test_subplot_autolabel_margins_title.png.dvc
+++ b/pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc
@@ -1,5 +1,5 @@
 outs:
 - md5: a4af27ae0468c63a8d6200c6a7f9908f
   size: 22646
-  path: test_subplot_autolabel_margins_title.png
+  path: test_subplot_autotag_margins_title.png
   hash: md5

From 0c7de28b339d018d954857e3f8992faf714f3848 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 5 Feb 2026 11:49:19 +0800
Subject: [PATCH 08/16] Fix conflicts

---
 pygmt/src/subplot.py        | 2 +-
 pygmt/tests/test_subplot.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 91c137e6427..b5ad2409f3d 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -9,7 +9,7 @@
 from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTParameterError, GMTValueError
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 from pygmt.params import Box, Position
 from pygmt.src._common import _parse_position
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index 6209c495193..97ef476cb13 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTParameterError, GMTValueError
+from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTValueError
 from pygmt.params import Position
 
 

From 89e4e88849b3486da4a79b3290ad7a253e6db5f5 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 5 Feb 2026 11:59:49 +0800
Subject: [PATCH 09/16] Add more tests

---
 .../embellishments/colorbars_multiple.py      |  6 +--
 pygmt/src/subplot.py                          |  2 +-
 pygmt/tests/test_subplot.py                   | 41 ++++++++++++++++++-
 3 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py
index d3c29512b1c..c6e219ead21 100644
--- a/examples/gallery/embellishments/colorbars_multiple.py
+++ b/examples/gallery/embellishments/colorbars_multiple.py
@@ -19,9 +19,9 @@
 grid_subset = pygmt.datasets.load_earth_relief(resolution="10m", region=subset_region)
 
 # Define a 1-row, 2-column subplot layout. The overall figure dimensions are set to be
-# 15 cm wide and 8 cm high. Each subplot is automatically labelled. The space between
-# the subplots is set to be 0.5 cm.
-with fig.subplot(nrows=1, ncols=2, figsize=("15c", "8c"), autotag=True, margins="0.5c"):
+# 15 cm wide and 8 cm high. Each subplot is automatically tagged. The space between the
+# subplots is set to be 0.5 cm.
+with fig.subplot(nrows=1, ncols=2, figsize=("15c", "8c"), autotag=True, margins=0.5):
     # Activate the first panel so that the colormap created by the makecpt function is
     # a panel-level CPT
     with fig.set_panel(panel=0):
diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index b5ad2409f3d..cd67104ddcf 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -60,7 +60,7 @@ def _alias_option_A(  # noqa: N802
             for v in [autotag, tag_position, tag_box, tag_number_style, tag_orientation]
         ):
             msg = (
-                "The 'autolabel' parameter is deprecated since v0.18.0. "
+                "The 'autolabel' parameter is deprecated since v0.19.0. "
                 "Please use the parameters 'autotag', 'tag_position', 'tag_box', "
                 "'tag_number_style', 'tag_orientation', and 'tag_font' instead."
             )
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index 97ef476cb13..9ac0ddb5d86 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -6,6 +6,7 @@
 from pygmt import Figure
 from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTValueError
 from pygmt.params import Position
+from pygmt.params.box import Box
 
 
 @pytest.mark.benchmark
@@ -127,7 +128,7 @@ def test_subplot_outside_plotting_positioning():
     return fig
 
 
-def test_deprecated_autolabel():
+def test_subplot_deprecated_autolabel():
     """
     Test that using the deprecated autolabel parameter raises a warning when conflicted
     with tag parameters.
@@ -148,3 +149,41 @@ def test_deprecated_autolabel():
     with pytest.raises(GMTInvalidInput):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_position="TL"):
             pass
+
+
+def test_subplot_invalid_tag_box_position():
+    """
+    Test that using an invalid tag_box/tag_position raises an error.
+    """
+    fig = Figure()
+    # Box properties "inner_pen", "inner_gap", and "radius" are not supported.
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, tag_box=Box(inner_pen="1p")):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, tag_box=Box(inner_gap=1)):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, tag_box=Box(radius=1)):
+            pass
+    # Box clearance must be a single value or a tuple of two values.
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(nrows=1, ncols=1, tag_box=Box(clearance=(1, 2, 3, 4))):
+            pass
+
+    # Position's cstype must be "inside" or "outside".
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(
+            nrows=1, ncols=1, tag_position=Position((1, 1), cstype="mapcoords")
+        ):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(
+            nrows=1, ncols=1, tag_position=Position((1, 1), cstype="boxcoords")
+        ):
+            pass
+    with pytest.raises(GMTInvalidInput):
+        with fig.subplot(
+            nrows=1, ncols=1, tag_position=Position((1, 1), cstype="plotcoords")
+        ):
+            pass

From c3a3282fec4ba841aab52b0f1e7b33117a7dc111 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 5 Feb 2026 12:02:05 +0800
Subject: [PATCH 10/16] Improve comments

---
 pygmt/src/subplot.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index cd67104ddcf..cf79209a7af 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -98,9 +98,8 @@ def _alias_option_A(  # noqa: N802
 
     return [
         Alias(autotag, name="autotag"),
-        Alias(
-            _parse_position(tag_position), name="tag_position", prefix="+"
-        ),  # Prefix is "+".
+        # tag_position's prefix is "+", not "+j" or "+J".
+        Alias(_parse_position(tag_position), name="tag_position", prefix="+"),
         Alias(tag_box, name="tag_box"),
         Alias(
             tag_number_style,

From af724ea01c3a155f4a0c41089053ffdeb4e59bcf Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 5 Feb 2026 12:05:06 +0800
Subject: [PATCH 11/16] Fix type hints

---
 pygmt/src/subplot.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index cf79209a7af..d010d8f6ab7 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -78,7 +78,7 @@ def _alias_option_A(  # noqa: N802
                 description="Box properties for 'tag_box' in 'Figure.subplot'",
                 reason="The 'inner_pen', 'inner_gap', and 'radius' properties are not supported.",
             )
-        if tag_box.clearance and len(tag_box.clearance) > 2:
+        if isinstance(tag_box.clearance, Sequence) and len(tag_box.clearance) > 2:
             raise GMTValueError(
                 tag_box,
                 description="Box 'clearance' property for 'tag_box' in 'Figure.subplot'",

From 1f159073e3a3d40e5c5ff9d2af18f38dbee18b49 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 12:56:00 +0800
Subject: [PATCH 12/16] Rename autotag to tag

---
 .../embellishments/colorbars_multiple.py      |  2 +-
 examples/tutorials/advanced/subplots.py       | 16 +++----
 pygmt/src/subplot.py                          | 48 +++++++++++--------
 ...=> test_subplot_tag_margins_title.png.dvc} |  2 +-
 pygmt/tests/test_subplot.py                   |  8 ++--
 5 files changed, 42 insertions(+), 34 deletions(-)
 rename pygmt/tests/baseline/{test_subplot_autotag_margins_title.png.dvc => test_subplot_tag_margins_title.png.dvc} (60%)

diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py
index c6e219ead21..0edd822b8ce 100644
--- a/examples/gallery/embellishments/colorbars_multiple.py
+++ b/examples/gallery/embellishments/colorbars_multiple.py
@@ -21,7 +21,7 @@
 # Define a 1-row, 2-column subplot layout. The overall figure dimensions are set to be
 # 15 cm wide and 8 cm high. Each subplot is automatically tagged. The space between the
 # subplots is set to be 0.5 cm.
-with fig.subplot(nrows=1, ncols=2, figsize=("15c", "8c"), autotag=True, margins=0.5):
+with fig.subplot(nrows=1, ncols=2, figsize=("15c", "8c"), tag=True, margins=0.5):
     # Activate the first panel so that the colormap created by the makecpt function is
     # a panel-level CPT
     with fig.set_panel(panel=0):
diff --git a/examples/tutorials/advanced/subplots.py b/examples/tutorials/advanced/subplots.py
index 7460432e422..54d20d9a602 100644
--- a/examples/tutorials/advanced/subplots.py
+++ b/examples/tutorials/advanced/subplots.py
@@ -100,7 +100,7 @@
     nrows=2,
     ncols=2,
     figsize=("15c", "6c"),
-    autotag=True,
+    tag=True,
     frame=["af", "WSne"],
     margins=["0.1c", "0.2c"],
     title="My Subplot Heading",
@@ -117,7 +117,7 @@
 # 15 cm wide and 6 cm high (``figsize=["15c", "6c"]``). In addition, we use
 # some optional parameters to fine-tune some details of the figure creation:
 #
-# - ``autotag=True``: Each subplot is automatically tagged 'abcd'.
+# - ``tag=True``: Each subplot is automatically tagged 'abcd'.
 # - ``margins=["0.1c", "0.2c"]``: Adjusts the space between adjacent subplots.
 #   In this case, it is set as 0.1 cm in the x-direction and 0.2 cm in the
 #   y-direction.
@@ -168,7 +168,7 @@
     nrows=2,
     ncols=2,
     figsize=("15c", "6c"),  # width of 15 cm, height of 6 cm
-    autotag=True,
+    tag=True,
     margins=["0.3c", "0.2c"],  # horizontal 0.3 cm and vertical 0.2 cm margins
     title="My Subplot Heading",
     sharex="b",  # shared x-axis on the bottom side
@@ -204,7 +204,7 @@
 
 fig = pygmt.Figure()
 # Bottom row, two subplots
-with fig.subplot(nrows=1, ncols=2, figsize=("15c", "3c"), autotag="b)"):
+with fig.subplot(nrows=1, ncols=2, figsize=("15c", "3c"), tag="b)"):
     fig.basemap(
         region=[0, 5, 0, 5], projection="X?", frame=["af", "WSne"], panel=[0, 0]
     )
@@ -214,7 +214,7 @@
 # Move plot origin by 1 cm above the height of the entire figure
 fig.shift_origin(yshift="h+1c")
 # Top row, one subplot
-with fig.subplot(nrows=1, ncols=1, figsize=("15c", "3c"), autotag="a)"):
+with fig.subplot(nrows=1, ncols=1, figsize=("15c", "3c"), tag="a)"):
     fig.basemap(
         region=[0, 10, 0, 10], projection="X?", frame=["af", "WSne"], panel=[0, 0]
     )
@@ -223,18 +223,18 @@
 fig.show()
 
 # %%
-# We start by drawing the bottom two subplots, setting ``autotag="b)"`` so
+# We start by drawing the bottom two subplots, setting ``tag="b)"`` so
 # that the subplots are tagged 'b)' and 'c)'. Next, we use
 # :meth:`pygmt.Figure.shift_origin` to move the plot origin 1 cm above the
 # **h**\ eight of the entire figure that is currently plotted (i.e. the bottom
 # row subplots). A single subplot is then plotted on the top row. You may need
 # to adjust the ``yshift`` parameter to make your plot look nice. This top row
-# uses ``autotag="a)"``, and we also plotted some text inside. Note that
+# uses ``tag="a)"``, and we also plotted some text inside. Note that
 # ``projection="X?"`` was used to let GMT automatically determine the size of
 # the subplot according to the size of the subplot area.
 
 # %%
-# You can also manually override the ``autotag`` for each subplot using for
+# You can also manually override the ``tag`` for each subplot using for
 # example, ``fig.set_panel(..., fixedlabel="b) Panel 2")`` which would allow
 # you to manually tag a single subplot as you wish. This can be useful for
 # adding a more descriptive subtitle to individual subplots.
diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index ff57a5854f9..18298aa8d50 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -9,14 +9,14 @@
 from pygmt._typing import AnchorCode
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 from pygmt.params import Box, Position
 from pygmt.src._common import _parse_position
 
 
 def _alias_option_A(  # noqa: N802
-    autotag: str | bool = False,
+    tag: str | bool = False,
     tag_position: AnchorCode | Position | None = None,
     tag_box: Box | None = None,
     tag_number_style: Literal["arabic", "roman", "Roman"] | None = None,
@@ -30,7 +30,7 @@ def _alias_option_A(  # noqa: N802
     --------
     >>> def parse(**kwargs):
     ...     return AliasSystem(A=_alias_option_A(**kwargs)).get("A")
-    >>> parse(autotag="a)")
+    >>> parse(tag="a)")
     'a)'
     >>> parse(tag_position="TL")
     '+jTL'
@@ -45,7 +45,7 @@ def _alias_option_A(  # noqa: N802
     >>> parse(tag_orientation="vertical")
     '+v'
     >>> parse(
-    ...     autotag="(1)",
+    ...     tag="(1)",
     ...     tag_position="TL",
     ...     tag_box=Box(pen="1p,red"),
     ...     tag_number_style="Roman",
@@ -57,14 +57,22 @@ def _alias_option_A(  # noqa: N802
     if autolabel:
         if any(
             v is not None and v is not False
-            for v in [autotag, tag_position, tag_box, tag_number_style, tag_orientation]
+            for v in [tag, tag_position, tag_box, tag_number_style, tag_orientation]
         ):
-            msg = (
-                "The 'autolabel' parameter is deprecated since v0.19.0. "
-                "Please use the parameters 'autotag', 'tag_position', 'tag_box', "
-                "'tag_number_style', 'tag_orientation', and 'tag_font' instead."
+            raise GMTParameterError(
+                conflicts_with=(
+                    "autolabel",
+                    [
+                        "tag",
+                        "tag_position",
+                        "tag_box",
+                        "tag_number_style",
+                        "tag_orientation",
+                        "tag_font",
+                    ],
+                ),
+                reason="'autolabel' is specified using a unrecommend GMT command string syntax.",
             )
-            raise GMTInvalidInput(msg)
         return Alias(autolabel, name="autolabel")
 
     # Validate tag_box if provided.
@@ -97,7 +105,7 @@ def _alias_option_A(  # noqa: N802
         )
 
     return [
-        Alias(autotag, name="autotag"),
+        Alias(tag, name="tag"),
         # tag_position's prefix is "+", not "+j" or "+J".
         Alias(_parse_position(tag_position), name="tag_position", prefix="+"),
         Alias(tag_box, name="tag_box"),
@@ -122,7 +130,7 @@ def subplot(  # noqa: PLR0913
     self,
     nrows: int = 1,
     ncols: int = 1,
-    autotag: str | bool = False,
+    tag: str | bool = False,
     tag_position: AnchorCode | Position | None = None,
     tag_box: Box | None = None,
     tag_orientation: Literal["horizontal", "vertical"] | None = None,
@@ -169,7 +177,7 @@ def subplot(  # noqa: PLR0913
         Specify the dimensions of each subplot directly as [*width*, *height*].
         Note that only one of ``figsize`` or ``subsize`` can be provided at
         once.
-    autotag
+    tag
         Specify automatic tagging of each subplot. It can accept a number, or a letter.
         The number or letter can be surrounded by parentheses on any side if these
         should be typeset as part of the tag. This sets the tag of the first, top-left
@@ -177,11 +185,11 @@ def subplot(  # noqa: PLR0913
 
         Examples are:
 
-        - ``autotag="a"``: tags are ``a``, ``b``, ``c``, ...
-        - ``autotag="1"``: tags are ``1``, ``2``, ``3``, ...
-        - ``autotag="a)"``: tags are ``a)``, ``b)``, ``c)``, ...
-        - ``autotag="(c)"``: tags are ``(c)``, ``(d)``, ``(e)``, ...
-        - ``autotag=True``: same as ``autotag="a)"``.
+        - ``tag="a"``: tags are ``a``, ``b``, ``c``, ...
+        - ``tag="1"``: tags are ``1``, ``2``, ``3``, ...
+        - ``tag="a)"``: tags are ``a)``, ``b)``, ``c)``, ...
+        - ``tag="(c)"``: tags are ``(c)``, ``(d)``, ``(e)``, ...
+        - ``tag=True``: same as ``tag="a)"``.
     tag_position
         Position of the subplot tag on the plot. It can be specified in two ways:
 
@@ -220,7 +228,7 @@ def subplot(  # noqa: PLR0913
 
         .. deprecated:: v0.19.0
 
-           Use the parameters ``autotag``, ``tag_position``, ``tag_box``,
+           Use the parameters ``tag``, ``tag_position``, ``tag_box``,
            ``tag_number_style``, ``tag_orientation``, and ``tag_font`` instead.
     clearance : str or list
         [*side*]\ *clearance*.
@@ -300,7 +308,7 @@ def subplot(  # noqa: PLR0913
 
     aliasdict = AliasSystem(
         A=_alias_option_A(
-            autotag=autotag,
+            tag=tag,
             tag_position=tag_position,
             tag_box=tag_box,
             tag_number_style=tag_number_style,
diff --git a/pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc b/pygmt/tests/baseline/test_subplot_tag_margins_title.png.dvc
similarity index 60%
rename from pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc
rename to pygmt/tests/baseline/test_subplot_tag_margins_title.png.dvc
index 713e5f3a32e..3d703db7763 100644
--- a/pygmt/tests/baseline/test_subplot_autotag_margins_title.png.dvc
+++ b/pygmt/tests/baseline/test_subplot_tag_margins_title.png.dvc
@@ -1,5 +1,5 @@
 outs:
 - md5: a4af27ae0468c63a8d6200c6a7f9908f
   size: 22646
-  path: test_subplot_autotag_margins_title.png
+  path: test_subplot_tag_margins_title.png
   hash: md5
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index 9ac0ddb5d86..b908d647fb5 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -40,9 +40,9 @@ def test_subplot_direct():
 
 
 @pytest.mark.mpl_image_compare
-def test_subplot_autotag_margins_title():
+def test_subplot_tag_margins_title():
     """
-    Make subplot figure with autotags, setting some margins and a title.
+    Make subplot figure with tags, setting some margins and a title.
     """
     fig = Figure()
 
@@ -50,7 +50,7 @@ def test_subplot_autotag_margins_title():
         nrows=2,
         ncols=1,
         figsize=("15c", "6c"),
-        autotag=True,
+        tag=True,
         margins=["0.3c", "0.1c"],
         title="Subplot Title",
     ):
@@ -135,7 +135,7 @@ def test_subplot_deprecated_autolabel():
     """
     fig = Figure()
     with pytest.raises(GMTInvalidInput):
-        with fig.subplot(nrows=1, ncols=1, autolabel=True, autotag="a)"):
+        with fig.subplot(nrows=1, ncols=1, autolabel=True, tag="a)"):
             pass
     with pytest.raises(GMTInvalidInput):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_box=True):

From 1f7af38c35f83b8f3f88bbf7a4789a02d7158e25 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 12:56:56 +0800
Subject: [PATCH 13/16] Fix a typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 pygmt/src/subplot.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 18298aa8d50..4566745ef2e 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -196,7 +196,7 @@ def subplot(  # noqa: PLR0913
         - A :doc:`2-character justification code </techref/justification_codes>` for a
           position inside the plot, e.g., ``"TL"`` for Top Left corner inside the plot.
         - A :class:`pygmt.params.Position` object to fully control the position and
-          offset. **Note**: the ``refpoint`` propterty of the Position object must be
+          offset. **Note**: the ``refpoint`` property of the Position object must be
           an two-character justification code, and ``cstype`` must be set to either
           ``"inside"`` or ``"outside"``,
 

From d652e018bc51f196a2272a735a804845deea7b5f Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 13:01:39 +0800
Subject: [PATCH 14/16] Fix tests

---
 pygmt/tests/test_subplot.py | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index b908d647fb5..03c370539b2 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -4,7 +4,7 @@
 
 import pytest
 from pygmt import Figure
-from pygmt.exceptions import GMTInvalidInput, GMTParameterError, GMTValueError
+from pygmt.exceptions import GMTParameterError, GMTValueError
 from pygmt.params import Position
 from pygmt.params.box import Box
 
@@ -134,19 +134,19 @@ def test_subplot_deprecated_autolabel():
     with tag parameters.
     """
     fig = Figure()
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag="a)"):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_box=True):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_orientation="vertical"):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_number_style="roman"):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTParameterError):
         with fig.subplot(nrows=1, ncols=1, autolabel=True, tag_position="TL"):
             pass
 
@@ -157,32 +157,32 @@ def test_subplot_invalid_tag_box_position():
     """
     fig = Figure()
     # Box properties "inner_pen", "inner_gap", and "radius" are not supported.
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(nrows=1, ncols=1, tag_box=Box(inner_pen="1p")):
             pass
-    with pytest.raises(GMTInvalidInput):
-        with fig.subplot(nrows=1, ncols=1, tag_box=Box(inner_gap=1)):
+    with pytest.raises(GMTValueError):
+        with fig.subplot(nrows=1, ncols=1, tag_box=Box(inner_gap=1, inner_pen="1p")):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(nrows=1, ncols=1, tag_box=Box(radius=1)):
             pass
     # Box clearance must be a single value or a tuple of two values.
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(nrows=1, ncols=1, tag_box=Box(clearance=(1, 2, 3, 4))):
             pass
 
     # Position's cstype must be "inside" or "outside".
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(
             nrows=1, ncols=1, tag_position=Position((1, 1), cstype="mapcoords")
         ):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(
             nrows=1, ncols=1, tag_position=Position((1, 1), cstype="boxcoords")
         ):
             pass
-    with pytest.raises(GMTInvalidInput):
+    with pytest.raises(GMTValueError):
         with fig.subplot(
             nrows=1, ncols=1, tag_position=Position((1, 1), cstype="plotcoords")
         ):

From 81ae0eed610e73cb1687ba8af3a18e17ed0f2cba Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 13:11:16 +0800
Subject: [PATCH 15/16] Improve docstrings

---
 pygmt/src/subplot.py        | 5 ++---
 pygmt/tests/test_subplot.py | 3 +--
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 4566745ef2e..6a291dacfa1 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -68,7 +68,6 @@ def _alias_option_A(  # noqa: N802
                         "tag_box",
                         "tag_number_style",
                         "tag_orientation",
-                        "tag_font",
                     ],
                 ),
                 reason="'autolabel' is specified using a unrecommend GMT command string syntax.",
@@ -209,7 +208,7 @@ def subplot(  # noqa: PLR0913
         **Notes on the use of the ``Box`` class:**
 
         - The property ``clearance`` only accept one or two values.
-        - The property ``inner_pen``/``inner_gap``/``radius`` is not supported.
+        - The properties ``inner_pen``, ``inner_gap``, ``radius`` are not supported.
     tag_number_style
         Style of the subplot tag numbers. It can be:
 
@@ -224,7 +223,7 @@ def subplot(  # noqa: PLR0913
     tag_font
         Font for the subplot tag [Default to ``"20p,Helvetica,black"``].
     autolabel
-        Specify automatic tagging of each subplot.
+        Specify automatic tag of each subplot.
 
         .. deprecated:: v0.19.0
 
diff --git a/pygmt/tests/test_subplot.py b/pygmt/tests/test_subplot.py
index 03c370539b2..d0cb819f810 100644
--- a/pygmt/tests/test_subplot.py
+++ b/pygmt/tests/test_subplot.py
@@ -5,8 +5,7 @@
 import pytest
 from pygmt import Figure
 from pygmt.exceptions import GMTParameterError, GMTValueError
-from pygmt.params import Position
-from pygmt.params.box import Box
+from pygmt.params import Box, Position
 
 
 @pytest.mark.benchmark

From 0c85280d93e827e1c9f42e03dc5c2e3aeac237e6 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 13:17:43 +0800
Subject: [PATCH 16/16] Rewrap to 88 characeters

---
 examples/tutorials/advanced/subplots.py | 156 ++++++++++++------------
 1 file changed, 75 insertions(+), 81 deletions(-)

diff --git a/examples/tutorials/advanced/subplots.py b/examples/tutorials/advanced/subplots.py
index 54d20d9a602..5261b7faf7a 100644
--- a/examples/tutorials/advanced/subplots.py
+++ b/examples/tutorials/advanced/subplots.py
@@ -2,20 +2,20 @@
 Making subplots
 ===============
 
-When you're preparing a figure for a paper, there will often be times when
-you'll need to put many individual plots into one large figure, and tag them
-'abcd'. These individual plots are called subplots.
+When you're preparing a figure for a paper, there will often be times when you'll need
+to put many individual plots into one large figure, and tag them 'abcd'. These
+individual plots are called subplots.
 
 There are two main ways to create subplots in GMT:
 
-- Use :meth:`pygmt.Figure.shift_origin` to manually move each individual plot
-  to the right position.
+- Use :meth:`pygmt.Figure.shift_origin` to manually move each individual plot to the
+  right position.
 - Use :meth:`pygmt.Figure.subplot` to define the layout of the subplots.
 
-The first method is easier to use and should handle simple cases involving a
-couple of subplots. For more advanced subplot layouts, however, we recommend
-the use of :meth:`pygmt.Figure.subplot` which offers finer grained control, and
-this is what the tutorial below will cover.
+The first method is easier to use and should handle simple cases involving a couple of
+subplots. For more advanced subplot layouts, however, we recommend the use of
+:meth:`pygmt.Figure.subplot` which offers finer grained control, and this is what the
+tutorial below will cover.
 """
 
 # %%
@@ -31,10 +31,10 @@
 # Define subplot layout
 # ---------------------
 #
-# The :meth:`pygmt.Figure.subplot` method is used to set up the layout, size,
-# and other attributes of the figure. It divides the whole canvas into regular
-# grid areas with *n* rows and *m* columns. Each grid area can contain an
-# individual subplot. For example:
+# The :meth:`pygmt.Figure.subplot` method is used to set up the layout, size, and other
+# attributes of the figure. It divides the whole canvas into regular grid areas with
+# *n* rows and *m* columns. Each grid area can contain an individual subplot. For
+# example:
 
 # %%
 # .. code-block:: default
@@ -44,10 +44,10 @@
 
 # %%
 # will define our figure to have a 2 row and 3 column grid layout.
-# ``figsize=("15c", "6c")`` defines the overall size of the figure to be 15 cm
-# wide by 6 cm high. Using ``frame="lrtb"`` allows us to customize the map
-# frame for all subplots instead of setting them individually. The figure
-# layout will look like the following:
+# ``figsize=("15c", "6c")`` defines the overall size of the figure to be 15 cm wide by
+# 6 cm high. Using ``frame="lrtb"`` allows us to customize the map frame for all
+# subplots instead of setting them individually. The figure layout will look like the
+# following:
 
 with fig.subplot(nrows=2, ncols=3, figsize=("15c", "6c"), frame="lrtb"):
     for i in range(2):  # row number starting from 0
@@ -62,29 +62,28 @@
 fig.show()
 
 # %%
-# The :meth:`pygmt.Figure.set_panel` method activates a specified subplot,
-# and all subsequent plotting methods will take place in that subplot panel.
-# This is similar to matplotlib's ``plt.sca`` method. In order to specify a
-# subplot, you will need to provide the identifier for that subplot via the
-# ``panel`` parameter. Pass in either the *index* number, or a tuple/list like
-# (*row*, *col*) to ``panel``.
+# The :meth:`pygmt.Figure.set_panel` method activates a specified subplot, and all
+# subsequent plotting methods will take place in that subplot panel. This is similar to
+# matplotlib's ``plt.sca`` method. In order to specify a subplot, you will need to
+# provide the identifier for that subplot via the ``panel`` parameter. Pass in either
+# the *index* number, or a tuple/list like (*row*, *col*) to ``panel``.
 
 # %%
 # .. note::
 #
-#     The row and column numbering starts from 0. So for a subplot layout with
-#     N rows and M columns, row numbers will go from 0 to N-1, and column
-#     numbers will go from 0 to M-1.
+#     The row and column numbering starts from 0. So for a subplot layout with N rows
+#     and M columns, row numbers will go from 0 to N-1, and column numbers will go from
+#     0 to M-1.
 
 # %%
-# For example, to activate the subplot on the top right corner (index: 2) at
-# *row*\=0 and *col*\=2, so that all subsequent plotting commands happen
-# there, you can use the following command:
+# For example, to activate the subplot on the top right corner (index: 2) at *row*\=0
+# and *col*\=2, so that all subsequent plotting commands happen there, you can use the
+# following command:
 
 # %%
 # .. code-block:: default
 #
-#     with fig.set_panel(panel=[0, 2]):
+#     with fig.set_panel(panel=(0, 2)):
 #         ...
 
 
@@ -92,8 +91,8 @@
 # Making your first subplot
 # -------------------------
 #
-# Next, let's use what we learned above to make a 2 row by 2 column subplot
-# figure. We'll also pick up on some new parameters to configure our subplot.
+# Next, let's use what we learned above to make a 2 row by 2 column subplot figure.
+# We'll also pick up on some new parameters to configure our subplot.
 
 fig = pygmt.Figure()
 with fig.subplot(
@@ -113,55 +112,52 @@
 
 # %%
 # In this example, we define a 2-row, 2-column (2x2) subplot layout using
-# :meth:`pygmt.Figure.subplot`. The overall figure dimensions is set to be
-# 15 cm wide and 6 cm high (``figsize=["15c", "6c"]``). In addition, we use
-# some optional parameters to fine-tune some details of the figure creation:
+# :meth:`pygmt.Figure.subplot`. The overall figure dimensions is set to be 15 cm wide
+# and 6 cm high (``figsize=("15c", "6c")``). In addition, we use some optional
+# parameters to fine-tune some details of the figure creation:
 #
 # - ``tag=True``: Each subplot is automatically tagged 'abcd'.
-# - ``margins=["0.1c", "0.2c"]``: Adjusts the space between adjacent subplots.
-#   In this case, it is set as 0.1 cm in the x-direction and 0.2 cm in the
-#   y-direction.
+# - ``margins=["0.1c", "0.2c"]``: Adjusts the space between adjacent subplots. In this
+#   case, it is set as 0.1 cm in the x-direction and 0.2 cm in the y-direction.
 # - ``title="My Subplot Heading"``: Adds a title on top of the whole figure.
 #
-# Notice that each subplot was set to use a linear projection ``"X?"``.
-# Usually, we need to specify the width and height of the map frame, but it is
-# also possible to use a question mark ``"?"`` to let GMT decide automatically
-# on what is the most appropriate width/height for each subplot's map frame.
+# Notice that each subplot was set to use a linear projection ``"X?"``. Usually, we need
+# to specify the width and height of the map frame, but it is also possible to use a
+# question mark ``"?"`` to let GMT decide automatically on what is the most appropriate
+# width/height for each subplot's map frame.
 
 # %%
 # .. tip::
 #
-#     In the above example, we used the following commands to activate the
-#     four subplots explicitly one after another::
+#     In the above example, we used the following commands to activate the four subplots
+#     explicitly one after another::
 #
 #         fig.basemap(..., panel=[0, 0])
 #         fig.basemap(..., panel=[0, 1])
 #         fig.basemap(..., panel=[1, 0])
 #         fig.basemap(..., panel=[1, 1])
 #
-#     In fact, we can just use ``fig.basemap(..., panel=True)`` without
-#     specifying any subplot index number, and GMT will automatically activate
-#     the next subplot panel.
+#     In fact, we can just use ``fig.basemap(..., panel=True)`` without specifying any
+#     subplot index number, and GMT will automatically activate the next subplot panel.
 
 # %%
 # .. note::
 #
-#     All plotting methods (e.g. :meth:`pygmt.Figure.coast`,
-#     :meth:`pygmt.Figure.text`, etc) are able to use ``panel`` parameter when
-#     in subplot mode. Once a panel is activated using ``panel`` or
-#     :meth:`pygmt.Figure.set_panel`, subsequent plotting commands that don't
-#     set a ``panel`` will have their elements added to the same panel as
-#     before.
+#     All plotting methods (e.g. :meth:`pygmt.Figure.coast`, :meth:`pygmt.Figure.text`,
+#     etc) are able to use ``panel`` parameter when in subplot mode. Once a panel is
+#     activated using ``panel`` or :meth:`pygmt.Figure.set_panel`, subsequent plotting
+#     commands that don't set a ``panel`` will have their elements added to the same
+#     panel as before.
 
 
 # %%
 # Shared x- and y-axes
 # --------------------
 #
-# In the example above with the four subplots, the two subplots for each row
-# have the same y-axis range, and the two subplots for each column have the
-# same x-axis range. You can use the ``sharex``/``sharey`` parameters to set a
-# common x- and/or y-axis between subplots.
+# In the example above with the four subplots, the two subplots for each row have the
+# same y-axis range, and the two subplots for each column have the same x-axis range.
+# You can use the ``sharex``/``sharey`` parameters to set a common x- and/or y-axis
+# between subplots.
 
 fig = pygmt.Figure()
 with fig.subplot(
@@ -182,25 +178,24 @@
 fig.show()
 
 # %%
-# ``sharex="b"`` indicates that subplots in a column will share the x-axis, and
-# only the **b**\ ottom axis is displayed. ``sharey="l"`` indicates that
-# subplots within a row will share the y-axis, and only the **l**\ eft axis is
-# displayed.
+# ``sharex="b"`` indicates that subplots in a column will share the x-axis, and only the
+# **b**\ ottom axis is displayed. ``sharey="l"`` indicates that subplots within a row
+# will share the y-axis, and only the **l**\ eft axis is displayed.
 #
-# Of course, instead of using the ``sharex``/``sharey`` parameters, you can
-# also set a different ``frame`` for each subplot to control the axis
-# properties individually for each subplot.
+# Of course, instead of using the ``sharex``/``sharey`` parameters, you can also set a
+# different ``frame`` for each subplot to control the axis properties individually for
+# each subplot.
 
 
 # %%
 # Advanced subplot layouts
 # ------------------------
 #
-# Nested subplots are currently not supported. If you want to create more
-# complex subplot layouts, some manual adjustments are needed.
+# Nested subplots are currently not supported. If you want to create more complex
+# subplot layouts, some manual adjustments are needed.
 #
-# The following example draws three subplots in a 2-row, 2-column layout, with
-# the first subplot occupying the first row.
+# The following example draws three subplots in a 2-row, 2-column layout, with the first
+# subplot occupying the first row.
 
 fig = pygmt.Figure()
 # Bottom row, two subplots
@@ -223,20 +218,19 @@
 fig.show()
 
 # %%
-# We start by drawing the bottom two subplots, setting ``tag="b)"`` so
-# that the subplots are tagged 'b)' and 'c)'. Next, we use
-# :meth:`pygmt.Figure.shift_origin` to move the plot origin 1 cm above the
-# **h**\ eight of the entire figure that is currently plotted (i.e. the bottom
-# row subplots). A single subplot is then plotted on the top row. You may need
-# to adjust the ``yshift`` parameter to make your plot look nice. This top row
-# uses ``tag="a)"``, and we also plotted some text inside. Note that
-# ``projection="X?"`` was used to let GMT automatically determine the size of
-# the subplot according to the size of the subplot area.
+# We start by drawing the bottom two subplots, setting ``tag="b)"`` so that the subplots
+# are tagged 'b)' and 'c)'. Next, we use :meth:`pygmt.Figure.shift_origin` to move the
+# plot origin 1 cm above the **h**\ eight of the entire figure that is currently plotted
+# (i.e. the bottom row subplots). A single subplot is then plotted on the top row. You
+# may need to adjust the ``yshift`` parameter to make your plot look nice. This top row
+# uses ``tag="a)"``, and we also plotted some text inside. Note that ``projection="X?"``
+# was used to let GMT automatically determine the size of the subplot according to the
+# size of the subplot area.
 
 # %%
-# You can also manually override the ``tag`` for each subplot using for
-# example, ``fig.set_panel(..., fixedlabel="b) Panel 2")`` which would allow
-# you to manually tag a single subplot as you wish. This can be useful for
-# adding a more descriptive subtitle to individual subplots.
+# You can also manually override the ``tag`` for each subplot using for example,
+# ``fig.set_panel(..., fixedlabel="b) Panel 2")`` which would allow you to manually tag
+# a single subplot as you wish. This can be useful for adding a more descriptive
+# subtitle to individual subplots.
 
 # sphinx_gallery_thumbnail_number = 3