Merge branch 'main' into datatypes/gmtcube

Author: seisman

.github/workflows/benchmarks.yml

@@ -44,7 +44,7 @@ jobs:
 
       # Install Miniconda with conda-forge dependencies
       - name: Setup Miniconda
-        uses: conda-incubator/[email protected].1
+        uses: conda-incubator/[email protected].3
         with:
           auto-activate-base: true
           activate-environment: ""  # base environment
@@ -86,7 +86,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@v2.2.1
+        uses: CodSpeedHQ/action@v2.3.0
         with:
           run: |
             python -c "import pygmt; pygmt.show_versions()"

.github/workflows/cache_data.yaml

@@ -80,7 +80,7 @@ jobs:
         with:
           name: gmt-cache
           path: |
-              ~/.gmt/cache
-              ~/.gmt/server
-              ~/.gmt/gmt_data_server.txt
-              ~/.gmt/gmt_hash_server.txt
+            ~/.gmt/cache
+            ~/.gmt/server
+            ~/.gmt/gmt_data_server.txt
+            ~/.gmt/gmt_hash_server.txt

.github/workflows/check-links.yml

@@ -68,7 +68,8 @@ jobs:
 
     - name: Create Issue From File
       if: env.lychee_exit_code != 0
-      uses: peter-evans/create-issue-from-file@v5
-      with:
-        title: Link Checker Report on ${{ steps.date.outputs.date }}
-        content-filepath: ./lychee/out.md
+      run: |
+        title="Link Checker Report on ${{ steps.date.outputs.date }}"
+        gh issue create --title "$title" --body-file ./lychee/out.md
+        env:
+          GH_TOKEN: ${{secrets.GITHUB_TOKEN}}

.github/workflows/ci_tests.yaml

@@ -166,7 +166,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4.1.1
+        uses: codecov/codecov-action@v4.3.0
         with:
           file: ./coverage.xml # optional
           env_vars: OS,PYTHON,NUMPY

.github/workflows/format-command.yml

@@ -11,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Generate token from GenericMappingTools bot
-      - uses: tibdex/github-app-token@v2
+      - uses: actions/create-github-app-token@v1.9.3
         id: generate-token
         with:
-          app_id: ${{ secrets.APP_ID }}
-          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
 
       # Checkout the pull request branch
       - uses: actions/[email protected]

.github/workflows/release-baseline-images.yml

@@ -35,7 +35,7 @@ jobs:
         shasum -a 256 baseline-images.zip
 
     - name: Upload baseline image as a release asset
-      uses: shogo82148/[email protected].4
+      uses: shogo82148/[email protected].5
       with:
         upload_url: ${{ github.event.release.upload_url }}
         asset_path: baseline-images.zip

doc/api/index.rst

@@ -292,6 +292,7 @@ Python objects to and from GMT virtual files:
     clib.Session.virtualfile_in
     clib.Session.virtualfile_out
     clib.Session.virtualfile_to_dataset
+    clib.Session.virtualfile_to_raster
 
 Low level access (these are mostly used by the :mod:`pygmt.clib` package):
 

environment.yml

@@ -27,7 +27,7 @@ dependencies:
     - codespell
     - ruff>=0.3.0
     # Dev dependencies (unit testing)
-    - matplotlib
+    - matplotlib-base
     - pytest-cov
     - pytest-doctestplus
     - pytest-mpl

pygmt/clib/session.py

@@ -14,6 +14,7 @@
 
 import numpy as np
 import pandas as pd
+import xarray as xr
 from packaging.version import Version
 from pygmt.clib.conversion import (
     array_to_datetime,
@@ -1712,8 +1713,39 @@ def virtualfile_out(
             with self.open_virtualfile(family, geometry, "GMT_OUT", None) as vfile:
                 yield vfile
 
+    def inquire_virtualfile(self, vfname: str) -> int:
+        """
+        Get the family of a virtual file.
+
+        Parameters
+        ----------
+        vfname
+            Name of the virtual file to inquire.
+
+        Returns
+        -------
+        family
+            The integer value for the family of the virtual file.
+
+        Examples
+        --------
+        >>> from pygmt.clib import Session
+        >>> with Session() as lib:
+        ...     with lib.virtualfile_out(kind="dataset") as vfile:
+        ...         family = lib.inquire_virtualfile(vfile)
+        ...         assert family == lib["GMT_IS_DATASET"]
+        """
+        c_inquire_virtualfile = self.get_libgmt_func(
+            "GMT_Inquire_VirtualFile",
+            argtypes=[ctp.c_void_p, ctp.c_char_p],
+            restype=ctp.c_uint,
+        )
+        return c_inquire_virtualfile(self.session_pointer, vfname.encode())
+
     def read_virtualfile(
-        self, vfname: str, kind: Literal["dataset", "grid", "cube", None] = None
+        self,
+        vfname: str,
+        kind: Literal["dataset", "grid", "image", "cube", None] = None,
     ):
         """
         Read data from a virtual file and optionally cast into a GMT data container.
@@ -1772,13 +1804,15 @@ def read_virtualfile(
         # _GMT_DATASET).
         if kind is None:  # Return the ctypes void pointer
             return pointer
+        if kind == "image":
+            raise NotImplementedError(f"kind={kind} is not supported yet.")
         dtype = {"dataset": _GMT_DATASET, "grid": _GMT_GRID, "cube": _GMT_CUBE}[kind]
         return ctp.cast(pointer, ctp.POINTER(dtype))
 
     def virtualfile_to_dataset(
         self,
         vfname: str,
-        output_type: Literal["pandas", "numpy", "file"] = "pandas",
+        output_type: Literal["pandas", "numpy", "file", "strings"] = "pandas",
         column_names: list[str] | None = None,
         dtype: type | dict[str, type] | None = None,
         index_col: str | int | None = None,
@@ -1799,6 +1833,7 @@ def virtualfile_to_dataset(
             - ``"pandas"`` will return a :class:`pandas.DataFrame` object.
             - ``"numpy"`` will return a :class:`numpy.ndarray` object.
             - ``"file"`` means the result was saved to a file and will return ``None``.
+            - ``"strings"`` will return the trailing text only as an array of strings.
         column_names
             The column names for the :class:`pandas.DataFrame` output.
         dtype
@@ -1844,6 +1879,16 @@ def virtualfile_to_dataset(
         ...                 assert result is None
         ...                 assert Path(outtmp.name).stat().st_size > 0
         ...
+        ...     # strings output
+        ...     with Session() as lib:
+        ...         with lib.virtualfile_out(kind="dataset") as vouttbl:
+        ...             lib.call_module("read", f"{tmpfile.name} {vouttbl} -Td")
+        ...             outstr = lib.virtualfile_to_dataset(
+        ...                 vfname=vouttbl, output_type="strings"
+        ...             )
+        ...     assert isinstance(outstr, np.ndarray)
+        ...     assert outstr.dtype.kind in ("S", "U")
+        ...
         ...     # numpy output
         ...     with Session() as lib:
         ...         with lib.virtualfile_out(kind="dataset") as vouttbl:
@@ -1872,6 +1917,9 @@ def virtualfile_to_dataset(
         ...                 column_names=["col1", "col2", "col3", "coltext"],
         ...             )
         ...     assert isinstance(outpd2, pd.DataFrame)
+        >>> outstr
+        array(['TEXT1 TEXT23', 'TEXT4 TEXT567', 'TEXT8 TEXT90',
+           'TEXT123 TEXT456789'], dtype='<U18')
         >>> outnp
         array([[1.0, 2.0, 3.0, 'TEXT1 TEXT23'],
                [4.0, 5.0, 6.0, 'TEXT4 TEXT567'],
@@ -1893,16 +1941,83 @@ def virtualfile_to_dataset(
         if output_type == "file":  # Already written to file, so return None
             return None
 
-        # Read the virtual file as a GMT dataset and convert to pandas.DataFrame
-        result = self.read_virtualfile(vfname, kind="dataset").contents.to_dataframe(
-            column_names=column_names,
-            dtype=dtype,
-            index_col=index_col,
+        # Read the virtual file as a _GMT_DATASET object
+        result = self.read_virtualfile(vfname, kind="dataset").contents
+
+        if output_type == "strings":  # strings output
+            return result.to_strings()
+
+        result = result.to_dataframe(
+            column_names=column_names, dtype=dtype, index_col=index_col
         )
         if output_type == "numpy":  # numpy.ndarray output
             return result.to_numpy()
         return result  # pandas.DataFrame output
 
+    def virtualfile_to_raster(
+        self,
+        vfname: str,
+        kind: Literal["grid", "image", "cube", None] = "grid",
+        outgrid: str | None = None,
+    ) -> xr.DataArray | None:
+        """
+        Output raster data stored in a virtual file to an :class:`xarray.DataArray`
+        object.
+
+        The raster data can be a grid, an image or a cube.
+
+        Parameters
+        ----------
+        vfname
+            The virtual file name that stores the result grid/image/cube.
+        kind
+            Type of the raster data. Valid values are ``"grid"``, ``"image"``,
+            ``"cube"`` or ``None``. If ``None``, will inquire the data type from the
+            virtual file name.
+        outgrid
+            Name of the output grid/image/cube. If specified, it means the raster data
+            was already saved into an actual file and will return ``None``.
+
+        Returns
+        -------
+        result
+            The result grid/image/cube. If ``outgrid`` is specified, return ``None``.
+
+        Examples
+        --------
+        >>> from pathlib import Path
+        >>> from pygmt.clib import Session
+        >>> from pygmt.helpers import GMTTempFile
+        >>> with Session() as lib:
+        ...     # file output
+        ...     with GMTTempFile(suffix=".nc") as tmpfile:
+        ...         outgrid = tmpfile.name
+        ...         with lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd:
+        ...             lib.call_module("read", f"@earth_relief_01d_g {voutgrd} -Tg")
+        ...             result = lib.virtualfile_to_raster(
+        ...                 vfname=voutgrd, outgrid=outgrid
+        ...             )
+        ...             assert result == None
+        ...             assert Path(outgrid).stat().st_size > 0
+        ...
+        ...     # xarray.DataArray output
+        ...     outgrid = None
+        ...     with lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd:
+        ...         lib.call_module("read", f"@earth_relief_01d_g {voutgrd} -Tg")
+        ...         result = lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)
+        ...         assert isinstance(result, xr.DataArray)
+        """
+        if outgrid is not None:
+            return None
+        if kind is None:  # Inquire the data family from the virtualfile
+            family = self.inquire_virtualfile(vfname)
+            kind = {  # type: ignore[assignment]
+                self["GMT_IS_GRID"]: "grid",
+                self["GMT_IS_IMAGE"]: "image",
+                self["GMT_IS_CUBE"]: "cube",
+            }[family]
+        return self.read_virtualfile(vfname, kind=kind).contents.to_dataarray()
+
     def extract_region(self):
         """
         Extract the WESN bounding box of the currently active figure.

pygmt/datatypes/dataset.py

@@ -3,6 +3,7 @@
 """
 
 import ctypes as ctp
+import warnings
 from collections.abc import Mapping
 from typing import Any, ClassVar
 
@@ -144,6 +145,28 @@ class _GMT_DATASEGMENT(ctp.Structure):  # noqa: N801
         ("hidden", ctp.c_void_p),
     ]
 
+    def to_strings(self) -> np.ndarray[Any, np.dtype[np.str_]]:
+        """
+        Convert the trailing text column to an array of strings.
+        """
+        textvector = []
+        for table in self.table[: self.n_tables]:
+            for segment in table.contents.segment[: table.contents.n_segments]:
+                if segment.contents.text:
+                    textvector.extend(segment.contents.text[: segment.contents.n_rows])
+        if None in textvector:
+            # Workaround for upstream GMT bug reported in
+            # https://github.com/GenericMappingTools/pygmt/issues/3170.
+            msg = (
+                "The trailing text column contains `None' values and has been replaced"
+                "with empty strings to avoid TypeError exceptions. "
+                "It's likely caused by an upstream GMT API bug. "
+                "Please consider reporting to us."
+            )
+            warnings.warn(msg, category=RuntimeWarning, stacklevel=1)
+            textvector = [item if item is not None else b"" for item in textvector]
+        return np.char.decode(textvector) if textvector else np.array([], dtype=str)
+
     def to_dataframe(
         self,
         column_names: pd.Index | None = None,
@@ -194,7 +217,11 @@ def to_dataframe(
         ...         with lib.virtualfile_out(kind="dataset") as vouttbl:
         ...             lib.call_module("read", f"{tmpfile.name} {vouttbl} -Td")
         ...             ds = lib.read_virtualfile(vouttbl, kind="dataset")
+        ...             text = ds.contents.to_strings()
         ...             df = ds.contents.to_dataframe()
+        >>> text
+        array(['TEXT1 TEXT23', 'TEXT4 TEXT567', 'TEXT8 TEXT90',
+           'TEXT123 TEXT456789'], dtype='<U18')
         >>> df
               0     1     2                   3
         0   1.0   2.0   3.0        TEXT1 TEXT23
@@ -207,28 +234,19 @@ def to_dataframe(
         vectors = []
         # Deal with numeric columns
         for icol in range(self.n_columns):
-            colvector = []
-            for itbl in range(self.n_tables):
-                dtbl = self.table[itbl].contents
-                for iseg in range(dtbl.n_segments):
-                    dseg = dtbl.segment[iseg].contents
-                    colvector.append(
-                        np.ctypeslib.as_array(dseg.data[icol], shape=(dseg.n_rows,))
-                    )
+            colvector = [
+                np.ctypeslib.as_array(
+                    seg.contents.data[icol], shape=(seg.contents.n_rows,)
+                )
+                for tbl in self.table[: self.n_tables]
+                for seg in tbl.contents.segment[: tbl.contents.n_segments]
+            ]
             vectors.append(pd.Series(data=np.concatenate(colvector)))
 
         # Deal with trailing text column
-        textvector = []
-        for itbl in range(self.n_tables):
-            dtbl = self.table[itbl].contents
-            for iseg in range(dtbl.n_segments):
-                dseg = dtbl.segment[iseg].contents
-                if dseg.text:
-                    textvector.extend(dseg.text[: dseg.n_rows])
-        if textvector:
-            vectors.append(
-                pd.Series(data=np.char.decode(textvector), dtype=pd.StringDtype())
-            )
+        textvector = self.to_strings()
+        if len(textvector) != 0:
+            vectors.append(pd.Series(data=textvector, dtype=pd.StringDtype()))
 
         if len(vectors) == 0:
             # Return an empty DataFrame if no columns are found.