"""surface - Grids table data using adjustable tension continuous curvaturesplines."""importxarrayasxrfrompygmt.clibimportSessionfrompygmt.exceptionsimportGMTInvalidInputfrompygmt.helpersimport(GMTTempFile,build_arg_string,data_kind,dummy_context,fmt_docstring,kwargs_to_strings,use_alias,)
[docs]@fmt_docstring@use_alias(I="spacing",R="region",G="outfile",V="verbose",a="aspatial",f="coltypes",r="registration",)@kwargs_to_strings(R="sequence")defsurface(x=None,y=None,z=None,data=None,**kwargs):r""" 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: .. math:: (1 - t)\nabla^2(z)+t\nabla(z) = 0 where :math:`t` is a tension factor between 0 and 1, and :math:`\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 :gmt-docs:`surface.html` {aliases} Parameters ---------- 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. {I} region : str or list *xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*]. Specify the region of interest. outfile : str Optional. The file name for the output netcdf file with extension .nc to store the grid in. {V} {a} {f} {r} Returns ------- ret: xarray.DataArray or None Return type depends on whether the ``outfile`` parameter is set: - :class:`xarray.DataArray`: if ``outfile`` is not set - None if ``outfile`` is set (grid output will be stored in file set by ``outfile``) """kind=data_kind(data,x,y,z)ifkind=="vectors"andzisNone:raiseGMTInvalidInput("Must provide z with x and y.")withGMTTempFile(suffix=".nc")astmpfile:withSession()aslib:ifkind=="file":file_context=dummy_context(data)elifkind=="matrix":file_context=lib.virtualfile_from_matrix(data)elifkind=="vectors":file_context=lib.virtualfile_from_vectors(x,y,z)else:raiseGMTInvalidInput("Unrecognized data type: {}".format(type(data)))withfile_contextasinfile:if"G"notinkwargs.keys():# if outfile is unset, output to tmpfilekwargs.update({"G":tmpfile.name})outfile=kwargs["G"]arg_str=" ".join([infile,build_arg_string(kwargs)])lib.call_module(module="surface",args=arg_str)ifoutfile==tmpfile.name:# if user did not set outfile, return DataArraywithxr.open_dataarray(outfile)asdataarray:result=dataarray.load()_=result.gmt# load GMTDataArray accessor informationelifoutfile!=tmpfile.name:# if user sets an outfile, return Noneresult=Nonereturnresult