Allow passing region to GMTBackendEntrypoint.open_dataset

[weiji14]

Description of proposed changes

Support passing in a region as a Sequence [xmin, xmax, ymin, ymax] or ISO country code to xarray.open_dataset when using engine="gmt".

Usage:

import numpy.testing as npt
import xarray as xr

da = xr.open_dataarray("@static_earth_relief.nc", engine="gmt", raster_kind="grid", region=[-52, -48, -18, -12])
assert da.sizes == {"lat": 6, "lon": 4}
npt.assert_allclose(da.lat, [-17.5, -16.5, -15.5, -14.5, -13.5, -12.5])
npt.assert_allclose(da.lon, [-51.5, -50.5, -49.5, -48.5])

This PR also refactors the internals of _load_remote_dataset to use xr.load_dataarray(engine="gmt", ...) instead of low-level calls to clib functions.

Extends #3919, adapted from #3673

Preview:

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[weiji14]

Coordinate names are y/x when region=None, but lat/lon when region is not None at L90 below. Need to fix this inconsistency.

[weiji14]

Should we keep grid.encoding["source"] as undefined/None for tiled grids (xref #3673 (comment))? Or select the first tile (e.g. S90E000.earth_relief_05m_p.nc)? May need to update this test depending on what we decide.

[weiji14]

Do we actually need the _ = raster.gmt line at L124 to load GMTDataArray accessor info, since lib.virtualfile_to_raster already calls self.read_virtualfile(vfname, kind=kind).contents.to_xarray() which sets the registration and gtype based on the header?

pygmt/pygmt/datatypes/grid.py

Lines 197 to 201 in 74de7d8

	# Set GMT accessors.
	# Must put at the end, otherwise info gets lost after certain grid operations.
	grid.gmt.registration = header.registration
	grid.gmt.gtype = header.gtype
	return grid

[seisman]

that's a good point. please try remove it and see if everything works fine.

[weiji14]

There is one extra test failure at https://github.com/GenericMappingTools/pygmt/actions/runs/14743641047/job/41386753150#step:10:1049:

_____________ [doctest] pygmt.xarray.accessor.GMTDataArrayAccessor _____________
026     Examples
027     --------
028     For GMT's built-in remote datasets, these GMT-specific properties are automatically
029     determined and you can access them as follows:
030 
031     >>> from pygmt.datasets import load_earth_relief
032     >>> # Use the global Earth relief grid with 1 degree spacing
033     >>> grid = load_earth_relief(resolution="01d", registration="pixel")
034     >>> # See if grid uses Gridline or Pixel registration
035     >>> grid.gmt.registration
Expected:
    <GridRegistration.PIXEL: 1>
Got:
    1

I think this might be because the _GMT_GRID_HEADER.registration property returns an int instead of an enum?

pygmt/pygmt/datatypes/header.py

Lines 81 to 82 in d29303b

	# Grid registration, 0 for gridline and 1 for pixel
	("registration", ctp.c_uint32),

and we overrode grid.gmt.registration with 1 instead of <GridRegistration.PIXEL: 1>. Should be a quick fix we can do in a separate PR. Edit: no, the GMTDataArrayAccessor registration property should always return an enum, not an int, something else in this PR seems to be affecting this doctest...