pygmt.surface(x=None, y=None, z=None, data=None, **kwargs)[source]

Grids table data using adjustable tension continuous curvature splines.

Surface reads randomly-spaced (x,y,z) triples and produces gridded values z(x,y) by solving:

\[(1 - t)\nabla^2(z)+t\nabla(z) = 0\]

where \(t\) is a tension factor between 0 and 1, and \(\nabla\) indicates the Laplacian operator.

Takes a matrix, xyz triples, or a file name as input.

Must provide either data or x, y, and z.

Full option list at


  • G = outfile

  • I = spacing

  • R = region

  • V = verbose

  • f = coltypes

  • x/y/z (1d arrays) – Arrays of x and y coordinates and values z of the data points.

  • data (str or 2d array) – Either a data file name or a 2d numpy array with the tabular data.

  • spacing (str) – xinc[unit][+e|n][/yinc[unit][+e|n]]. xinc [and optionally yinc] is the grid spacing.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • outfile (str) – Optional. The file name for the output netcdf file with extension .nc to store the grid in.

  • verbose (bool or str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorithms);

    • i - Informational messages (same as verbose=True)

    • c - Compatibility warnings

    • d - Debugging messages

  • coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at


ret (xarray.DataArray or None) – Return type depends on whether the outfile parameter is set:

  • xarray.DataArray: if outfile is not set

  • None if outfile is set (grid output will be stored in file set by outfile)