From a795a64e87d952bf593507b3742f9d8b86ad0dd8 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 20 Dec 2025 20:42:25 +0800 Subject: [PATCH] Figure.subplot: Pythonic implemention for the subplot tagging --- pygmt/src/subplot.py | 108 ++++++++++++++++++++++++++++++------------- 1 file changed, 76 insertions(+), 32 deletions(-) diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py index f1a610bbc27..22144f61ef6 100644 --- a/pygmt/src/subplot.py +++ b/pygmt/src/subplot.py @@ -6,15 +6,12 @@ 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.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias +from pygmt.params import Box @fmt_docstring @@ -29,10 +26,17 @@ T="title", ) @kwargs_to_strings(Ff="sequence", Fs="sequence") -def subplot( +def subplot( # noqa: PLR0913 self, nrows=1, ncols=1, + autotag: str | bool = False, + tag_box: Box | None = None, + tag_offset: float | str | Sequence[float | str] | None = None, + tag_position: AnchorCode | None = None, + tag_orientation: Literal["horizontal", "vertical"] | None = None, + tag_number_style: Literal["arabic", "roman", "Roman"] | None = None, + tag_font: str | None = None, margins: float | str | Sequence[float | str] | None = None, projection: str | None = None, frame: str | Sequence[str] | bool = False, @@ -71,31 +75,48 @@ 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. + 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_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:** - 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]. + - The property ``clearance`` cannot be four values. + - The property ``inner_pen``/``inner_gap``/``radius`` is not supported. + tag_position + Position of the subplot tag. It can be specified using a + :doc:`2-character justification code `. If not + specified, defaults to ``"TL"`` (Top Left corner). + tag_offset + Offset of the subplot tag in the direction implied by the justification. It can + be a single value or a sequence of two values specifying the x- and y-offsets. + [Default to ``"4p/4p"``, i.e., 20 % of the :gmt-term:`FONT_TAG` size]. + 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_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_font + Font for the subplot tag. [Default to ``"20p,Helvetica,black"``]. $frame clearance : str or list [*side*]\ *clearance*. @@ -174,6 +195,22 @@ def subplot( raise GMTInvalidInput(msg) aliasdict = AliasSystem( + A=[ + Alias(autotag, name="autotag"), + Alias(tag_box, name="tag_box"), + Alias(tag_offset, name="tag_offset", prefix="+o", sep="/", size=2), + Alias(tag_position, name="tag_position", prefix="+j"), + Alias( + tag_orientation, + name="tag_orientation", + mapping={"horizontal": "", "vertical": "+v"}, + ), + Alias( + tag_number_style, + name="tag_number_style", + mapping={"arabic": "", "roman": "+r", "Roman": "+R"}, + ), + ], M=Alias(margins, name="margins", sep="/", size=(2, 4)), ).add_common( B=frame, @@ -183,6 +220,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. @@ -191,7 +231,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: