Default CPTs for GMT remote datasets

[seisman]

Most GMT remote datasets have a default CPT. When plotting a dataset without specifying a CPT, the default CPT will be used. For example, the default CPT for earth_age dataset is @earth_age.cpt.

The following command plots the earth_age_01d_g.nc grid using the default @earth_age.cpt file.

gmt grdimage @earth_age_01d_g -png map

In the following PyGMT script, a grid file name is directly passed to Figure.grdimage. This script produces the indentical image:

import pygmt
fig = pygmt.Figure()
fig.grdimage(grid="@earth_age_01d_g")
fig.colorbar(frame=True)
fig.savefig("map.png")

However, if we load the dataset into a xarray.DataArray and pass it to Figure.grdimage, the default CPT changes to "turbo" (GMT's default CPT for any grid data).

import pygmt
from pygmt.datasets import load_earth_age

grid = load_earth_age()
fig = pygmt.Figure()
fig.grdimage(grid=grid)
fig.colorbar()
fig.savefig("map.png")

It would be good if PyGMT can use the specific CPT when a CPT is not specified, although it's technically difficult. At least we should document the default CPT for each dataset and add an example showing how to use the default dataset CPT.

[michaelgrund]

Agree, would be nice to have at least examples to show the most suitable CPT for each dataset.

[maxrjones]

This mechanism was discussed a bit in GenericMappingTools/gmt#6178 (comment). I think it would take detecting whether the user has set the current CPT and evaluating the grid for a cpt attr, then setting an argument to -C if only the latter is true. It would be worth evaluating the overhead for those checks. At least, documenting GMT's defaults seems useful.

[weiji14]

grid = load_earth_age()
fig = pygmt.Figure()
fig.grdimage(grid=grid)

Could we store the default cmap in an xarray accessor (#499) or attribute, and then let grdimage default to that cmap if cmap=None?

Or, if we don't want to add the extra logic to grdimage, we could attempt to add it in the .gmt.imshow() function at #2372.

[seisman]

Could we store the default cmap in an xarray accessor (#499) or attribute,

We can, but xarray accessor or attribute have known limitations (#2375). The saved CPT information will be lost after some grid operations.

and then let grdimage default to that cmap if cmap=None?

The default value of cmap is always None, and cmap=None means that GMT will use the default CPT (turbo) or the current hidden CPT, depending on if a current hidden CPT exists. So we can't let grdimage default to that cmap if cmap=None.

[yvonnefroehlich]

@seisman: [...] add an example showing how to use the default dataset CPT.

Should such a gallery example focus on one remote dataset? E.g. earth_age:
Code example:

import pygmt

# #############################################################################
# Use "@earth_age_01d_g" to download the remote dataset `earth_age_01d_g`
# directly within the method pygmt.Figure.grdimage.

fig = pygmt.Figure()

fig.grdimage(grid="@earth_age_01d_g", frame=True)
fig.colorbar(frame="+lage / Myr")

fig.show()
# fig.savefig("datasets_cpt_example_at.png")
     

# #############################################################################
# Use `pygmt.datasets.load_earth_age()` to download the remote dataset 
# `earth_age` into a `xarray.DataArray`.

grid_earth_age = pygmt.datasets.load_earth_age()  

fig = pygmt.Figure()

# Left: Use GMT's overall default colormap turbo
fig.grdimage(grid=grid_earth_age, frame=["af", "WSne"])
fig.colorbar(frame="+lage / Myr")

fig.shift_origin(xshift="16c")

# Right: Use GMT's default colormap for the earth_age remote dataset
fig.grdimage(grid=grid_earth_age, cmap="@earth_age.cpt", frame=["af", "wSne"])
fig.colorbar(frame="+lage / Myr")

fig.show()
# fig.savefig("datasets_cpt_example_load.png")

Output figues:

---

@michaelgrund: Agree, would be nice to have at least examples to show the most suitable CPT for each dataset.

Or do we want any kind of overview, which shows / compares the colormaps for all remote datasets?
Regarding the unexpected display of the remote dataset earth_mask see issue #2629, please.
Edit 2023/08/16: Corrected figure based on the fix in PR #2632.

[seisman]

Agree, would be nice to have at least examples to show the most suitable CPT for each dataset.

Here are my thoughts. Instead of creating a huge image with too many datasets as done in #2325 (comment), I think we have two options:

1. In the Remote Datasets site, each dataset already has an overview image. So we can just directly include these images on the API documentation page of the datasets. For examples, adding the following codes to https://www.pygmt.org/dev/api/generated/pygmt.datasets.load_earth_age.html

.. image:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_age.png

2. Just like the Projections gallery, we can create a gallery for all available datasets.

I prefer to option 1, because it's much simpler, and we don't have to add so many scripts for these datasets, which also slowdown the documentation building. The Remote Datasets site should be the central place to show all the available datasets.

[yvonnefroehlich]

Agree, would be nice to have at least examples to show the most suitable CPT for each dataset.

Here are my thoughts. Instead of creating a huge image with too many datasets as done in #2325 (comment), I think we have two options:

1. In the Remote Datasets site, each dataset already has an overview image. So we can just directly include these images on the API documentation page of the datasets. For examples, adding the following codes to https://www.pygmt.org/dev/api/generated/pygmt.datasets.load_earth_age.html

.. image:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_age.png

2. Just like the Projections gallery, we can create a gallery for all available datasets.

I prefer to option 1, because it's much simpler, and we don't have to add so many scripts for these datasets, which also slowdown the documentation building. The Remote Datasets site should be the central place to show all the available datasets.

I also prefer option 1. Having a gallery for all available datasets separately from the API reference would probably lead to reduant parts.