diff --git a/doc/techref/array_dtypes.md b/doc/techref/array_dtypes.md new file mode 100644 index 00000000000..2a4534bc51a --- /dev/null +++ b/doc/techref/array_dtypes.md @@ -0,0 +1,140 @@ +# 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 ({class}`int` and {class}`float`), PyGMT +supports most of the numeric dtypes provided by NumPy, pandas, and PyArrow. + +**Signed Integers** + +- `numpy.int8`, `numpy.int16`, `numpy.int32`, `numpy.int64`, {class}`numpy.longlong` +- {class}`pandas.Int8Dtype`, {class}`pandas.Int16Dtype`, {class}`pandas.Int32Dtype`, + {class}`pandas.Int64Dtype` +- {func}`pyarrow.int8`, {func}`pyarrow.int16`, {func}`pyarrow.int32`, + {func}`pyarrow.int64` + +**Unsigned Integers** + +- `numpy.uint8`, `numpy.uint16`, `numpy.uint32`, `numpy.uint64`, {class}`numpy.ulonglong` +- {class}`pandas.UInt8Dtype`, {class}`pandas.UInt16Dtype`, {class}`pandas.UInt32Dtype`, + {class}`pandas.UInt64Dtype` +- {func}`pyarrow.uint8`, {func}`pyarrow.uint16`, {func}`pyarrow.uint32`, + {func}`pyarrow.uint64` + +**Floating-point numbers** + +- `numpy.float32`, `numpy.float64` +- {class}`pandas.Float32Dtype`, {class}`pandas.Float64Dtype` +- {func}`pyarrow.float32`, {func}`pyarrow.float64` + +:::{note} +1. Signed and unsigned integer dtypes from pandas and PyArrow (e.g., + {class}`pandas.Int8Dtype`, {func}`pyarrow.int8`) support missing values like `None` + or {class}`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 {class}`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: + +```python +# 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 {class}`str` type, PyGMT also supports the following +string dtypes: + +- NumPy: {class}`numpy.str_` or fixed-width Unicode string dtype (e.g., ``"U10"``) +- pandas: {class}`pandas.StringDtype`, with different storage backends, including + `string[python]` and `string[pyarrow]` +- PyArrow: {func}`pyarrow.string`/{func}`pyarrow.utf8`, + {func}`pyarrow.large_string`/{func}`pyarrow.large_utf8`, and + {func}`pyarrow.string_view` + +:::{note} +Examples of string arrays supported by PyGMT: + +```python +# 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: + +- A list/tuple of elements in Python's built-in {class}`datetime.datetime` or + {class}`datetime.date`, datetime-like strings, or mixed. +- NumPy arrays: {class}`numpy.datetime64` with various resolutions +- pandas objects with {class}`numpy.datetime64`, {class}`pandas.DatetimeTZDtype`, + {func}`pyarrow.timestamp` with various resolution and timezone support, and + pyarrow-backend dtypes like `date32[day][pyarrow]` and `date64[ms][pyarrow]`, +- PyArrow: {func}`pyarrow.date32`, {func}`pyarrow.date64` and {func}`pyarrow.timestamp` + with various resolutions and timezone support. + +## Timedelta Dtypes + +PyGMT supports NumPy arrays with the {class}`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: + +- Floating-point dtypes: `numpy.float16`, {func}`pyarrow.float16` and + {class}`numpy.longdouble` +- Boolean dtypes: {class}`numpy.bool`, {class}`pandas.BooleanDtype` and + {func}`pyarrow.bool_` +- Complex dtypes: `numpy.complex64`, `numpy.complex128` +- {class}`numpy.bytes_` and {class}`numpy.void` + +The {class}`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. diff --git a/doc/techref/index.md b/doc/techref/index.md index a0534c5f933..c5ff33fef0e 100644 --- a/doc/techref/index.md +++ b/doc/techref/index.md @@ -16,4 +16,5 @@ text_formatting.md encodings.md justification_codes.md environment_variables.md +array_dtypes.md ```