Merge branch 'main' into changelog-release

.github/workflows/check-links.yml

@@ -41,6 +41,7 @@ jobs:
           --exclude "^file://"
           --exclude "^https://docs.generic-mapping-tools.org/latest/%s$"
           --exclude "^https://docs.generic-mapping-tools.org/latest/%3Cmodule-name%3E.html$"
+          --exclude "^https://www.generic-mapping-tools.org/remote-datasets/%s$"
           --exclude "https://hackmd.io/@pygmt"
           --verbose
           "repository/**/*.rst"

doc/api/index.rst

@@ -124,6 +124,9 @@ Operations on tabular data
     sphdistance
     sphinterpolate
     surface
+    triangulate
+    triangulate.regular_grid
+    triangulate.delaunay_triples
     xyz2grd
 
 Operations on raster data

examples/gallery/embellishments/legend.py

@@ -19,7 +19,7 @@
     pen="faint",
     label="Apples",
 )
-fig.plot(data="@Table_5_11.txt", pen="1.5p,gray", label='"My lines"')
+fig.plot(data="@Table_5_11.txt", pen="1.5p,gray", label="My lines")
 fig.plot(data="@Table_5_11.txt", style="t0.15i", color="orange", label="Oranges")
 
 fig.legend(position="JTR+jTR+o0.2c", box=True)

pygmt/__init__.py

@@ -56,6 +56,7 @@
     sphdistance,
     sphinterpolate,
     surface,
+    triangulate,
     which,
     x2sys_cross,
     x2sys_init,

pygmt/datasets/earth_age.py

@@ -26,7 +26,7 @@ def load_earth_age(resolution="01d", region=None, registration=None):
     registration type (**p** for pixel registration or **g** for gridline
     registration).
 
-    Refer to :gmt-datasets:`earth_age.html` for more details.
+    Refer to :gmt-datasets:`earth-age.html` for more details.
 
     Parameters
     ----------
@@ -54,8 +54,8 @@ def load_earth_age(resolution="01d", region=None, registration=None):
         The Earth seafloor crustal age grid. Coordinates are latitude and
         longitude in degrees. Age is in millions of years (Myr).
 
-    Notes
-    -----
+    Note
+    ----
     The :class:`xarray.DataArray` grid doesn't support slice operation, for
     Earth seafloor crustal age with resolutions of 5 arc-minutes or higher,
     which are stored as smaller tiles.

pygmt/datasets/earth_relief.py

@@ -62,8 +62,8 @@ def load_earth_relief(resolution="01d", region=None, registration=None, use_srtm
         The Earth relief grid. Coordinates are latitude and longitude in
         degrees. Relief is in meters.
 
-    Notes
-    -----
+    Note
+    ----
     The :class:`xarray.DataArray` grid doesn't support slice operation, for
     Earth relief data with resolutions of 5 arc-minutes or higher, which are
     stored as smaller tiles.

pygmt/figure.py

@@ -235,10 +235,17 @@ def psconvert(self, icc_gray=False, **kwargs):
                 kwargs["N"] = "+i"
             else:
                 kwargs["N"] += "+i"
-        # allow for spaces in figure name
-        kwargs["F"] = f'"{kwargs.get("F")}"' if kwargs.get("F") else None
+
+        # Manually handle prefix -F argument so spaces aren't converted to \040
+        # by build_arg_string function. For more information, see
+        # https://github.com/GenericMappingTools/pygmt/pull/1487
+        try:
+            prefix_arg = f'-F"{kwargs.pop("F")}"'
+        except KeyError as err:
+            raise GMTInvalidInput("The 'prefix' must be specified.") from err
+
         with Session() as lib:
-            lib.call_module("psconvert", build_arg_string(kwargs))
+            lib.call_module("psconvert", f"{prefix_arg} {build_arg_string(kwargs)}")
 
     def savefig(
         self, fname, transparent=False, crop=True, anti_alias=True, show=False, **kwargs

pygmt/helpers/utils.py

@@ -120,7 +120,7 @@ def dummy_context(arg):
 
 
 def build_arg_string(kwargs):
-    """
+    r"""
     Transform keyword arguments into a GMT argument string.
 
     Make sure all arguments have been previously converted to a string
@@ -131,6 +131,11 @@ def build_arg_string(kwargs):
     same command line argument. For example, the kwargs entry ``'B': ['xa',
     'yaf']`` will be converted to ``-Bxa -Byaf`` in the argument string.
 
+    Note that spaces `` `` in arguments are converted to the equivalent octal
+    code ``\040``, except in the case of -J (projection) arguments where PROJ4
+    strings (e.g. "+proj=longlat +datum=WGS84") will have their spaces removed.
+    See https://github.com/GenericMappingTools/pygmt/pull/1487 for more info.
+
     Parameters
     ----------
     kwargs : dict
@@ -151,7 +156,7 @@ def build_arg_string(kwargs):
     ...             A=True,
     ...             B=False,
     ...             E=200,
-    ...             J="X4c",
+    ...             J="+proj=longlat +datum=WGS84",
     ...             P="",
     ...             R="1/2/3/4",
     ...             X=None,
@@ -160,7 +165,7 @@ def build_arg_string(kwargs):
     ...         )
     ...     )
     ... )
-    -A -E200 -JX4c -P -R1/2/3/4 -Z0
+    -A -E200 -J+proj=longlat+datum=WGS84 -P -R1/2/3/4 -Z0
     >>> print(
     ...     build_arg_string(
     ...         dict(
@@ -176,6 +181,16 @@ def build_arg_string(kwargs):
     Traceback (most recent call last):
       ...
     pygmt.exceptions.GMTInvalidInput: Unrecognized parameter 'watre'.
+    >>> print(
+    ...     build_arg_string(
+    ...         dict(
+    ...             B=["af", "WSne+tBlank Space"],
+    ...             F='+t"Empty  Spaces"',
+    ...             l="'Void Space'",
+    ...         ),
+    ...     )
+    ... )
+    -BWSne+tBlank\040Space -Baf -F+t"Empty\040\040Spaces" -l'Void\040Space'
     """
     gmt_args = []
 
@@ -185,11 +200,19 @@ def build_arg_string(kwargs):
         if kwargs[key] is None or kwargs[key] is False:
             pass  # Exclude arguments that are None and False
         elif is_nonstr_iter(kwargs[key]):
-            gmt_args.extend(f"-{key}{value}" for value in kwargs[key])
+            for value in kwargs[key]:
+                _value = str(value).replace(" ", r"\040")
+                gmt_args.append(rf"-{key}{_value}")
         elif kwargs[key] is True:
             gmt_args.append(f"-{key}")
         else:
-            gmt_args.append(f"-{key}{kwargs[key]}")
+            if key != "J":  # non-projection parameters
+                _value = str(kwargs[key]).replace(" ", r"\040")
+            else:
+                # special handling if key == "J" (projection)
+                # remove any spaces in PROJ4 string
+                _value = str(kwargs[key]).replace(" ", "")
+            gmt_args.append(rf"-{key}{_value}")
     return " ".join(sorted(gmt_args))
 
 

pygmt/src/__init__.py

@@ -47,6 +47,7 @@
 from pygmt.src.subplot import set_panel, subplot
 from pygmt.src.surface import surface
 from pygmt.src.text import text_ as text  # "text" is an argument within "text_"
+from pygmt.src.triangulate import triangulate
 from pygmt.src.velo import velo
 from pygmt.src.which import which
 from pygmt.src.wiggle import wiggle

pygmt/src/blockm.py

@@ -85,7 +85,7 @@ def _blockm(block_method, data, x, y, z, outfile, **kwargs):
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmean(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
     r"""
     Block average (x,y,z) data tables by mean estimation.
@@ -182,7 +182,7 @@ def blockmean(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmedian(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
     r"""
     Block average (x,y,z) data tables by median estimation.
@@ -270,7 +270,7 @@ def blockmedian(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
 def blockmode(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
     r"""
     Block average (x,y,z) data tables by mode estimation.

pygmt/src/config.py

@@ -55,7 +55,7 @@ def __init__(self, **kwargs):
                     self.old_defaults[key] = lib.get_default(key)
 
         # call gmt set to change GMT defaults
-        arg_str = " ".join([f"{key}={value}" for key, value in kwargs.items()])
+        arg_str = " ".join([f'{key}="{value}"' for key, value in kwargs.items()])
         with Session() as lib:
             lib.call_module("set", arg_str)
 

pygmt/src/contour.py

@@ -6,15 +6,13 @@
 from pygmt.helpers import (
     build_arg_string,
     check_data_input_order,
-    deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
 )
 
 
 @fmt_docstring
-@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
 @check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="annotation",

pygmt/src/grdfilter.py

@@ -26,7 +26,7 @@
     f="coltypes",
     r="registration",
 )
-@kwargs_to_strings(R="sequence")
+@kwargs_to_strings(I="sequence", R="sequence")
 def grdfilter(grid, **kwargs):
     r"""
     Filter a grid in the space (or time) domain.

pygmt/src/grdhisteq.py

@@ -141,7 +141,7 @@ def _grdhisteq(grid, output_type, **kwargs):
     def equalize_grid(
         grid,
         *,
-        outgrid=True,
+        outgrid=None,
         divisions=None,
         region=None,
         gaussian=None,
@@ -163,7 +163,7 @@ def equalize_grid(
         ----------
         grid : str or xarray.DataArray
             The file name of the input grid or the grid loaded as a DataArray.
-        outgrid : str or bool or None
+        outgrid : str or None
             The name of the output netCDF file with extension .nc to store the
             grid in.
         divisions : int
@@ -183,7 +183,7 @@ def equalize_grid(
         ret: xarray.DataArray or None
             Return type depends on the ``outgrid`` parameter:
 
-            - xarray.DataArray if ``outgrid`` is True or None
+            - xarray.DataArray if ``outgrid`` is None
             - None if ``outgrid`` is a str (grid output is stored in
               ``outgrid``)
 
@@ -202,18 +202,20 @@ def equalize_grid(
         -------
         :meth:`pygmt.grd2cpt`
 
-        Notes
-        -----
+        Note
+        ----
         This method does a weighted histogram equalization for geographic
         grids to account for node area varying with latitude.
         """
         # Return an xarray.DataArray if ``outgrid`` is not set
         with GMTTempFile(suffix=".nc") as tmpfile:
             if isinstance(outgrid, str):
                 output_type = "file"
-            else:
+            elif outgrid is None:
                 output_type = "xarray"
                 outgrid = tmpfile.name
+            else:
+                raise GMTInvalidInput("Must specify 'outgrid' as a string or None.")
             return grdhisteq._grdhisteq(
                 grid=grid,
                 output_type=output_type,
@@ -281,12 +283,13 @@ def compute_bins(
 
         Returns
         -------
-        ret: pandas.DataFrame or None
-            Return type depends on the ``outfile`` parameter:
+        ret : pandas.DataFrame or numpy.ndarray or None
+            Return type depends on ``outfile`` and ``output_type``:
 
-            - pandas.DataFrame if ``outfile`` is True or None
-            - None if ``outfile`` is a str (file output is stored in
+            - None if ``outfile`` is set (output will be stored in file set by
               ``outfile``)
+            - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if
+              ``outfile`` is not set (depends on ``output_type``)
 
         Example
         -------
@@ -312,8 +315,8 @@ def compute_bins(
         -------
         :meth:`pygmt.grd2cpt`
 
-        Notes
-        -----
+        Note
+        ----
         This method does a weighted histogram equalization for geographic
         grids to account for node area varying with latitude.
         """

pygmt/src/grdlandmask.py

@@ -27,7 +27,7 @@
     V="verbose",
     r="registration",
 )
-@kwargs_to_strings(R="sequence", N="sequence", E="sequence")
+@kwargs_to_strings(I="sequence", R="sequence", N="sequence", E="sequence")
 def grdlandmask(**kwargs):
     r"""
     Create a grid file with set values for land and water.

pygmt/src/grdproject.py

@@ -30,7 +30,7 @@
     n="interpolation",
     r="registration",
 )
-@kwargs_to_strings(C="sequence", R="sequence")
+@kwargs_to_strings(C="sequence", D="sequence", R="sequence")
 def grdproject(grid, **kwargs):
     r"""
     Change projection of gridded data between geographical and rectangular.

pygmt/src/nearneighbor.py

@@ -33,7 +33,7 @@
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma")
+@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma")
 def nearneighbor(data=None, x=None, y=None, z=None, **kwargs):
     r"""
     Grid table data using a "Nearest neighbor" algorithm

pygmt/src/plot.py

@@ -7,7 +7,6 @@
     build_arg_string,
     check_data_input_order,
     data_kind,
-    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -17,8 +16,6 @@
 
 
 @fmt_docstring
-@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
-@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
 @check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="straight_line",

pygmt/src/plot3d.py

@@ -7,7 +7,6 @@
     build_arg_string,
     check_data_input_order,
     data_kind,
-    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -17,8 +16,6 @@
 
 
 @fmt_docstring
-@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
-@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
 @check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="straight_line",

pygmt/src/rose.py

@@ -6,15 +6,13 @@
 from pygmt.helpers import (
     build_arg_string,
     check_data_input_order,
-    deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
 )
 
 
 @fmt_docstring
-@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
 @check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="sector",