Source code for pygmt.src.grdsample

"""
grdsample - Resample a grid onto a new lattice
"""

import xarray as xr
from pygmt.clib import Session
from pygmt.helpers import (
    GMTTempFile,
    build_arg_string,
    fmt_docstring,
    kwargs_to_strings,
    use_alias,
)


[docs]@fmt_docstring @use_alias( G="outgrid", J="projection", I="increment", R="region", T="translate", V="verbose", f="coltypes", r="registration", n="interpolation", x="cores", ) @kwargs_to_strings(I="sequence", R="sequence") def grdsample(grid, **kwargs): r""" Change the registration, spacing, or nodes in a grid file. This reads a grid file and interpolates it to create a new grid file. It can change the registration with ``translate`` or ``registration``, change the grid-spacing or number of nodes with ``increment``, and set a new sub-region using ``region``. A bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is set with ``interpolation``. When ``region`` is omitted, the output grid will cover the same region as the input grid. When ``increment`` is omitted, the grid spacing of the output grid will be the same as the input grid. Either ``registration`` or ``translate`` can be used to change the grid registration. When omitted, the output grid will have the same registration as the input grid. {aliases} Parameters ---------- grid : str or xarray.DataArray The file name of the input grid or the grid loaded as a DataArray. outgrid : str or None The name of the output netCDF file with extension .nc to store the grid in. {I} {R} translate : bool Translate between grid and pixel registration; if the input is grid-registered, the output will be pixel-registered and vice-versa. interpolation : str [**b**\|\ **c**\|\ **l**\|\ **n**][**+a**][**+b**\ *BC*][**+c**] [**+t**\ *threshold*]. Select interpolation mode for grids. - **b** to use B-spline smoothing. - **c** to use bicubic interpolation. - **l** to use bilinear interpolation. - **n** to use nearest-neighbor value (for example to plot categorical data). The following modifiers are supported: - **+a** to switch off antialiasing (where supported) [default uses antialiasing]. - **+b** to override boundary conditions used, by appending *g* for geographic, *p* for periodic, or *n* for natural boundary conditions. For the latter two you may append **x** or **y** to specify just one direction, otherwise both are assumed. - **+c** to clip the interpolated grid to input z-min/z-max [default may exceed limits]. - **+t** to control how close to nodes with NaNs the interpolation will go based on *threshold*. A *threshold* of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN. For example, 0.5 will interpolate about half way from a non-NaN value and 0.1 will go about 90% of the way [default is 0.5]. registration : str or bool [**g**\ |\ **p**\ ]. Set registration to **g**\ ridline or **p**\ ixel. {V} {f} {x} Returns ------- ret: xarray.DataArray or None Return type depends on whether the ``outgrid`` parameter is set: - :class:`xarray.DataArray` if ``outgrid`` is not set - None if ``outgrid`` is set (grid output will be stored in file set by ``outgrid``) """ with GMTTempFile(suffix=".nc") as tmpfile: with Session() as lib: file_context = lib.virtualfile_from_data(check_kind="raster", data=grid) with file_context as infile: if "G" not in kwargs.keys(): # if outgrid is unset, output to tempfile kwargs.update({"G": tmpfile.name}) outgrid = kwargs["G"] arg_str = " ".join([infile, build_arg_string(kwargs)]) lib.call_module("grdsample", arg_str) if outgrid == tmpfile.name: # if user did not set outgrid, return DataArray with xr.open_dataarray(outgrid) as dataarray: result = dataarray.load() _ = result.gmt # load GMTDataArray accessor information else: result = None # if user sets an outgrid, return None return result