22grdfill - Interpolate across holes in a grid.
33"""
44
5+ import warnings
6+
57import xarray as xr
68from pygmt .clib import Session
79from pygmt .exceptions import GMTInvalidInput
1618__doctest_skip__ = ["grdfill" ]
1719
1820
21+ def _parse_fill_mode (
22+ constantfill = None , gridfill = None , neighborfill = None , splinefill = None
23+ ) -> str | None :
24+ """
25+ Parse the fill parameters and return the appropriate string for the -A option.
26+
27+ >>> import numpy as np
28+ >>> import xarray as xr
29+ >>> _parse_fill_mode(constantfill=20.0)
30+ 'c20.0'
31+ >>> _parse_fill_mode(gridfill="bggrid.nc")
32+ 'g'
33+ >>> _parse_fill_mode(gridfill=xr.DataArray(np.zeros((10, 10))))
34+ 'g'
35+ >>> _parse_fill_mode(neighborfill=20)
36+ 'n20'
37+ >>> _parse_fill_mode(neighborfill=True)
38+ 'n'
39+ >>> _parse_fill_mode(splinefill=0.5)
40+ 's0.5'
41+ >>> _parse_fill_mode(splinefill=True)
42+ 's'
43+ >>> _parse_fill_mode(constantfill=20, gridfill="bggrid.nc")
44+ Traceback (most recent call last):
45+ ...
46+ pygmt.exceptions.GMTInvalidInput: The ... parameters are mutually exclusive.
47+ """
48+ fill_params = [constantfill , gridfill , neighborfill , splinefill ]
49+ if sum (param is not None for param in fill_params ) > 1 :
50+ msg = (
51+ "The 'constantfill', 'gridfill', 'neighborfill', and 'splinefill' "
52+ "parameters are mutually exclusive."
53+ )
54+ raise GMTInvalidInput (msg )
55+
56+ if constantfill is not None :
57+ return f"c{ constantfill }
58+ if gridfill is not None :
59+ return "g" # Append grid file name later to support xarray.DataArray.
60+ if neighborfill is not None and neighborfill is not False :
61+ return "n" if neighborfill is True else f"n{ neighborfill }
62+ if splinefill is not None and splinefill is not False :
63+ return "s" if splinefill is True else f"s{ splinefill }
64+ return None
65+
66+
1967@fmt_docstring
2068# TODO(PyGMT>=0.19.0): Remove the deprecated 'no_data' parameter.
2169@deprecate_parameter ("no_data" , "hole" , "v0.15.0" , remove_version = "v0.19.0" )
22- @use_alias (A = "mode" , N = "hole" , R = "region" , V = "verbose" )
70+ @use_alias (A = "mode" , N = "hole" , R = "region" , V = "verbose" , f = "coltypes" )
2371@kwargs_to_strings (R = "sequence" )
24- def grdfill (grid , outgrid : str | None = None , ** kwargs ) -> xr .DataArray | None :
72+ def grdfill (
73+ grid : str | xr .DataArray ,
74+ outgrid : str | None = None ,
75+ constantfill : float | None = None ,
76+ gridfill : str | xr .DataArray | None = None ,
77+ neighborfill : float | bool | None = None ,
78+ splinefill : float | bool | None = None ,
79+ ** kwargs ,
80+ ) -> xr .DataArray | None :
2581 r"""
2682 Interpolate across holes in a grid.
2783
@@ -31,26 +87,42 @@ def grdfill(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
3187 replace the hole values. If no holes are found the original unchanged grid is
3288 returned.
3389
34- Full option list at :gmt-docs:`grdfill.html`
90+ Full option list at :gmt-docs:`grdfill.html`.
3591
3692 {aliases}
3793
3894 Parameters
3995 ----------
4096 {grid}
4197 {outgrid}
42- mode : str
43- Specify the hole-filling algorithm to use. Choose from **c** for
44- constant fill and append the constant value, **n** for nearest
45- neighbor (and optionally append a search radius in
46- pixels [default radius is :math:`r^2 = \sqrt{{ X^2 + Y^2 }}`,
47- where (*X,Y*) are the node dimensions of the grid]), or
48- **s** for bicubic spline (optionally append a *tension*
49- parameter [Default is no tension]).
98+ constantfill
99+ Fill the holes with a constant value. Specify the constant value to use.
100+ gridfill
101+ Fill the holes with values sampled from another (possibly coarser) grid. Specify
102+ the grid (a file name or an :class:`xarray.DataArray`) to use for the fill.
103+ neighborfill
104+ Fill the holes with the nearest neighbor. Specify the search radius in pixels.
105+ If set to ``True``, the default search radius will be used
106+ (:math:`r^2 = \sqrt{{n^2 + m^2}}`, where (*n,m*) are the node dimensions of the
107+ grid).
108+ splinefill
109+ Fill the holes with a bicubic spline. Specify the tension value to use. If set
110+ to ``True``, no tension will be used.
50111 hole : float
51112 Set the node value used to identify a point as a member of a hole [Default is
52113 NaN].
114+ mode : str
115+ Specify the hole-filling algorithm to use. Choose from **c** for constant fill
116+ and append the constant value, **n** for nearest neighbor (and optionally append
117+ a search radius in pixels [default radius is :math:`r^2 = \sqrt{{ X^2 + Y^2 }}`,
118+ where (*X,Y*) are the node dimensions of the grid]), or **s** for bicubic spline
119+ (optionally append a *tension* parameter [Default is no tension]).
120+
121+ .. deprecated:: 0.15.0
122+ Use ``constantfill``, ``gridfill``, ``neighborfill``, or ``splinefill``
123+ instead. The parameter will be removed in v0.19.0.
53124 {region}
125+ {coltypes}
54126 {verbose}
55127
56128 Returns
@@ -67,19 +139,37 @@ def grdfill(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
67139 >>> import pygmt
68140 >>> # Load a bathymetric grid with missing data
69141 >>> earth_relief_holes = pygmt.datasets.load_sample_data(name="earth_relief_holes")
70- >>> # Perform grid filling operations on the sample grid
71- >>> # Set all empty values to "20"
72- >>> filled_grid = pygmt.grdfill(grid=earth_relief_holes, mode="c20")
142+ >>> # Fill the holes with a constant value of 20
143+ >>> filled_grid = pygmt.grdfill(grid=earth_relief_holes, constantfill=20)
73144 """
145+ # TODO(PyGMT>=0.19.0): Remove the deprecated 'mode' parameter.
146+ if kwargs .get ("A" ) is not None : # The deprecated 'mode' parameter is given.
147+ warnings .warn (
148+ "The 'mode' parameter is deprecated since v0.15.0 and will be removed in "
149+ "v0.19.0. Use 'constantfill'/'gridfill'/'neighborfill'/'splinefill' "
150+ "instead." ,
151+ FutureWarning ,
152+ stacklevel = 1 ,
153+ )
154+ else :
155+ # Determine the -A option from the fill parameters.
156+ kwargs ["A" ] = _parse_fill_mode (constantfill , gridfill , neighborfill , splinefill )
157+
74158 if kwargs .get ("A" ) is None and kwargs .get ("L" ) is None :
75159 msg = "At least parameter 'mode' or 'L' must be specified."
76160 raise GMTInvalidInput (msg )
77161
78162 with Session () as lib :
79163 with (
80164 lib .virtualfile_in (check_kind = "raster" , data = grid ) as vingrd ,
165+ lib .virtualfile_in (
166+ check_kind = "raster" , data = gridfill , required_data = False
167+ ) as vbggrd ,
81168 lib .virtualfile_out (kind = "grid" , fname = outgrid ) as voutgrd ,
82169 ):
170+ if gridfill is not None :
171+ # Fill by a grid. Append the actual or virtual grid file name.
172+ kwargs ["A" ] = f"g{ vbggrd }
83173 kwargs ["G" ] = voutgrd
84174 lib .call_module (
85175 module = "grdfill" , args = build_arg_list (kwargs , infile = vingrd )
0 commit comments