Rephrase the documentation for dataset loading functions (#3838)

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

Author: seisman

pygmt/datasets/earth_age.py

@@ -30,26 +30,29 @@ def load_earth_age(
 
        Earth seafloor crustal age dataset.
 
-    The grids are downloaded to a user data directory
-    (usually ``~/.gmt/server/earth/earth_age/``) the first time you invoke
-    this function. Afterwards, it will load the grid from the data directory.
-    So you'll need an internet connection the first time around.
-
-    These grids can also be accessed by passing in the file name
-    **@earth_age**\_\ *res*\[_\ *reg*] to any grid processing function or
-    plotting method. *res* is the grid resolution (see below), and *reg* is
-    the grid registration type (**p** for pixel registration or **g** for
-    the 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 about available
-    datasets, including version information and references.
+    This function downloads the dataset from the GMT data server, caches it in a user
+    data directory (usually ``~/.gmt/server/earth/earth_age/``), and load the dataset as
+    an :class:`xarray.DataArray`. An internet connection is required the first time
+    around, but subsequent calls will load the dataset from the local data directory.
+
+    The dataset can also be accessed by specifying a file name in any grid processing
+    function or plotting method, using the following file name format:
+    **@earth_age**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
+    registration type (**p** for pixel registration, **g** for gridline registration).
+    If *reg* is omitted (e.g., ``@earth_age_01d``), the gridline-registered grid will be
+    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    for plotting functions. If *res* is also omitted (i.e., ``@earth_age``), GMT
+    automatically selects a suitable resolution based on the current region and
+    projection settings.
+
+    This dataset comes with a color palette table (CPT) file, ``@earth_age.cpt``. To use
+    the dataset-specific CPT when plotting the dataset, explicitly set
+    ``cmap="@earth_age.cpt"``, otherwise GMT's default CPT (*turbo*) will be used. If
+    the dataset is referenced by the file name in a grid plotting method, the
+    dataset-specific CPT file is used automatically unless another CPT is specified.
+
+    Refer to :gmt-datasets:`earth-age.html` for more details about available datasets,
+    including version information and references.
 
     Parameters
     ----------
@@ -67,29 +70,28 @@ def load_earth_age(
     Returns
     -------
     grid
-        The Earth seafloor crustal age grid. Coordinates are latitude and
-        longitude in degrees. Age is in millions of years (Myr).
+        The Earth seafloor crustal age grid. Coordinates are latitude and longitude in
+        degrees. Age is in millions of years (Myr).
 
     Note
     ----
     The registration and coordinate system type of the returned
-    :class:`xarray.DataArray` grid can be accessed via the GMT accessors
-    (i.e., ``grid.gmt.registration`` and ``grid.gmt.gtype`` respectively).
-    However, these properties may be lost after specific grid operations (such
-    as slicing) and will need to be manually set before passing the grid to any
-    PyGMT data processing or plotting functions. Refer to
-    :class:`pygmt.GMTDataArrayAccessor` for detailed explanations and
-    workarounds.
+    :class:`xarray.DataArray` grid can be accessed via the GMT accessors (i.e.,
+    ``grid.gmt.registration`` and ``grid.gmt.gtype`` respectively). However, these
+    properties may be lost after specific grid operations (such as slicing) and will
+    need to be manually set before passing the grid to any PyGMT data processing or
+    plotting functions. Refer to :class:`pygmt.GMTDataArrayAccessor` for detailed
+    explanations and workarounds.
 
     Examples
     --------
 
     >>> from pygmt.datasets import load_earth_age
-    >>> # load the default grid (gridline-registered 1 arc-degree grid)
+    >>> # Load the default grid (gridline-registered 1 arc-degree grid)
     >>> grid = load_earth_age()
-    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> # Load the 30 arc-minutes grid with "gridline" registration
     >>> grid = load_earth_age(resolution="30m", registration="gridline")
-    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> # Load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_age(
     ...     resolution="05m",
     ...     region=[120, 160, 30, 60],

pygmt/datasets/earth_day.py

@@ -45,14 +45,17 @@ def load_blue_marble(
 
        Earth day/night dataset.
 
-    The images are downloaded to a user data directory (usually
-    ``~/.gmt/server/earth/earth_day/``) the first time you invoke this function.
-    Afterwards, it will load the image from the data directory. So you'll need an
-    internet connection the first time around.
 
-    These images can also be accessed by passing in the file name
-    **@earth_day**\_\ *res* to any image processing function or plotting method. *res*
-    is the image resolution (see below).
+    This function downloads the dataset from the GMT data server, caches it in a user
+    data directory (usually ``~/.gmt/server/earth/earth_day/``), and load the dataset as
+    an :class:`xarray.DataArray`. An internet connection is required the first time
+    around, but subsequent calls will load the dataset from the local data directory.
+
+    The dataset can also be accessed by specifying a file name in any image processing
+    function or plotting method, using the following file name format:
+    **@earth_day**\_\ *res*. *res* is the image resolution. If *res* is omitted (i.e.,
+    ``@earth_day``), GMT automatically selects a suitable resolution based on the
+    current region and projection settings.
 
     Refer to :gmt-datasets:`earth-daynight.html` for more details about available
     datasets, including version information and references.
@@ -85,7 +88,7 @@ def load_blue_marble(
     --------
 
     >>> from pygmt.datasets import load_blue_marble
-    >>> # load the default image (pixel-registered 1 arc-degree image)
+    >>> # Load the default image (pixel-registered 1 arc-degree image)
     >>> image = load_blue_marble()
     """
     image = _load_remote_dataset(

pygmt/datasets/earth_deflection.py

@@ -35,24 +35,29 @@ def load_earth_deflection(
        * - .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_earth_edefl.jpg
          - .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_earth_ndefl.jpg
 
-    The grids are downloaded to a user data directory (usually
-    ``~/.gmt/server/earth/earth_edefl/`` and ``~/.gmt/server/earth/earth_ndefl/`` the
-    first time you invoke this function. Afterwards, it will load the grid from the
-    data directory. So you'll need an internet connection the first time around.
-
-    These grids can also be accessed by passing in the file name
-    **@**\ *earth_defl_type*\_\ *res*\[_\ *reg*] to any grid processing function or
-    plotting method. *earth_defl_type* is the GMT name for the dataset. The available
-    options are **earth_edefl** and **earth_ndefl**. *res* is the grid resolution (see
-    below), and *reg* is the grid registration type (**p** for pixel registration or
-    **g** for gridline registration).
-
-    The default color palette table (CPTs) for this dataset is *@earth_defl.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_defl.cpt"``.
+
+    This function downloads the dataset from the GMT data server, caches it in a user
+    data directory (usually ``~/.gmt/server/earth/earth_edefl/`` and
+    ``~/.gmt/server/earth/earth_ndefl/``), and load the dataset as an
+    :class:`xarray.DataArray`. An internet connection is required the first time around,
+    but subsequent calls will load the dataset from the local data directory.
+
+    The datasets can also be accessed by specifying a file name in any grid processing
+    function or plotting method, using the following file name format:
+    **@**\ *earth_defl_type*\_\ *res*\_\ *reg*. *earth_defl_type* is the GMT name for
+    the dataset. The available options are **earth_edefl** and **earth_ndefl**; *res* is
+    the grid resolution; *reg* is the grid registration type (**p** for pixel
+    registration, **g** for gridline registration). If *reg* is omitted (e.g.,
+    ``@earth_edefl_01d``), the gridline-registered grid will be loaded for grid
+    proccessing functions and the pixel-registered grid will be loaded for plotting
+    functions. If *res* is also omitted (i.e., ``@earth_edefl``), GMT automatically
+    selects a suitable resolution based on the current region and projection settings.
+
+    This dataset comes with a color palette table (CPT) file, ``@earth_defl.cpt``. To
+    use the dataset-specific CPT when plotting the dataset, explicitly set
+    ``cmap="@earth_defl.cpt"``, otherwise GMT's default CPT (*turbo*) will be used. If
+    the dataset is referenced by the file name in a grid plotting method, the
+    dataset-specific CPT file is used automatically unless another CPT is specified.
 
     Refer to :gmt-datasets:`earth-edefl.html` and :gmt-datasets:`earth-ndefl.html` for
     more details about available datasets, including version information and references.
@@ -96,14 +101,14 @@ def load_earth_deflection(
     --------
 
     >>> from pygmt.datasets import load_earth_deflection
-    >>> # load the default grid for east-west deflection (gridline-registered
+    >>> # Load the default grid for east-west deflection (gridline-registered
     >>> # 1 arc-degree grid)
     >>> grid = load_earth_deflection()
-    >>> # load the default grid for north-south deflection
+    >>> # Load the default grid for north-south deflection
     >>> grid = load_earth_deflection(component="north")
-    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> # Load the 30 arc-minutes grid with "gridline" registration
     >>> grid = load_earth_deflection(resolution="30m", registration="gridline")
-    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> # Load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_deflection(
     ...     resolution="05m", region=[120, 160, 30, 60], registration="gridline"
     ... )

pygmt/datasets/earth_dist.py

@@ -30,22 +30,26 @@ def load_earth_dist(
 
        GSHHG Earth distance to shoreline dataset.
 
-    The grids are downloaded to a user data directory (usually
-    ``~/.gmt/server/earth/earth_dist/``) the first time you invoke this function.
-    Afterwards, it will load the grid from the data directory. So you'll need an
-    internet connection the first time around.
-
-    These grids can also be accessed by passing in the file name
-    **@earth_dist**\_\ *res*\[_\ *reg*] to any grid processing function or plotting
-    method. *res* is the grid resolution (see below), and *reg* is the grid registration
-    type (**p** for pixel registration or **g** for gridline registration).
-
-    The default color palette table (CPT) for this dataset is *@earth_dist.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_dist.cpt"``.
+    This function downloads the dataset from the GMT data server, caches it in a user
+    data directory (usually ``~/.gmt/server/earth/earth_dist/``), and load the dataset
+    as an :class:`xarray.DataArray`. An internet connection is required the first time
+    around, but subsequent calls will load the dataset from the local data directory.
+
+    The dataset can also be accessed by specifying a file name in any grid processing
+    function or plotting method, using the following file name format:
+    **@earth_dist**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
+    registration type (**p** for pixel registration, **g** for gridline registration).
+    If *reg* is omitted (e.g., ``@earth_dist_01d``), the gridline-registered grid will
+    be loaded for grid proccessing functions and the pixel-registered grid will be
+    loaded for plotting functions. If *res* is also omitted (i.e., ``@earth_dist``), GMT
+    automatically selects a suitable resolution based on the current region and
+    projection settings.
+
+    This dataset comes with a color palette table (CPT) file, ``@earth_dist.cpt``. To
+    use the dataset-specific CPT when plotting the dataset, explicitly set
+    ``cmap="@earth_dist.cpt"``, otherwise GMT's default CPT (*turbo*) will be used. If
+    the dataset is referenced by the file name in a grid plotting method, the
+    dataset-specific CPT file is used automatically unless another CPT is specified.
 
     Refer to :gmt-datasets:`earth-dist.html` for more details about available datasets,
     including version information and references.
@@ -84,11 +88,11 @@ def load_earth_dist(
     --------
 
     >>> from pygmt.datasets import load_earth_dist
-    >>> # load the default grid (gridline-registered 1 arc-degree grid)
+    >>> # Load the default grid (gridline-registered 1 arc-degree grid)
     >>> grid = load_earth_dist()
-    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> # Load the 30 arc-minutes grid with "gridline" registration
     >>> grid = load_earth_dist(resolution="30m", registration="gridline")
-    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> # Load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_dist(
     ...     resolution="05m",
     ...     region=[120, 160, 30, 60],

pygmt/datasets/earth_free_air_anomaly.py

@@ -35,25 +35,30 @@ def load_earth_free_air_anomaly(
        * - .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_earth_faa.jpg
          - .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_earth_faaerror.jpg
 
-    The grids are downloaded to a user data directory (usually
-    ``~/.gmt/server/earth/earth_faa/`` or ``~/.gmt/server/earth/earth_faaerror/``) the
-    first time you invoke this function. Afterwards, it will load the grid from data
-    directory. So you'll need an internet connection the first time around.
-
-    These grids can also be accessed by passing in the file name
-    **@earth_faa_type**\_\ *res*\[_\ *reg*] to any grid processing function or
-    plotting method. *earth_faa_type* is the GMT name for the dataset. The available
-    options are **earth_faa** and **earth_faaerror**. *res* is the grid resolution (see
-    below), and *reg* is the grid registration type (**p** for pixel registration or
-    **g** for gridline registration).
-
-    The default color palette tables (CPTs) for these datasets are *@earth_faa.cpt* and
-    *@earth_faaerror.cpt*. 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_faa.cpt"`` or
-    ``cmap="@earth_faaerror.cpt"``.
+
+    This function downloads the dataset from the GMT data server, caches it in a user
+    data directory (usually ``~/.gmt/server/earth/earth_faa/`` or
+    ``~/.gmt/server/earth/earth_faaerror/``), and load the dataset as an
+    :class:`xarray.DataArray`. An internet connection is required the first time around,
+    but subsequent calls will load the dataset from the local data directory.
+
+    The dataset can also be accessed by specifying a file name in any grid processing
+    function or plotting method, using the following file name format:
+    **@**\ *earth_faa_type*\_\ *res*\_\ *reg*. *earth_faa_type* is the GMT name for the
+    dataset. The available options are **earth_faa** and **earth_faaerror**. *res* is
+    the grid resolution; *reg* is the grid registration type (**p** for pixel
+    registration, **g** for gridline registration). If *reg* is omitted (e.g.,
+    ``@earth_faa_01d``), the gridline-registered grid will be loaded for grid
+    proccessing functions and the pixel-registered grid will be loaded for plotting
+    functions. If *res* is also omitted (i.e., ``@earth_faa``), GMT automatically
+    selects a suitable resolution based on the current region and projection settings.
+
+    This dataset comes with two color palette table (CPT) files, ``@earth_faa.cpt`` and
+    ``@earth_faaerror.cpt``. To use the dataset-specific CPT when plotting the dataset,
+    explicitly set ``cmap="@earth_faa.cpt"`` or ``cmap="@earth_faaerror.cpt"``,
+    otherwise GMT's default CPT (*turbo*) will be used. If the dataset is referenced by
+    the file name in a grid plotting method, the dataset-specific CPT file is used
+    automatically unless another CPT is specified.
 
     Refer to :gmt-datasets:`earth-faa.html` and :gmt-datasets:`earth-faaerror.html` for
     more details about available datasets, including version information and references.
@@ -96,13 +101,13 @@ def load_earth_free_air_anomaly(
     --------
 
     >>> from pygmt.datasets import load_earth_free_air_anomaly
-    >>> # load the default grid (gridline-registered 1 arc-degree grid)
+    >>> # Load the default grid (gridline-registered 1 arc-degree grid)
     >>> grid = load_earth_free_air_anomaly()
-    >>> # load the uncertainties related to the default grid
+    >>> # Load the uncertainties related to the default grid
     >>> grid = load_earth_free_air_anomaly(uncertainty=True)
-    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> # Load the 30 arc-minutes grid with "gridline" registration
     >>> grid = load_earth_free_air_anomaly(resolution="30m", registration="gridline")
-    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> # Load high-resolution (5 arc-minutes) grid for a specific region
     >>> grid = load_earth_free_air_anomaly(
     ...     resolution="05m", region=[120, 160, 30, 60], registration="gridline"
     ... )