Merge branch 'main' into AliasSystem/alias

Author: seisman

doc/techref/index.md

@@ -11,6 +11,7 @@ visit the {gmt-docs}`GMT Technical Reference <reference.html>`.
 common_parameters.md
 projections.md
 fonts.md
+text_formatting.md
 patterns.md
 encodings.md
 environment_variables.md

doc/techref/text_formatting.md

@@ -0,0 +1,29 @@
+# Text Formatting
+
+The table below shows how text added to a plot, such as text strings added via
+`Figure.text`, plot title, labels of Cartesian axes and colorbars, and legend entries.
+Changing the font as well as its color and size in this way allows to change those
+only for specific characters of a longer text. The supported fonts are listed at
+[](/techref/fonts.md).
+
+| Symbol | Behavior |
+| --- | --- |
+| @%*font*%*TEXT*@%%  | Change the *font* of *TEXT* |
+| @;*color*;*TEXT*@;; | Change the font *color* of *TEXT* |
+| @:*size*:*TEXT*@::  | Change the font *size* of *TEXT* |
+| @-*TEXT*@-          | Toggle subscripts on/off |
+| @+*TEXT*@+          | Toggle superscript on/off |
+| @#*TEXT*@#          | Toggle small caps on/off |
+| @\_*TEXT*@\_        | Toggle underline on/off |
+| @!*CHAR1CHAR2*      | Print two characters on top of each other (composite characters, e.g., overstrike) |
+| @\~*TEXT*@\~        | Toggle Greek letters on/off |
+| @@                  | Print the @ sign |
+| @.                  | Print the ° (degree) symbol |
+| @s                  | Print letter ß |
+| @i                  | Print letter í |
+| @a or @A            | Print letter å or Å |
+| @c or @C            | Print letter ç or Ç |
+| @e or @E            | Print letter æ or Æ |
+| @n or @N            | Print letter ñ or Ñ |
+| @o or @O            | Print letter ø or Ø |
+| @u or @U            | Print letter ü or Ü |

examples/gallery/embellishments/text_formatting.py

@@ -0,0 +1,41 @@
+"""
+Text formatting
+===============
+
+There are various options for formatting text contained in a plot, e.g., text added via
+:meth:`pygmt.Figure.text`, the plot title, labels of colorbars as well as Cartesian
+axes, and legend entries. It's also possible to change the font as well as its color
+and size only for specific characters of a longer text. The supported fonts are listed
+at :doc:`Supported Fonts </techref/fonts>`. For an complete overview see
+:doc:`Text Formatting </techref/text_formatting>`.
+"""
+
+# %%
+import pygmt
+
+fig = pygmt.Figure()
+fig.basemap(region=[-1, 1, -4, 4], projection="X4c/5c", frame=0)
+
+# Change font color for specific letters of the word "PyGMT":
+# blue for "P", yellow for "y", and red for "GMT"
+fig.text(x=0, y=3, text="@;63/124/173;P@;;@;255/212/59;y@;;@;238/86/52;GMT@;;")
+
+# Change font size and style for one single character, respectively
+fig.text(x=0, y=2, text="te@:15:x@::t     tex@%Courier-Oblique%t@%%")
+
+# Use superscript
+fig.text(x=0, y=1, text="E = mc@+2@+")
+
+# Use subscripts and Greek letters
+fig.text(x=0, y=0, text="@~s@~@-ij@- = c@-ijkl@- @~e@~@-kl@-")
+
+# Combine two characters above each other
+fig.text(x=0, y=-1, text="@!_~")
+
+# Underline the text
+fig.text(x=0, y=-2, text="This is @_underlined@_ text")
+
+# Use small caps
+fig.text(x=0, y=-3, text="T@#ext@# in S@#mall@# C@#aps@#")
+
+fig.show()

examples/gallery/maps/country_polygons.py

@@ -2,11 +2,12 @@
 Highlight country, continent and state polygons
 ===============================================
 
-The :meth:`pygmt.Figure.coast` method can highlight country polygons
-via the ``dcw`` parameter. It accepts the country code or full
-country name and can draw its borders and add a color to its landmass.
-It's also possible to define multiple countries at once by separating
-the individual names with commas.
+The :meth:`pygmt.Figure.coast` method can highlight country polygons via the ``dcw``
+parameter. It accepts the country code (following the 2-letter
+`ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_) or
+full country name and can draw its borders and add a color to its landmass. It's also
+possible to define multiple countries at once by separating the individual names with
+commas.
 """
 
 # %%

pygmt/clib/conversion.py

@@ -12,7 +12,7 @@
 import pandas as pd
 import xarray as xr
 from packaging.version import Version
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTValueError
 
 
 def dataarray_to_matrix(
@@ -49,7 +49,7 @@ def dataarray_to_matrix(
 
     Raises
     ------
-    GMTInvalidInput
+    GMTValueError
         If the grid has more than two dimensions or variable grid spacing.
 
     Examples
@@ -92,8 +92,11 @@ def dataarray_to_matrix(
     [2.0, 2.0]
     """
     if len(grid.dims) != 2:
-        msg = f"Invalid number of grid dimensions 'len({grid.dims})'. Must be 2."
-        raise GMTInvalidInput(msg)
+        raise GMTValueError(
+            len(grid.dims),
+            description="number of grid dimensions",
+            reason="The grid must be 2-D.",
+        )
 
     # Extract region and inc from the grid
     region, inc = [], []
@@ -113,8 +116,11 @@ def dataarray_to_matrix(
             )
             warnings.warn(msg, category=RuntimeWarning, stacklevel=2)
         if coord_inc == 0:
-            msg = f"Grid has a zero increment in the '{dim}' dimension."
-            raise GMTInvalidInput(msg)
+            raise GMTValueError(
+                coord_inc,
+                description="grid increment",
+                reason=f"Grid has a zero increment in the '{dim}' dimension.",
+            )
         region.extend(
             [
                 coord.min() - coord_inc / 2 * grid.gmt.registration,

pygmt/clib/session.py

@@ -913,9 +913,10 @@ def _check_dtype_and_dim(self, array: np.ndarray, ndim: int) -> int:
 
         Raises
         ------
+        GMTValueError
+            If the array has the wrong number of dimensions.
         GMTInvalidInput
-            If the array has the wrong number of dimensions or is an unsupported data
-            type.
+            If the array is an unsupported data type.
 
         Examples
         --------
@@ -933,8 +934,11 @@ def _check_dtype_and_dim(self, array: np.ndarray, ndim: int) -> int:
         """
         # Check that the array has the given number of dimensions.
         if array.ndim != ndim:
-            msg = f"Expected a numpy {ndim}-D array, got {array.ndim}-D."
-            raise GMTInvalidInput(msg)
+            raise GMTValueError(
+                array.ndim,
+                description="array dimension",
+                reason=f"Expected a numpy {ndim}-D array, got {array.ndim}-D.",
+            )
 
         # 1-D arrays can be numeric or text, 2-D arrays can only be numeric.
         valid_dtypes = DTYPES if ndim == 1 else DTYPES_NUMERIC

pygmt/helpers/utils.py

@@ -18,7 +18,7 @@
 import xarray as xr
 from pygmt._typing import PathLike
 from pygmt.encodings import charset
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 
 # Type hints for the list of encodings supported by PyGMT.
 Encoding = Literal[
@@ -597,8 +597,7 @@ def build_arg_list(  # noqa: PLR0912
             or os.fspath(outfile) in {"", ".", ".."}
             or os.fspath(outfile).endswith(("/", "\\"))
         ):
-            msg = f"Invalid output file name '{outfile}'."
-            raise GMTInvalidInput(msg)
+            raise GMTValueError(outfile, description="output file name")
         gmt_args.append(f"->{os.fspath(outfile)}")
     return gmt_args
 

pygmt/helpers/validators.py

@@ -6,7 +6,7 @@
 from typing import Literal
 
 from pygmt._typing import PathLike
-from pygmt.exceptions import GMTInvalidInput
+from pygmt.exceptions import GMTInvalidInput, GMTValueError
 
 
 def validate_output_table_type(
@@ -39,7 +39,7 @@ def validate_output_table_type(
     >>> validate_output_table_type(output_type="invalid-type")
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Must specify 'output_type' either as 'file', ...
+    pygmt....GMTValueError: ...: 'invalid-type'. Expected one of: ...
     >>> validate_output_table_type("file", outfile=None)
     Traceback (most recent call last):
         ...
@@ -49,9 +49,13 @@ def validate_output_table_type(
     ...     assert len(w) == 1
     'file'
     """
-    if output_type not in {"file", "numpy", "pandas"}:
-        msg = "Must specify 'output_type' either as 'file', 'numpy', or 'pandas'."
-        raise GMTInvalidInput(msg)
+    _valids = {"file", "numpy", "pandas"}
+    if output_type not in _valids:
+        raise GMTValueError(
+            output_type,
+            description="value for parameter 'output_type'",
+            choices=_valids,
+        )
     if output_type == "file" and outfile is None:
         msg = "Must specify 'outfile' for output_type='file'."
         raise GMTInvalidInput(msg)

pygmt/src/_common.py

@@ -7,7 +7,7 @@
 from pathlib import Path
 from typing import Any, ClassVar, Literal
 
-from pygmt.exceptions import GMTInvalidInput, GMTValueError
+from pygmt.exceptions import GMTValueError
 from pygmt.src.which import which
 
 
@@ -125,7 +125,7 @@ class _FocalMechanismConvention:
     >>> _FocalMechanismConvention.from_params(["strike", "dip", "rake"])
     Traceback (most recent call last):
         ...
-    pygmt.exceptions.GMTInvalidInput: Fail to determine focal mechanism convention...
+    pygmt.exceptions.GMTValueError: Invalid focal mechanism parameters: ...
     """
 
     # Mapping of focal mechanism conventions to their parameters.
@@ -236,18 +236,14 @@ def from_params(
 
         Raises
         ------
-        GMTInvalidInput
+        GMTValueError
             If the focal mechanism convention cannot be determined from the given
             parameters.
         """
         for convention, param_list in cls._params.items():
             if set(param_list).issubset(set(params)):
                 return cls(convention, component=component)
-        msg = (
-            "Fail to determine focal mechanism convention from the given parameters: "
-            f"{', '.join(params)}."
-        )
-        raise GMTInvalidInput(msg)
+        raise GMTValueError(params, description="focal mechanism parameters")
 
 
 def _parse_coastline_resolution(

pygmt/src/coast.py

@@ -168,7 +168,7 @@ def coast(
         *code1,code2,…*\ [**+g**\ *fill*\ ][**+p**\ *pen*\ ][**+z**].
         Select painting country polygons from the `Digital Chart of the World
         <https://en.wikipedia.org/wiki/Digital_Chart_of_the_World>`__.
-        Append one or more comma-separated countries using the 2-character
+        Append one or more comma-separated countries using the 2-letter
         `ISO 3166-1 alpha-2 convention
         <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__.
         To select a state of a country (if available), append .\ *state*,