Document the default CPT for GMT remote datasets (#2573)

Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Yvonne Fröhlich <[email protected]>

Author: 3 people

pygmt/datasets/earth_age.py

@@ -26,6 +26,13 @@ def load_earth_age(resolution="01d", region=None, registration=None):
     registration type (**p** for pixel registration or **g** for gridline
     registration).
 
+    The default color palette table (CPT) for this dataset is *@earth_age.cpt*.
+    It's implicitly used when passing in the file name of the dataset to any
+    grid plotting method if no CPT is explicitly specified. When the dataset
+    is loaded and plotted as an :class:`xarray.DataArray` object, the default
+    CPT is ignored and GMT's default CPT (*turbo*) is used. To use the
+    dataset-specific CPT, you need to explicitly set ``cmap="@earth_age.cpt"``.
+
     Refer to :gmt-datasets:`earth-age.html` for more details.
 
     Parameters

pygmt/datasets/earth_free_air_anomaly.py

@@ -26,6 +26,13 @@ def load_earth_free_air_anomaly(resolution="01d", region=None, registration=None
     registration type (**p** for pixel registration or **g** for gridline
     registration).
 
+    The default color palette table (CPT) for this dataset is *@earth_faa.cpt*.
+    It's implicitly used when passing in the file name of the dataset to any
+    grid plotting method if no CPT is explicitly specified. When the dataset
+    is loaded and plotted as an :class:`xarray.DataArray` object, the default
+    CPT is ignored and GMT's default CPT (*turbo*) is used. To use the
+    dataset-specific CPT, you need to explicitly set ``cmap="@earth_faa.cpt"``.
+
     Refer to :gmt-datasets:`earth-faa.html` for more details.
 
     Parameters

pygmt/datasets/earth_magnetic_anomaly.py

@@ -33,6 +33,16 @@ def load_earth_magnetic_anomaly(
     (see below), and *reg* is grid registration type (**p** for pixel
     registration or **g** for gridline registration).
 
+    The default color palette tables (CPTs) for this dataset are
+    *@earth_mag.cpt* for ``data_source="emag2"`` and
+    ``data_source="emag2_4km"``, and *@earth_wdmam.cpt* for
+    ``data_source="wdmam"``. The dataset-specific CPT is implicitly used when
+    passing in the file name of the dataset to any grid plotting method if no
+    CPT is explicitly specified. When the dataset is loaded and plotted as an
+    :class:`xarray.DataArray` object, the default CPT is ignored and GMT's
+    default CPT (*turbo*) is used. To use the dataset-specific CPT, you need to
+    explicitly set ``cmap="@earth_mag.cpt"`` or ``cmap="@earth_wdmam.cpt"``.
+
     Refer to :gmt-datasets:`earth-mag.html`
     and :gmt-datasets:`earth-wdmam.html` for more details.
 

pygmt/datasets/earth_relief.py

@@ -37,6 +37,13 @@ def load_earth_relief(
     grid resolution (see below), and *reg* is grid registration type
     (**p** for pixel registration or **g** for gridline registration).
 
+    The default color palette table (CPT) for this dataset is *geo*.
+    It's implicitly used when passing in the file name of the dataset to any
+    grid plotting method if no CPT is explicitly specified. When the dataset
+    is loaded and plotted as an :class:`xarray.DataArray` object, the default
+    CPT is ignored and GMT's default CPT (*turbo*) is used. To use the
+    dataset-specific CPT, you need to explicitly set ``cmap="geo"``.
+
     Refer to :gmt-datasets:`earth-relief.html` for more details about available
     datasets, including version information and references.
 

pygmt/datasets/earth_vertical_gravity_gradient.py

@@ -29,6 +29,13 @@ def load_earth_vertical_gravity_gradient(
     registration type (**p** for pixel registration or **g** for gridline
     registration).
 
+    The default color palette table (CPT) for this dataset is *@earth_vgg.cpt*.
+    It's implicitly used when passing in the file name of the dataset to any
+    grid plotting method if no CPT is explicitly specified. When the dataset
+    is loaded and plotted as an :class:`xarray.DataArray` object, the default
+    CPT is ignored and GMT's default CPT (*turbo*) is used. To use the
+    dataset-specific CPT, you need to explicitly set ``cmap="@earth_vgg.cpt"``.
+
     Refer to :gmt-datasets:`earth-vgg.html` for more details.
 
     Parameters