pygmt.GMTBackendEntrypoint

class pygmt.GMTBackendEntrypoint[source]

Xarray backend to read raster grid/image files using ‘gmt’ engine.

Internally, GMT uses the netCDF C library to read netCDF files, and GDAL for GeoTIFF and other raster formats. See https://docs.generic-mapping-tools.org/6.6/reference/features.html#grid-file-format for more details about supported formats. This GMT engine can also read GMT remote datasets (file names starting with an @) directly, and pre-loads pygmt.GMTDataArrayAccessor properties (in the ‘.gmt’ accessor) for easy access to GMT-specific metadata and features.

When using xarray.open_dataarray or xarray.load_dataarray with engine="gmt", the raster_kind parameter is required and can be either:

"grid": for reading single-band raster grids
"image": for reading multi-band raster images

Optionally, you can pass in a region in the form of a sequence [xmin, xmax, ymin, ymax] or an ISO country code.

Examples

Read a single-band netCDF file using raster_kind="grid"

>>> import pygmt
>>> import xarray as xr
>>>
>>> da_grid = xr.open_dataarray(
...     "@static_earth_relief.nc", engine="gmt", raster_kind="grid"
... )
>>> da_grid
<xarray.DataArray 'z' (lat: 14, lon: 8)> Size: 448B
[112 values with dtype=float32]
Coordinates:
  * lat      (lat) float64 112B -23.5 -22.5 -21.5 -20.5 ... -12.5 -11.5 -10.5
  * lon      (lon) float64 64B -54.5 -53.5 -52.5 -51.5 -50.5 -49.5 -48.5 -47.5
:ivar Conventions: CF-1.7
:ivar title: Produced by grdcut
:ivar history: grdcut @earth_relief_01d_p -R-55/-47/-24/-10 -Gstatic_eart...
:ivar description: Reduced by Gaussian Cartesian filtering (111.2 km fullwidt...
:ivar actual_range: [190. 981.]
:ivar long_name: elevation (m)

Read a multi-band GeoTIFF file using raster_kind="image"

>>> da_image = xr.open_dataarray(
...     "@earth_night_01d", engine="gmt", raster_kind="image"
... )
>>> da_image
<xarray.DataArray 'z' (band: 3, y: 180, x: 360)> Size: 194kB
[194400 values with dtype=uint8]
Coordinates:
  * band     (band) uint8 3B 1 2 3
  * y        (y) float64 1kB 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
  * x        (x) float64 3kB -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
:ivar long_name: z

Load a single-band netCDF file using raster_kind="grid" over a bounding box region.

>>> da_grid = xr.load_dataarray(
...     "@tut_bathy.nc", engine="gmt", raster_kind="grid", region=[-64, -62, 32, 33]
... )
>>> da_grid
<xarray.DataArray 'z' (lat: 13, lon: 25)> Size: 1kB
array([[-4369., -4587., -4469., -4409., -4587., -4505., -4403., -4405.,
        -4466., -4595., -4609., -4608., -4606., -4607., -4607., -4597.,
...
        -4667., -4642., -4677., -4795., -4797., -4800., -4803., -4818.,
        -4820.]], dtype=float32)
Coordinates:
  * lat      (lat) float64 104B 32.0 32.08 32.17 32.25 ... 32.83 32.92 33.0
  * lon      (lon) float64 200B -64.0 -63.92 -63.83 ... -62.17 -62.08 -62.0
:ivar Conventions: CF-1.7
:ivar title: ETOPO5 global topography
:ivar history: grdreformat -fg bermuda.grd bermuda.nc=ns
:ivar description: /home/elepaio5/data/grids/etopo5.i2
:ivar actual_range: [-4968. -4315.]
:ivar long_name: Topography
:ivar units: m

Attributes

GMTBackendEntrypoint.description: ClassVar[str] = 'Open raster (.grd, .nc or .tif) files in Xarray via GMT.'

GMTBackendEntrypoint.open_dataset_parameters: ClassVar[tuple | None] = ('filename_or_obj', 'raster_kind', 'region')

GMTBackendEntrypoint.supports_groups: ClassVar[bool] = False

GMTBackendEntrypoint.url: ClassVar[str] = 'https://pygmt.org/dev/api/generated/pygmt.GMTBackendEntrypoint.html'

Methods Summary

`GMTBackendEntrypoint.guess_can_open`(...)	Backend open_dataset method used by Xarray in `open_dataset`.
`GMTBackendEntrypoint.open_dataset`(...[, ...])	Backend open_dataset method used by Xarray in `open_dataset`.
`GMTBackendEntrypoint.open_datatree`(...[, ...])	Backend open_datatree method used by Xarray in `open_datatree`.
`GMTBackendEntrypoint.open_groups_as_dict`(...)	Opens a dictionary mapping from group names to Datasets.