From a8926332941a5b2645d347c3c2c9db4d47201538 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 7 Feb 2026 21:39:20 +0800
Subject: [PATCH] Figure.set_panel: Deprecate parameter 'fixedlabel' to 'tag'
 (Will be removed in v0.23.0)

---
 examples/tutorials/advanced/subplots.py |  6 +++---
 pygmt/src/subplot.py                    | 28 ++++++++++++++-----------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/examples/tutorials/advanced/subplots.py b/examples/tutorials/advanced/subplots.py
index 5261b7faf7a..ef3641355a8 100644
--- a/examples/tutorials/advanced/subplots.py
+++ b/examples/tutorials/advanced/subplots.py
@@ -229,8 +229,8 @@
 
 # %%
 # 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.
+# ``fig.set_panel(..., tag="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
diff --git a/pygmt/src/subplot.py b/pygmt/src/subplot.py
index 6a291dacfa1..42bafe68def 100644
--- a/pygmt/src/subplot.py
+++ b/pygmt/src/subplot.py
@@ -10,7 +10,13 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTParameterError, GMTValueError
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import (
+    build_arg_list,
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 from pygmt.params import Box, Position
 from pygmt.src._common import _parse_position
 
@@ -352,10 +358,12 @@ def subplot(  # noqa: PLR0913
 
 @fmt_docstring
 @contextlib.contextmanager
-@use_alias(A="fixedlabel", C="clearance")
+@deprecate_parameter("fixedlabel", "tag", "v0.19.0", remove_version="v0.23.0")
+@use_alias(C="clearance")
 def set_panel(
     self,
     panel: int | Sequence[int] | None = None,
+    tag: str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -372,6 +380,7 @@ def set_panel(
     ``projection="X"`` will fill the subplot by using unequal scales].
 
     $aliases
+       - A = tag
        - V = verbose
 
     Parameters
@@ -386,13 +395,10 @@ def set_panel(
         GMT maintains information about the current figure and subplot. Also, you may
         give the one-dimensional *index* instead which starts at 0 and follows the row
         or column order set via ``autolabel`` in :meth:`pygmt.Figure.subplot`.
-
-    fixedlabel : str
-        Overrides the automatic labeling with the given string. No modifiers
-        are allowed. Placement, justification, etc. are all inherited from how
-        ``autolabel`` was specified by the initial :meth:`pygmt.Figure.subplot`
-        command.
-
+    tag
+        Tag for the current subplot. It overrides the automatic tag set by the
+        :meth:`pygmt.Figure.subplot` method. Use ``tag="-"`` to skip the tag for this
+        panel.
     clearance : str or list
         [*side*]\ *clearance*.
         Reserve a space of dimension *clearance* between the margin and the
@@ -409,9 +415,7 @@ def set_panel(
     """
     self._activate_figure()
 
-    aliasdict = AliasSystem().add_common(
-        V=verbose,
-    )
+    aliasdict = AliasSystem(A=Alias(tag, name="tag")).add_common(V=verbose)
     aliasdict.merge(kwargs)
 
     with Session() as lib: