Merge branch 'main' into class/frame-part1

Author: seisman

examples/gallery/embellishments/scalebar.py

@@ -1,109 +1,84 @@
-r"""
+"""
 Scale bar
 =========
 
-The ``map_scale`` parameter of the :meth:`pygmt.Figure.basemap` and
-:meth:`pygmt.Figure.coast` methods is used to add a scale bar to a map.
-This example shows how such a scale bar can be customized:
-
- - position: **g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**. Set the position
-   of the reference point. Choose from
-
-   - **g**: Give map coordinates as *longitude*\/\ *latitude*.
-   - **j**\|\ **J**: Specify a
-     :doc:`2-character justification code </techref/justification_codes>`.
-     Lower / uppercase **j** / **J** mean inside / outside of the map
-     bounding box.
-   - **n**: Give normalized bounding box coordinates as *nx*\/\ *ny*.
-   - **x**: Give plot coordinates as *x*\/\ *y*.
-
- - length: **+w**. Give a distance value, and, optionally a distance unit.
-   Choose from **e** (meters), **f** (feet), **k** (kilometers) [Default],
-   **M** (statute miles), **n** (nautical miles), or **u** (US survey feet).
- - origin: **+c**\ [*slon*/]\ *slat*. Control where on the map the scale bar
-   applies. If **+c** is not given the reference point is used. If only
-   **+c** is appended the middle of the map is used. Note that *slon* is only
-   optional for projections with constant scale along parallels, e.g.,
-   Mercator projection.
- - justify: **+j**. Set the anchor point. Specify a
-   :doc:`2-character justification code </techref/justification_codes>`.
- - offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*. Give either a
-   common shift or individual shifts in x- (longitude) and y- (latitude)
-   directions.
- - height: Use :gmt-term:`MAP_SCALE_HEIGHT` via :func:`pygmt.config`.
- - fancy style: **+f**. Get a scale bar that looks like train tracks.
- - unit: **+u**. Add the distance unit given via **+w** to the single
-   distance values.
- - label: **+l**. Add the distance unit given via **+w** as label. Append
-   text to get a customized label instead.
- - alignment: **+a**. Set the label alignment. Choose from **t**\(op)
-   [Default], **b**\(ottom), **l**\(eft), or **r**\(ight).
+The :meth:`pygmt.Figure.scalebar` method can be used to add a scale bar to a map. This
+example shows how such a scale bar can be customized.
 """
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 # Create a new Figure instance
 fig = pygmt.Figure()
 
 # Mercator projection with 10 centimeters width
 fig.basemap(region=[-45, -25, -15, 0], projection="M0/0/10c", frame=["WSne", "af"])
 
-# -----------------------------------------------------------------------------
-# Top Left: Add a plain scale bar
-# It is placed based on geographic coordinates (g) 42° West and 1° South,
-# applies at the reference point (+c is not given), and represents a
-# length (+w) of 500 kilometers
-fig.basemap(map_scale="g-42/-1+w500k")
-
-# -----------------------------------------------------------------------------
-# Top Right: Add a fancy scale bar
-# It is placed based on normalized bounding box coordinates (n)
-# Use a fancy style (+f) to get a scale bar that looks like train tracks
-# Add the distance unit (+u) to the single distance values
-fig.basemap(map_scale="n0.8/0.95+w500k+f+u")
+# --- Top Left: Add a plain scale bar ---
+# It is placed based on geographic coordinates 42° West and 1° South, applies at the
+# reference point by default, and represents a length of 500 kilometers.
+fig.scalebar(length="500k", position=Position((-42, -1), cstype="mapcoords"))
+
+# --- Top Right: Add a fancy scale bar ---
+# It is placed based on normalized bounding box coordinates. Use a fancy style to get a
+# scale bar that looks like train tracks. Add the distance unit to the single distance
+# values.
+fig.scalebar(
+    position=Position((0.8, 0.95), cstype="boxcoords"),
+    length="500k",
+    fancy=True,
+    unit=True,
+)
 
-# -----------------------------------------------------------------------------
-# Bottom Left: Add a thick scale bar
-# Adjust the GMT default parameter MAP_SCALE_HEIGHT locally (the change applies
-# only to the code within the "with" statement)
-# It applies (+c) at the middle of the map (no location is appended to +c)
-# Without appending text, +l adds the distance unit as label
-with pygmt.config(MAP_SCALE_HEIGHT="10p"):
-    fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l")
+# --- Bottom Left: Add a thick scale bar ---
+# It applies at the middle of the map (scale_loc is set to True). Use the height
+# parameter to adjust the thickness of the scale bar Without providing text, the label
+# parameter adds the distance unit as label.
+fig.scalebar(
+    position=Position((0.2, 0.15), cstype="boxcoords"),
+    scale_loc=True,
+    length="500k",
+    height="10p",
+    fancy=True,
+    label=True,
+)
 
-# -----------------------------------------------------------------------------
-# Bottom Right: Add a scale bar valid for a specific location
-# It is placed at BottomRight (j) using MiddleRight as anchor point (+j) with
-# an offset (+o) of 1 centimeter in both x- and y-directions
-# It applies (+c) at -7° South, add a customized label by appending text to +l
-fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S")
+# --- Bottom Right: Add a scale bar valid for a specific location ---
+# It is placed at BottomRight using MiddleRight as anchor point with an offset of 1
+# centimeter in both x- and y-directions. It applies at -7° South. A customized label
+# is added via the label parameter.
+fig.scalebar(
+    position=Position("BR", anchor="MR", offset=1),
+    scale_loc=-7,
+    length="500k",
+    fancy=True,
+    unit=True,
+    label="valid at 7° S",
+)
 
 fig.show()
 
 
 # %%
-# The ``box`` parameter allows surrounding the scale bar. This can be useful
-# when adding a scale bar to a colorful map. To fill the box, append **+g**
-# with the desired color (or pattern). The outline of the box can be adjusted
-# by appending **+p** with the desired thickness, color, and style. To force
-# rounded edges append **+r** with the desired radius.
+# The ``box`` parameter allows surrounding the scale bar. This can be useful when adding
+# a scale bar to a colorful map to improve contrast and readability.
 
-# Create a new Figure instance
 fig = pygmt.Figure()
 
-fig.coast(
-    region=[-45, -25, -15, 0],
-    projection="M10c",
-    land="tan",
-    water="steelblue",
-    frame=["WSne", "af"],
-    # Set the label alignment (+a) to right (r)
-    map_scale="jBL+o1c/1c+c-7+w500k+f+lkm+ar",
-    # Fill the box in white with a transparency of 30 percent, add a solid
-    # outline in darkgray (gray30) with a thickness of 0.5 points, and use
-    # rounded edges with a radius of 3 points
+fig.basemap(region=[-45, -25, -15, 0], projection="M10c", frame=["WSne", "af"])
+fig.coast(land="tan", water="steelblue")
+fig.scalebar(
+    position=Position("BL", cstype="inside", offset=1),
+    scale_loc=-7,
+    length="500k",
+    fancy=True,
+    label="km",
+    label_alignment="right",
+    # Fill the box in white with a transparency of 30 percent, add a solid outline in
+    # darkgray (gray30) with a thickness of 0.5 points, and use rounded edges with a
+    # radius of 3 points
     box=Box(fill="white@30", pen="0.5p,gray30,solid", radius="3p"),
 )
 

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

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,13 @@ def subplot(  # noqa: PLR0913
 
 @fmt_docstring
 @contextlib.contextmanager
-@use_alias(A="fixedlabel", C="clearance")
+# TODO(PyGMT>=0.23.0): Remove the deprecated 'fixedlabel' parameter.
+@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 +381,7 @@ def set_panel(
     ``projection="X"`` will fill the subplot by using unequal scales].
 
     $aliases
+       - A = tag
        - V = verbose
 
     Parameters
@@ -386,13 +396,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 +416,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: