pygmt.GMTDataArrayAccessor

class pygmt.GMTDataArrayAccessor(xarray_obj)[source]

GMT accessor for xarray.DataArray.

The gmt accessor extends xarray.DataArray to store GMT-specific properties for grids and images, which are important for PyGMT to correctly process and plot them. The gmt accessor contains the following properties:

The gmt accessor also provides a set of grid-operation methods that enables applying GMT’s grid processing functionalities directly to the current xarray.DataArray object. See the summary table below for the list of available methods.

Notes

When accessed the first time, the gmt accessor will first be initialized to the default values (GridRegistration.GRIDLINE and GridType.CARTESIAN, i.e., a gridline-registered, Cartesian grid), and then the properties will be updated with the correct grid registration and type determined from the source encoding (i.e., grid.encoding["source"]), if it is available.

Due to the limitations of xarray accessors, the gmt accessor is created once per xarray.DataArray instance. Thus, the gmt accessor will be re-initialized in cases where the xarray.DataArray is manipulated (e.g., arithmetic and slice operations) or when accessing a xarray.DataArray from a xarray.Dataset. In these cases, the GMT-specific properties will result in incorrect values if the source encoding is not defined or is dropped due to operations, and users need to manually set these properties again.

Examples

For grids loaded from a file (e.g., via xarray.load_dataarray) and GMT’s built-in remote datasets, the GMT-specific properties are automatically determined and you can access them as follows:

>>> from pygmt.datasets import load_earth_relief
>>> # Use the global Earth relief grid with 1 degree spacing
>>> grid = load_earth_relief(resolution="01d", registration="pixel")
>>> # See if grid uses Gridline or Pixel registration
>>> grid.gmt.registration
<GridRegistration.PIXEL: 1>
>>> # See if grid is in Cartesian or Geographic coordinate system
>>> grid.gmt.gtype
<GridType.GEOGRAPHIC: 1>
>>> grid.encoding["source"] is not None
True

Inplace assignment operators like *= don’t create new instances, so the properties are still kept:

>>> grid *= 2.0
>>> grid.gmt.registration
<GridRegistration.PIXEL: 1>
>>> grid.gmt.gtype
<GridType.GEOGRAPHIC: 1>

Slice operation creates a new instance, but the source encoding is kept, so the properties are still kept:

>>> grid_slice = grid[0:30, 50:80]
>>> # grid source encoding is kept in slice operation
>>> grid_slice.encoding["source"] is not None
True
>>> # properties are still kept
>>> grid_slice.gmt.registration
<GridRegistration.PIXEL: 1>
>>> grid_slice.gmt.gtype
<GridType.GEOGRAPHIC: 1>

Other grid operations (e.g., arithmetic operations) create new instances and drop the source encoding, so the properties will be reset to the default values:

>>> grid2 = grid * 2.0
>>> # grid source encoding is dropped in arithmetic operation.
>>> "source" in grid2.encoding
False
>>> # properties are reset to the default values
>>> grid2.gmt.registration
<GridRegistration.GRIDLINE: 0>
>>> grid2.gmt.gtype
<GridType.CARTESIAN: 0>
>>> # Need to set these properties before passing the grid to PyGMT
>>> grid2.gmt.registration = grid.gmt.registration
>>> grid2.gmt.gtype = grid.gmt.gtype
>>> grid2.gmt.registration
<GridRegistration.PIXEL: 1>
>>> grid2.gmt.gtype
<GridType.GEOGRAPHIC: 1>

For xarray.DataArray grids created from scratch, the source encoding is not available, so the properties will be set to the default values, and you need to manually set the correct properties before passing it to PyGMT functions:

>>> import numpy as np
>>> import xarray as xr
>>> import pygmt
>>> from pygmt.enums import GridRegistration, GridType
>>> # Create a DataArray in gridline coordinates of sin(lon) * cos(lat)
>>> interval = 2.5
>>> lat = np.arange(90, -90 - interval, -interval)
>>> lon = np.arange(0, 360 + interval, interval)
>>> longrid, latgrid = np.meshgrid(lon, lat)
>>> data = np.sin(np.deg2rad(longrid)) * np.cos(np.deg2rad(latgrid))
>>> grid = xr.DataArray(data, coords=[("latitude", lat), ("longitude", lon)])
>>> # Default to a gridline-registered Cartesian grid
>>> grid.gmt.registration
<GridRegistration.GRIDLINE: 0>
>>> grid.gmt.gtype
<GridType.CARTESIAN: 0>
>>> # Manually set it to a gridline-registered geographic grid
>>> grid.gmt.registration = GridRegistration.GRIDLINE
>>> grid.gmt.gtype = GridType.GEOGRAPHIC
>>> grid.gmt.registration
<GridRegistration.GRIDLINE: 0>
>>> grid.gmt.gtype
<GridType.GEOGRAPHIC: 1>

Accessing a xarray.DataArray from a xarray.Dataset always creates new instances, so these properties are always lost if the source encoding is not available. The workaround is to assign the xarray.DataArray into a variable:

>>> ds = xr.Dataset({"zval": grid})
>>> ds.zval.gmt.registration
<GridRegistration.GRIDLINE: 0>
>>> ds.zval.gmt.gtype
<GridType.CARTESIAN: 0>
>>> # Manually set these properties won't work as expected
>>> ds.zval.gmt.registration = GridRegistration.GRIDLINE
>>> ds.zval.gmt.gtype = GridType.GEOGRAPHIC
>>> ds.zval.gmt.registration, ds.zval.gmt.gtype
(<GridRegistration.GRIDLINE: 0>, <GridType.CARTESIAN: 0>)
>>> # workaround: assign the DataArray into a variable
>>> zval = ds.zval
>>> zval.gmt.registration, zval.gmt.gtype
(<GridRegistration.GRIDLINE: 0>, <GridType.CARTESIAN: 0>)
>>> zval.gmt.registration = GridRegistration.GRIDLINE
>>> zval.gmt.gtype = GridType.GEOGRAPHIC
>>> zval.gmt.registration, zval.gmt.gtype
(<GridRegistration.GRIDLINE: 0>, <GridType.GEOGRAPHIC: 1>)

Instead of calling a grid-processing function and passing the xarray.DataArray object as an input, you can call the corresponding method directly on the object. For example, the following two are equivalent:

>>> from pygmt.datasets import load_earth_relief
>>> grid = load_earth_relief(resolution="30m", region=[10, 30, 15, 25])
>>> # Create a new grid from an input grid. Set all values below 1,000 to 0 and all
>>> # values above 1,500 to 10,000.
>>> # Option 1:
>>> new_grid = pygmt.grdclip(grid=grid, below=[1000, 0], above=[1500, 10000])
>>> # Option 2:
>>> new_grid = grid.gmt.clip(below=[1000, 0], above=[1500, 10000])

Attributes

property GMTDataArrayAccessor.gtype: GridType

Grid coordinate system type pygmt.enums.GridType.

property GMTDataArrayAccessor.registration: GridRegistration

Grid registration type pygmt.enums.GridRegistration.

Methods Summary

GMTDataArrayAccessor.clip([outgrid, above, ...])

Clip the range of grid values.

GMTDataArrayAccessor.cut([kind, outgrid, ...])

Extract subregion from a grid or image or a slice from a cube.

GMTDataArrayAccessor.dimfilter([outgrid])

Directional filtering of grids in the space domain.

GMTDataArrayAccessor.fill([outgrid, ...])

Interpolate across holes in a grid.

GMTDataArrayAccessor.filter([outgrid])

Filter a grid in the space (or time) domain.

GMTDataArrayAccessor.gradient([outgrid])

Compute directional gradients from a grid.

GMTDataArrayAccessor.histeq(grid[, outgrid])

Perform histogram equalization for a grid.

GMTDataArrayAccessor.project([outgrid, ...])

Forward and inverse map transformation of grids.

GMTDataArrayAccessor.sample([outgrid])

Resample a grid onto a new lattice.

GMTDataArrayAccessor.track([points, ...])

Sample one or more grids at specified locations.