Merge branch 'refactor/data_kind' into data_kind/vectors-none

Author: seisman

pygmt/_typing.py

@@ -0,0 +1,8 @@
+"""
+Type aliases for type hints.
+"""
+
+from typing import Literal
+
+# Anchor codes
+AnchorCode = Literal["TL", "TC", "TR", "ML", "MC", "MR", "BL", "BC", "BR"]

pygmt/clib/conversion.py

@@ -5,39 +5,45 @@
 import ctypes as ctp
 import warnings
 from collections.abc import Sequence
+from typing import Any
 
 import numpy as np
+import pandas as pd
+import xarray as xr
+from packaging.version import Version
 from pygmt.exceptions import GMTInvalidInput
 
 
-def dataarray_to_matrix(grid):
+def dataarray_to_matrix(
+    grid: xr.DataArray,
+) -> tuple[np.ndarray, list[float], list[float]]:
     """
-    Transform an xarray.DataArray into a data 2-D array and metadata.
+    Transform an xarray.DataArray into a 2-D numpy array and metadata.
 
-    Use this to extract the underlying numpy array of data and the region and
-    increment for the grid.
+    Use this to extract the underlying numpy array of data and the region and increment
+    for the grid.
 
-    Only allows grids with two dimensions and constant grid spacing (GMT
-    doesn't allow variable grid spacing). If the latitude and/or longitude
-    increments of the input grid are negative, the output matrix will be
-    sorted by the DataArray coordinates to yield positive increments.
+    Only allows grids with two dimensions and constant grid spacings (GMT doesn't allow
+    variable grid spacings). If the latitude and/or longitude increments of the input
+    grid are negative, the output matrix will be sorted by the DataArray coordinates to
+    yield positive increments.
 
-    If the underlying data array is not C contiguous, for example if it's a
-    slice of a larger grid, a copy will need to be generated.
+    If the underlying data array is not C contiguous, for example, if it's a slice of a
+    larger grid, a copy will need to be generated.
 
     Parameters
     ----------
-    grid : xarray.DataArray
-        The input grid as a DataArray instance. Information is retrieved from
-        the coordinate arrays, not from headers.
+    grid
+        The input grid as a DataArray instance. Information is retrieved from the
+        coordinate arrays, not from headers.
 
     Returns
     -------
-    matrix : 2-D array
+    matrix
         The 2-D array of data from the grid.
-    region : list
+    region
         The West, East, South, North boundaries of the grid.
-    inc : list
+    inc
         The grid spacing in East-West and North-South, respectively.
 
     Raises
@@ -62,8 +68,8 @@ def dataarray_to_matrix(grid):
     (180, 360)
     >>> matrix.flags.c_contiguous
     True
-    >>> # Using a slice of the grid, the matrix will be copied to guarantee
-    >>> # that it's C-contiguous in memory. The increment should be unchanged.
+    >>> # Using a slice of the grid, the matrix will be copied to guarantee that it's
+    >>> # C-contiguous in memory. The increment should be unchanged.
     >>> matrix, region, inc = dataarray_to_matrix(grid[10:41, 30:101])
     >>> matrix.flags.c_contiguous
     True
@@ -73,7 +79,7 @@ def dataarray_to_matrix(grid):
     [-150.0, -79.0, -80.0, -49.0]
     >>> print(inc)
     [1.0, 1.0]
-    >>> # but not if only taking every other grid point.
+    >>> # The increment should change accordingly if taking every other grid point.
     >>> matrix, region, inc = dataarray_to_matrix(grid[10:41:2, 30:101:2])
     >>> matrix.flags.c_contiguous
     True
@@ -85,21 +91,19 @@ def dataarray_to_matrix(grid):
     [2.0, 2.0]
     """
     if len(grid.dims) != 2:
-        raise GMTInvalidInput(
-            f"Invalid number of grid dimensions '{len(grid.dims)}'. Must be 2."
-        )
+        msg = f"Invalid number of grid dimensions 'len({grid.dims})'. Must be 2."
+        raise GMTInvalidInput(msg)
+
     # Extract region and inc from the grid
-    region = []
-    inc = []
-    # Reverse the dims because it is rows, columns ordered. In geographic
-    # grids, this would be North-South, East-West. GMT's region and inc are
-    # East-West, North-South.
+    region, inc = [], []
+    # Reverse the dims because it is rows, columns ordered. In geographic grids, this
+    # would be North-South, East-West. GMT's region and inc are East-West, North-South.
     for dim in grid.dims[::-1]:
         coord = grid.coords[dim].to_numpy()
-        coord_incs = coord[1:] - coord[0:-1]
+        coord_incs = coord[1:] - coord[:-1]
         coord_inc = coord_incs[0]
         if not np.allclose(coord_incs, coord_inc):
-            # calculate the increment if irregular spacing is found
+            # Calculate the increment if irregular spacing is found.
             coord_inc = (coord[-1] - coord[0]) / (coord.size - 1)
             msg = (
                 f"Grid may have irregular spacing in the '{dim}' dimension, "
@@ -108,9 +112,8 @@ def dataarray_to_matrix(grid):
             )
             warnings.warn(msg, category=RuntimeWarning, stacklevel=2)
         if coord_inc == 0:
-            raise GMTInvalidInput(
-                f"Grid has a zero increment in the '{dim}' dimension."
-            )
+            msg = f"Grid has a zero increment in the '{dim}' dimension."
+            raise GMTInvalidInput(msg)
         region.extend(
             [
                 coord.min() - coord_inc / 2 * grid.gmt.registration,
@@ -129,26 +132,25 @@ def dataarray_to_matrix(grid):
     return matrix, region, inc
 
 
-def vectors_to_arrays(vectors):
+def vectors_to_arrays(vectors: Sequence[Any]) -> list[np.ndarray]:
     """
-    Convert 1-D vectors (lists, arrays, or pandas.Series) to C contiguous 1-D arrays.
+    Convert 1-D vectors (scalars, lists, or array-like) to C contiguous 1-D arrays.
 
-    Arrays must be in C contiguous order for us to pass their memory pointers
-    to GMT. If any are not, convert them to C order (which requires copying the
-    memory). This usually happens when vectors are columns of a 2-D array or
-    have been sliced.
+    Arrays must be in C contiguous order for us to pass their memory pointers to GMT.
+    If any are not, convert them to C order (which requires copying the memory). This
+    usually happens when vectors are columns of a 2-D array or have been sliced.
 
-    If a vector is a list or pandas.Series, get the underlying numpy array.
+    The returned arrays are guaranteed to be C contiguous and at least 1-D.
 
     Parameters
     ----------
-    vectors : list of lists, 1-D arrays, or pandas.Series
+    vectors
         The vectors that must be converted.
 
     Returns
     -------
-    arrays : list of 1-D arrays
-        The converted numpy arrays
+    arrays
+        List of converted numpy arrays.
 
     Examples
     --------
@@ -178,6 +180,10 @@ def vectors_to_arrays(vectors):
     >>> [i.ndim for i in data]  # Check that they are 1-D arrays
     [1, 1, 1]
 
+    >>> series = pd.Series(data=[0, 4, pd.NA, 8, 6], dtype=pd.Int32Dtype())
+    >>> vectors_to_arrays([series])
+    [array([ 0.,  4., nan,  8.,  6.])]
+
     >>> import datetime
     >>> import pytest
     >>> pa = pytest.importorskip("pyarrow")
@@ -205,8 +211,20 @@ def vectors_to_arrays(vectors):
     }
     arrays = []
     for vector in vectors:
-        vec_dtype = str(getattr(vector, "dtype", ""))
-        arrays.append(np.ascontiguousarray(vector, dtype=dtypes.get(vec_dtype)))
+        if (
+            hasattr(vector, "isna")
+            and vector.isna().any()
+            and Version(pd.__version__) < Version("2.2")
+        ):
+            # Workaround for dealing with pd.NA with pandas < 2.2.
+            # Bug report at: https://github.com/GenericMappingTools/pygmt/issues/2844
+            # Following SPEC0, pandas 2.1 will be dropped in 2025 Q3, so it's likely
+            # we can remove the workaround in PyGMT v0.17.0.
+            array = np.ascontiguousarray(vector.astype(float))
+        else:
+            vec_dtype = str(getattr(vector, "dtype", ""))
+            array = np.ascontiguousarray(vector, dtype=dtypes.get(vec_dtype))
+        arrays.append(array)
     return arrays
 
 
@@ -289,16 +307,15 @@ def strings_to_ctypes_array(strings: Sequence[str]) -> ctp.Array:
     return (ctp.c_char_p * len(strings))(*[s.encode() for s in strings])
 
 
-def array_to_datetime(array):
+def array_to_datetime(array: Sequence[Any]) -> np.ndarray:
     """
     Convert a 1-D datetime array from various types into numpy.datetime64.
 
-    If the input array is not in legal datetime formats, raise a ValueError
-    exception.
+    If the input array is not in legal datetime formats, raise a ValueError exception.
 
     Parameters
     ----------
-    array : list or 1-D array
+    array
         The input datetime array in various formats.
 
         Supported types:
@@ -310,7 +327,8 @@ def array_to_datetime(array):
 
     Returns
     -------
-    array : 1-D datetime array in numpy.datetime64
+    array
+        1-D datetime array in numpy.datetime64.
 
     Raises
     ------

pygmt/clib/session.py

@@ -105,33 +105,28 @@ class Session:
     """
     A GMT API session where most operations involving the C API happen.
 
-    Works as a context manager (for use in a ``with`` block) to create a GMT C
-    API session and destroy it in the end to clean up memory.
+    Works as a context manager (for use in a ``with`` block) to create a GMT C API
+    session and destroy it in the end to clean up memory.
 
-    Functions of the shared library are exposed as methods of this class. Most
-    methods MUST be used with an open session (inside a ``with`` block). If
-    creating GMT data structures to communicate data, put that code inside the
-    same ``with`` block as the API calls that will use the data.
+    Functions of the shared library are exposed as methods of this class. Most methods
+    MUST be used with an open session (inside a ``with`` block). If creating GMT data
+    structures to communicate data, put that code inside the same ``with`` block as the
+    API calls that will use the data.
 
-    By default, will let :mod:`ctypes` try to find the GMT shared library
-    (``libgmt``). If the environment variable :term:`GMT_LIBRARY_PATH` is set, will
-    look for the shared library in the directory specified by it.
+    By default, will let :mod:`ctypes` try to find the GMT shared library (``libgmt``).
+    If the environment variable :term:`GMT_LIBRARY_PATH` is set, will look for the
+    shared library in the directory specified by it.
 
-    A ``GMTVersionError`` exception will be raised if the GMT shared library
-    reports a version older than the required minimum GMT version.
-
-    The ``session_pointer`` attribute holds a ctypes pointer to the currently
-    open session.
+    The ``session_pointer`` attribute holds a ctypes pointer to the currently open
+    session.
 
     Raises
     ------
     GMTCLibNotFoundError
-        If there was any problem loading the library (couldn't find it or
-        couldn't access the functions).
+        If there was any problem loading the library (couldn't find it or couldn't
+        access the functions).
     GMTCLibNoSessionError
-        If you try to call a method outside of a 'with' block.
-    GMTVersionError
-        If the minimum required version of GMT is not found.
+        If you try to call a method outside of a ``with`` block.
 
     Examples
     --------
@@ -141,45 +136,44 @@ class Session:
     >>> grid = load_static_earth_relief()
     >>> type(grid)
     <class 'xarray.core.dataarray.DataArray'>
-    >>> # Create a session and destroy it automatically when exiting the "with"
-    >>> # block.
-    >>> with Session() as ses:
+    >>> # Create a session and destroy it automatically when exiting the "with" block.
+    >>> with Session() as lib:
     ...     # Create a virtual file and link to the memory block of the grid.
-    ...     with ses.virtualfile_from_grid(grid) as fin:
+    ...     with lib.virtualfile_from_grid(grid) as fin:
     ...         # Create a temp file to use as output.
     ...         with GMTTempFile() as fout:
-    ...             # Call the grdinfo module with the virtual file as input
-    ...             # and the temp file as output.
-    ...             ses.call_module("grdinfo", [fin, "-C", f"->{fout.name}"])
+    ...             # Call the grdinfo module with the virtual file as input and the
+    ...             # temp file as output.
+    ...             lib.call_module("grdinfo", [fin, "-C", f"->{fout.name}"])
     ...             # Read the contents of the temp file before it's deleted.
     ...             print(fout.read().strip())
     -55 -47 -24 -10 190 981 1 1 8 14 1 1
     """
 
     @property
-    def session_pointer(self):
+    def session_pointer(self) -> ctp.c_void_p:
         """
         The :class:`ctypes.c_void_p` pointer to the current open GMT session.
 
         Raises
         ------
         GMTCLibNoSessionError
-            If trying to access without a currently open GMT session (i.e.,
-            outside of the context manager).
+            If trying to access without a currently open GMT session (i.e., outside of
+            the context manager).
         """
         if not hasattr(self, "_session_pointer") or self._session_pointer is None:
             raise GMTCLibNoSessionError("No currently open GMT API session.")
         return self._session_pointer
 
     @session_pointer.setter
-    def session_pointer(self, session):
+    def session_pointer(self, session: ctp.c_void_p):
         """
         Set the session void pointer.
         """
         self._session_pointer = session
 
     @property
-    def info(self):
+    def info(self) -> dict[str, str]:
         """
         Dictionary with the GMT version and default paths and parameters.
         """
@@ -629,31 +623,29 @@ def call_module(self, module: str, args: str | list[str]):
 
         # 'args' can be (1) a single string or (2) a list of strings.
         argv: bytes | ctp.Array[ctp.c_char_p] | None
-        if isinstance(args, str):
-            # 'args' is a single string that contains whitespace-separated arguments.
-            # In this way, we need to correctly handle option arguments that contain
-            # whitespaces or quotation marks. It's used in PyGMT <= v0.11.0 but is no
-            # longer recommended.
-            mode = self["GMT_MODULE_CMD"]
-            argv = args.encode()
-        elif isinstance(args, list):
+        if isinstance(args, list):
             # 'args' is a list of strings and each string contains a module argument.
             # In this way, GMT can correctly handle option arguments with whitespaces or
             # quotation marks. This is the preferred way to pass arguments to the GMT
             # API and is used for PyGMT >= v0.12.0.
             mode = len(args)  # 'mode' is the number of arguments.
             # Pass a null pointer if no arguments are specified.
             argv = strings_to_ctypes_array(args) if mode != 0 else None
+        elif isinstance(args, str):
+            # 'args' is a single string that contains whitespace-separated arguments.
+            # In this way, we need to correctly handle option arguments that contain
+            # whitespaces or quotation marks. It's used in PyGMT <= v0.11.0 but is no
+            # longer recommended.
+            mode = self["GMT_MODULE_CMD"]
+            argv = args.encode()
         else:
-            raise GMTInvalidInput(
-                "'args' must be either a string or a list of strings."
-            )
+            msg = "'args' must either be a list of strings (recommended) or a string."
+            raise GMTInvalidInput(msg)
 
         status = c_call_module(self.session_pointer, module.encode(), mode, argv)
         if status != 0:
-            raise GMTCLibError(
-                f"Module '{module}' failed with status code {status}:\n{self._error_message}"
-            )
+            msg = f"Module '{module}' failed with status code {status}:\n{self._error_message}"
+            raise GMTCLibError(msg)
 
     def create_data(
         self,

pygmt/helpers/utils.py

@@ -11,7 +11,7 @@
 import sys
 import time
 import webbrowser
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Literal
 
 import numpy as np
@@ -406,7 +406,7 @@ def non_ascii_to_octal(
 
 def build_arg_list(  # noqa: PLR0912
     kwdict: dict[str, Any],
-    confdict: dict[str, str] | None = None,
+    confdict: Mapping[str, Any] | None = None,
     infile: str | pathlib.PurePath | Sequence[str | pathlib.PurePath] | None = None,
     outfile: str | pathlib.PurePath | None = None,
 ) -> list[str]: