Remote datasets: Add "load_earth_dist" to load "GSHHG Earth distance to shoreline" dataset

[yvonnefroehlich]

Description of proposed changes

Add load_earth_dist to download the "GSHHG Earth distance to shoreline" dataset and load into a xarray.DataArray:

• Official documentation: https://www.generic-mapping-tools.org/remote-datasets/earth-dist.html
• Recipe: https://github.com/GenericMappingTools/gmtserver-admin/blob/master/recipes/earth_dist.recipe

Adresses #2431

Preview: https://pygmt-dev--3706.org.readthedocs.build/en/3706/api/generated/pygmt.datasets.load_earth_dist.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

[yvonnefroehlich]

/format

[seisman]

Thanks for working on this function. I feel we should first update the upstream documentation to clarify the following points:

1. The distance unit is km
2. The distances have both negative and positive values. Positive means land to coastline and negative means ocean to coastline.
3. For the dataset image, maybe we should add the coastline to make the image more readable. Like this one:
   

[seisman]

Need to update to the new syntax in #3696, depending on which PR is merged first.

[seisman]

Looks good to me. The dataset image will be updated automatically when the upstream PR is merged.

[yvonnefroehlich]

Currently we use both, the abbreviation and the complete word for units in load_remote_datasets.py:

pygmt/pygmt/datasets/load_remote_dataset.py

Lines 113 to 115 in b90fa46

	"earth_gebco": GMTRemoteDataset(
	description="GEBCO Earth relief",
	units="meters",

but

pygmt/pygmt/datasets/load_remote_dataset.py

Lines 135 to 137 in b90fa46

	"earth_geoid": GMTRemoteDataset(
	description="EGM2008 Earth geoid",
	units="m",

I think we should decide on one way and update the dictionary in load_remote_datasets.py and the related tests.

Edit:
For the unit "meters", the complete word may be better to avoid a confusion with the "m" used in the resolution argument, which means arc-minutes.

[seisman]

That's a good point. The CF convention mentions that the unit string must be recognized by the UDUNIT package. I quickly read the UNUNIT documentation, I think valid values are meter, m and metre (without s). But the CF-convention has an example that uses meters (https://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#vertical-coordinate).

[seisman]

This section (http://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#_dimensional_vertical_coordinate) says:

Plural forms are also acceptable.

So I think meters/meter/m are fine. Let's use meters then.

[yvonnefroehlich]

This section (http://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#_dimensional_vertical_coordinate) says:

Plural forms are also acceptable.

So I think meters/meter/m are fine. Let's use meters then.

Submitted PR #3725 for updating this for all datasets.