From 9087c6e4eb791b0434c1e25ed89b1937637230b3 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 20 Dec 2025 20:42:25 +0800 Subject: [PATCH 1/7] 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 ` - 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 ` 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 Date: Sat, 20 Dec 2025 20:42:25 +0800 Subject: [PATCH 2/7] 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 ` - 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 ` 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 Date: Fri, 30 Jan 2026 17:53:36 +0800 Subject: [PATCH 3/7] 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 Date: Fri, 30 Jan 2026 18:10:07 +0800 Subject: [PATCH 4/7] 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 Date: Fri, 30 Jan 2026 18:37:35 +0800 Subject: [PATCH 5/7] 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 Date: Fri, 30 Jan 2026 18:45:56 +0800 Subject: [PATCH 6/7] 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 Date: Fri, 30 Jan 2026 19:10:47 +0800 Subject: [PATCH 7/7] 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