pygmt.sphinterpolate: Spherical gridding in tension of data on a sphere

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the pygmt.sphinterpolate function in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/sphinterpolate.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/sphinterpolate
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.sphinterpolate.html

GMT Option Flags and Modifiers

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• ☑️ -G (outgrid): Output grid file name.
• ☑️ -I (spacing): Grid spacing.
• ⬜ -Q mode: Specify one of four modes to determine how tension is computed: 0 (no tension), 1 (minimize the mean square second derivative), 2 (minimize the mean square Laplacian), 3 (minimize the total bending energy). Append tension to set a fixed tension value.
• ☑️ -R (region): Output grid region.
• ⬜ -T: Enforce that no values at the data points deviate from the input values (exact interpolation).
• ☑️ -V (verbose): Verbosity level.
• ⬜ -Z: Scale data by dividing by the range before interpolation; rescale output to original range afterwards. Helps when z-values have very large magnitudes.
• -X/-Y: Use Figure.shift_origin instead.
• ⬜ -b: Binary input/output.
• ⬜ -d: Replace NaN with a specified nodata value on input/output.
• ⬜ -e: Pattern matching to select input rows.
• ⬜ -f (coltypes): Column data types.
• ⬜ -g: Gap detection.
• ⬜ -h: Read/write header records.
• ⬜ -i: Select input columns.
• ⬜ -w: Wrap repeated cycles.
• --PAR=value: Use pygmt.config instead.

Notes on Input Formats

• data: Accepts a file path, 2-D numpy.ndarray, or pandas.DataFrame with (lon, lat, z) in the first three columns.
• outgrid: If not set, returns an xarray.DataArray; if set to a file path, writes the grid to disk and returns None.
• Both spacing and region are required parameters.
• sphinterpolate is specifically designed for global or near-global spherical data and handles the pole singularity correctly; for small-area or Cartesian data, use pygmt.surface instead.

Linked Pull Requests

• Initial feature implementation – Wrap sphinterpolate #1418
• Implement -Q (tension mode) option
• Implement -T (exact interpolation) option
• Implement -Z (z-value scaling) option
• Add common data I/O options (-b, -d, -e, -f, -g, -h, -i, -w)
• Add a gallery or tutorial example (e.g., gridding the Mars shape model from the sample dataset at 0.5-degree resolution with and without tension)

Related Issues and Discussions

• pygmt.sphinterpolate is the tension-capable global interpolator; pygmt.sphdistance with quantity="z" implements natural nearest-neighbour interpolation on the sphere, which does not require a smoothness parameter.
• The tension parameter (-Q) is critical for datasets with steep gradients (e.g., planetary topography); higher tension reduces oscillations but increases deviation from the input data.
• The PyGMT sample dataset mars_shape is a natural test case for sphinterpolate, as it provides global lon/lat/radius observations of the Martian surface.