Merge branch 'main' into refactor/data_kind

Author: seisman

.github/workflows/ci_tests_dev.yaml

@@ -36,7 +36,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-24.04, macos-14, windows-2022]
+        os: [ubuntu-24.04, macos-15, windows-2022]
         gmt_git_ref: [master]
     timeout-minutes: 30
     defaults:

doc/_templates/footer.html

@@ -3,7 +3,7 @@
 
 {%- block extrafooter %}
 <p>
-Built with <a href="https://sphinx-doc.org/">Sphinx</a>
+Built with <a href="https://www.sphinx-doc.org/">Sphinx</a>
 using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a>
 provided by <a href="https://readthedocs.org">Read the Docs</a>
 </p>

doc/techref/index.md

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

doc/techref/patterns.md

@@ -0,0 +1,25 @@
+# Bit and hachure patterns
+
+PyGMT supports a variety of bit and hachure patterns that can be used to fill polygons.
+
+These patterns can be defined using the following syntax:
+
+**P**|**p**_pattern_[**+b**_color_][**+f**_color_][**+r**_dpi_]
+
+*pattern* can either be a number in the range 1-90 or the name of a 1-, 8-, or 24-bit
+image raster file. The former will result in one of the 90 predefined 64x64 bit-patterns
+provided by GMT (see the figure below). The latter allows the user to create customized,
+repeating images using image raster files.
+
+By specifying upper case **P** instead of **p** the image will be bit-reversed, i.e.,
+white and black areas will be interchanged (only applies to 1-bit images or predefined
+bit-image patterns). For these patterns and other 1-bit images one may specify
+alternative **b**ackground and **f**oreground colors (by appending **+b**_color_ and/or
+**+f**_color_) that will replace the default white and black pixels, respectively.
+Excluding *color* from a fore- or background specification yields a transparent image
+where only the back- or foreground pixels will be painted. The **+r**_dpi_ modifier sets
+the resolution in dpi.
+
+The image below shows the 90 predefined bit patterns that can be used in PyGMT.
+
+![](https://docs.generic-mapping-tools.org/6.5/_images/GMT_App_E.png)

examples/gallery/symbols/patterns.py

@@ -1,67 +1,44 @@
-r"""
+"""
 Bit and hachure patterns
 ========================
 
-PyGMT allows using bit or hachure patterns via the ``fill`` parameter
-or similar parameters:
+In addition to colors, PyGMT also allows using bit and hachure patterns to fill
+symbols, polygons, and other areas, via the ``fill`` parameter or similar parameters.
+
+Example method parameters that support bit and hachure patterns include:
 
-- :meth:`pygmt.Figure.coast`: Land and water masses via ``land`` and
-  ``water``, respectively
+- :meth:`pygmt.Figure.coast`: Land and water masses via ``land`` and ``water``
 - :meth:`pygmt.Figure.histogram`: Histogram bars via ``fill``
-- :meth:`pygmt.Figure.meca`: Focal mechanisms via ``compressionfill``
-  and ``extensionfill``
+- :meth:`pygmt.Figure.meca`: Focal mechanisms via ``compressionfill`` and
+  ``extensionfill``
 - :meth:`pygmt.Figure.plot`: Symbols and polygons via ``fill``
 - :meth:`pygmt.Figure.rose`: Histogram sectors via ``fill``
 - :meth:`pygmt.Figure.solar`: Day-light terminators via ``fill``
 - :meth:`pygmt.Figure.ternary`: Symbols via ``fill``
-- :meth:`pygmt.Figure.velo`: Uncertainty wedges and velocity error
-  ellipses via ``uncertaintyfill``
-- :meth:`pygmt.Figure.wiggle`: Anomalies via ``fillpositive``
-  and ``fillnegative``
-
-The required argument has the following form:
+- :meth:`pygmt.Figure.velo`: Uncertainty wedges and velocity error ellipses via
+  ``uncertaintyfill``
+- :meth:`pygmt.Figure.wiggle`: Anomalies via ``fillpositive`` and ``fillnegative``
 
-**P**\|\ **p**\ *pattern*\ [**+b**\ *color*][**+f**\ *color*][**+r**\ *dpi*]
-
-*pattern* can either be a number in the range 1-90 or the name of a
-1-, 8-, or 24-bit image raster file. The former will result in one of the 90
-predefined 64 x 64 bit-patterns provided by GMT; an overview can by found at
-:gmt-docs:`reference/predefined-patterns.html`.
-The latter allows the user to create customized, repeating images using image
-raster files.
-By specifying upper case **P** instead of **p** the image will be
-bit-reversed, i.e., white and black areas will be interchanged (only applies
-to 1-bit images or predefined bit-image patterns).
-For these patterns and other 1-bit images one may specify alternative
-**b**\ ackground and **f**\ oreground colors (by appending **+b**\ *color*
-and/or **+f**\ *color*) that will replace the default white and black pixels,
-respectively. Excluding *color* from a fore- or background specification yields
-a transparent image where only the back- or foreground pixels will be painted.
-The **+r**\ *dpi* modifier sets the resolution in dpi.
+GMT provides 90 predefined patterns that can be used in PyGMT. The patterns are numbered
+from 1 to 90, and can be colored and inverted. The resolution of the pattern
+can be changed, and the background and foreground colors can be set. For a complete list
+of available patterns and the full syntax to specify a pattern, refer to the
+:doc:`/techref/patterns`.
 """
 
 # %%
 import pygmt
 
-y = 11
-
-fig = pygmt.Figure()
-fig.basemap(
-    region=[0, 10, 0, 12],
-    projection="X10c",
-    frame="rlbt+glightgray+tBit and Hachure Patterns",
-)
-
-# To use a pattern as fill append "p" and the number of the desired
-# pattern. By default, the pattern is plotted in black and white
-# with a resolution of 300 dpi
-for pattern in [
+# A list of patterns that will be demonstrated.
+# To use a pattern as fill append "p" and the number of the desired pattern.
+# By default, the pattern is plotted in black and white with a resolution of 300 dpi.
+patterns = [
     # Plot a hachted pattern via pattern number 8
     "p8",
     # Plot a dotted pattern via pattern number 19
     "p19",
-    # Set the background color ("+b") to "red3"
-    # and the foreground color ("+f") to "lightgray"
+    # Set the background color ("+b") to "red3" and the foreground color ("+f") to
+    # "lightgray"
     "p19+bred3+flightbrown",
     # Invert the pattern by using a capitalized "P"
     "P19+bred3+flightbrown",
@@ -70,23 +47,21 @@
     # Make the background transparent by not giving a color after "+b";
     # works analogous for the foreground
     "p19+b+flightbrown+r100",
-]:
-    # Plot a square with the pattern as fill
-    fig.plot(
-        x=2,
-        y=y,
-        style="s2c",  # square with a width of 2 centimeters
-        pen="1p,black",  # 1 point thick, black outline
-        fill=pattern,
-    )
-    # Add a description of the pattern
-    fig.text(
-        x=4,
-        y=y,
-        text=pattern,
-        font="Courier-Bold",
-        justify="ML",  # justification of the text is Middle Left
-    )
-    y -= 2
+]
 
+fig = pygmt.Figure()
+fig.basemap(
+    region=[0, 10, 0, 12],
+    projection="X10c",
+    frame="rlbt+glightgray+tBit and Hachure Patterns",
+)
+
+y = 11
+for pattern in patterns:
+    # Plot a square with the pattern as fill.
+    # The square has a size of 2 centimeters with a 1 point thick, black outline.
+    fig.plot(x=2, y=y, style="s2c", pen="1p,black", fill=pattern)
+    # Add a description of the pattern.
+    fig.text(x=4, y=y, text=pattern, font="Courier-Bold", justify="ML")
+    y -= 2
 fig.show()

pygmt/accessors.py

@@ -2,6 +2,7 @@
 GMT accessor for :class:`xarray.DataArray`.
 """
 
+import contextlib
 from pathlib import Path
 
 import xarray as xr
@@ -115,22 +116,17 @@ class GMTDataArrayAccessor:
 
     def __init__(self, xarray_obj):
         self._obj = xarray_obj
-
-        self._source = self._obj.encoding.get("source")
-        if self._source is not None and Path(self._source).exists():
-            try:
-                # Get grid registration and grid type from the last two columns
-                # of the shortened summary information of `grdinfo`.
+        # Default to Gridline registration and Cartesian grid type
+        self._registration = 0
+        self._gtype = 0
+
+        # If the source file exists, get grid registration and grid type from the last
+        # two columns of the shortened summary information of grdinfo.
+        if (_source := self._obj.encoding.get("source")) and Path(_source).exists():
+            with contextlib.suppress(ValueError):
                 self._registration, self._gtype = map(
-                    int, grdinfo(self._source, per_column="n").split()[-2:]
+                    int, grdinfo(_source, per_column="n").split()[-2:]
                 )
-            except ValueError:
-                self._registration = 0  # Default to Gridline registration
-                self._gtype = 0  # Default to Cartesian grid type
-        else:
-            self._registration = 0  # Default to Gridline registration
-            self._gtype = 0  # Default to Cartesian grid type
-        del self._source
 
     @property
     def registration(self):

pygmt/helpers/utils.py

@@ -188,17 +188,18 @@ def _check_encoding(
     return "ISOLatin1+"
 
 
-def data_kind(  # noqa: PLR0911
+def data_kind(
     data: Any, required: bool = True
 ) -> Literal[
     "arg", "file", "geojson", "grid", "image", "matrix", "stringio", "vectors"
 ]:
     r"""
     Check the kind of data that is provided to a module.
 
-    The ``data`` argument can be in any types. Following data kinds are recognized:
+    The argument passed to the ``data`` parameter can have any data type. The
+    following data kinds are recognized and returned as ``kind``:
 
-    - ``"arg"``: data is ``None`` and ``required=False``, or bool, int, float,
+    - ``"arg"``: ``data`` is ``None`` and ``required=False``, or bool, int, float,
       representing an optional argument, used for dealing with optional virtual files
     - ``"file"``: a string or a :class:`pathlib.PurePath` object or a sequence of them,
       representing one or more file names
@@ -294,36 +295,31 @@ def data_kind(  # noqa: PLR0911
     >>> data_kind(data=None)
     'vectors'
     """
-    # One file or a list/tuple of files.
-    if isinstance(data, str | pathlib.PurePath) or (
-        isinstance(data, list | tuple)
-        and all(isinstance(_file, str | pathlib.PurePath) for _file in data)
-    ):
-        return "file"
-
-    # A StringIO object.
-    if isinstance(data, io.StringIO):
-        return "stringio"
-
-    # An option argument, mainly for dealing optional virtual files.
-    if isinstance(data, bool | int | float) or (data is None and not required):
-        return "arg"
-
-    # An xarray.DataArray object, representing a grid or an image.
-    if isinstance(data, xr.DataArray):
-        return "image" if len(data.dims) == 3 else "grid"
-
-    # Geo-like Python object that implements ``__geo_interface__`` (e.g.,
-    # geopandas.GeoDataFrame or shapely.geometry).
-    # Reference: https://gist.github.com/sgillies/2217756
-    if hasattr(data, "__geo_interface__"):
-        return "geojson"
-
-    # A 2-D numpy.ndarray.
-    if isinstance(data, np.ndarray) and data.ndim == 2:
-        return "matrix"
-
-    return "vectors"
+    match data:
+        case str() | pathlib.PurePath():  # One file.
+            kind = "file"
+        case list() | tuple() if all(
+            isinstance(_file, str | pathlib.PurePath) for _file in data
+        ):  # A list/tuple of files.
+            kind = "file"
+        case io.StringIO():
+            kind = "stringio"
+        case (bool() | int() | float()) | None if not required:
+            # An option argument, mainly for dealing with optional virtual files.
+            kind = "arg"
+        case xr.DataArray():
+            # An xarray.DataArray object, representing either a grid or an image.
+            kind = "image" if len(data.dims) == 3 else "grid"
+        case x if hasattr(x, "__geo_interface__"):
+            # Geo-like Python object that implements ``__geo_interface__`` (e.g.,
+            # geopandas.GeoDataFrame or shapely.geometry).
+            # Reference: https://gist.github.com/sgillies/2217756
+            kind = "geojson"
+        case np.ndarray() if data.ndim == 2:  # A 2-D numpy.ndarray object.
+            kind = "matrix"
+        case _:  # Fall back to "vectors" if data is None and required=True.
+            kind = "vectors"
+    return kind  # type: ignore[return-value]
 
 
 def non_ascii_to_octal(