Add pygmt.read to read a dataset/grid/image into pandas.DataFrame/xarray.DataArray

[seisman]

Description of proposed changes

This PR adds the pygmt.read function to read any recognized data files (currently dataset, grid, or image) into a pandas.DataFrame/xarray.DataArray object.

The new read function can replace most load_dataarray/xr.open_dataarray/xr.load_dataarray calls.

Related to #3643 (comment).

Preview: https://pygmt-dev--3673.org.readthedocs.build/en/3673/api/generated/pygmt.read.html

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.
• Use underscores (not hyphens) in names of Python files and directories.

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

[seisman]

This line is used here to avoid using the kwargs_to_string, use_alias decorators:

"R": "/".join(f"{v}" for v in region) if is_nonstr_iter(region) else region

[seisman]

In the _load_remote_dataset function, we can't replace the following codes with the new read function, because in read, we call which to get the full path of the source grid, which doesn't work well for tiled grids.

pygmt/pygmt/datasets/load_remote_dataset.py

Lines 444 to 459 in 7768e93

	fname = f"@{prefix}_{resolution}_{reg}"
	kind = "image" if name in {"earth_day", "earth_night"} else "grid"
	kwdict = {"R": region, "T": {"grid": "g", "image": "i"}[kind]}
	with Session() as lib:
	with lib.virtualfile_out(kind=kind) as voutgrd:
	lib.call_module(
	module="read",
	args=[fname, voutgrd, *build_arg_list(kwdict)],
	)
	grid = lib.virtualfile_to_raster(kind=kind, outgrid=None, vfname=voutgrd)
	# Full path to the grid if not tiled grids.
	source = which(fname, download="a") if not resinfo.tiled else None
	# Manually add source to xarray.DataArray encoding to make the GMT accessors work.
	if source:
	grid.encoding["source"] = source

[seisman]

Now, the load_dataarray function is used in pygmt/src/grdcut.py only (related to #3115).

xr.open_dataarray is used in test_accessors.py.

[michaelgrund]

Suggested change

	column names from table header. Ignored if the row number is larger than the
	column names from the table header. Ignored if the row number is larger than the

[michaelgrund]

Suggested change

	number of headers in the table.
	number of header lines in the table.