Supported Array Dtypes

PyGMT uses NumPy arrays as its core data structure for storing data and exchanging data with the GMT C API. This design allows PyGMT to support a wide range of array-like objects and data types (dtypes), as long as they can be converted to NumPy arrays. This page provides a comprehensive overview of the array dtypes supported by PyGMT.

Numeric Dtypes

In addition to Python’s built-in numeric types (int and float), PyGMT supports most of the numeric dtypes provided by NumPy, pandas, and PyArrow.

Signed Integers

Unsigned Integers

Floating-point numbers

Note

  1. Signed and unsigned integer dtypes from pandas and PyArrow (e.g., pandas.Int8Dtype, pyarrow.int8) support missing values like None or pandas.NA, whereas NumPy’s corresponding dtypes (e.g., numpy.int8) don’t. Arrays of these dtypes containing missing values are automatically cast to numpy.float64 internally.

  2. For 3-D xarray.DataArray objects representing raster images, only 8-bit unsigned integers (i.e., numpy.uint8) are supported.

Note

Examples of numeric arrays supported by PyGMT:

# A list of integers
[1, 2, 3]

# A NumPy array with dtype int32
np.array([1, 2, 3], dtype=np.int32)

# A pandas Series with nullable Int32 dtype
pd.Series([1, 2, 3], dtype="Int32")

# A pandas Series with nullable Int32 dtype and missing values
pd.Series([1, 2, pd.NA], dtype="Int32")

# A pandas Series using a PyArrow-backed float64 dtype
pd.Series([1, 2, 3], dtype="float64[pyarrow]")

# A PyArrow array with dtype uint8
pa.array([1, 2, 3], type=pa.uint8())

String Dtypes

In addition to Python’s built-in str type, PyGMT also supports the following string dtypes:

Note

Examples of string arrays supported by PyGMT:

# A list of strings
["a", "b", "c"]

# A NumPy string array
np.array(["a", "b", "c"])
np.array(["a", "b", "c"], dtype=np.str_)

# A pandas.Series string array
pd.Series(["a", "b", "c"], dtype="string")
pd.Series(["a", "b", "c"], dtype="string[python]")
pd.Series(["a", "b", "c"], dtype="string[pyarrow]")

# A PyArrow array with pyarrow.string dtype
pa.array(["a", "b", "c"], type=pa.string())

Datetime Dtypes

PyGMT supports a variety of datetime types:

Timedelta Dtypes

PyGMT supports NumPy arrays with the numpy.timedelta64 dtype. Timedelta values are passed to GMT as their underlying integer values, so their unit determines the numeric scale. For example, a timedelta64[D] array is interpreted as days, whereas a timedelta64[s] array is interpreted as seconds.

Timedelta values can also be used in sequence-valued parameters such as region. The timedelta dtype does not, by itself, configure a GMT relative-time axis; configure GMT time settings explicitly when a relative-time axis is required.

Unsupported Dtypes

The following dtypes are intentionally unsupported, and should be cast to an appropriate supported dtype before passing to PyGMT:

The numpy.object_ dtype is also not supported. PyGMT may convert object arrays that can be interpreted as datetimes or text, but applications should create arrays with an explicit supported dtype instead.