Source code for pygmt.src.sphdistance

"""
sphdistance - Create Voronoi distance, node,
or natural nearest-neighbor grid on a sphere
"""
import xarray as xr
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import (
    GMTTempFile,
    build_arg_string,
    data_kind,
    dummy_context,
    fmt_docstring,
    kwargs_to_strings,
    use_alias,
)


@fmt_docstring
@use_alias(
    G="outgrid",
    I="increment",
    R="region",
)
@kwargs_to_strings(I="sequence", R="sequence")
def sphdistance(table, **kwargs):
    r"""
    Create Voroni polygons from lat/long coordinates.

    Reads one or more ASCII [or binary] files (or standard
    input) containing lon, lat and performs the construction of Voronoi
    polygons. These polygons are then processed to calculate the nearest
    distance to each node of the lattice and written to the specified grid.

    {aliases}

    Parameters
    ----------
    outgrid : str or None
        The name of the output netCDF file with extension .nc to store the grid
        in.
    {I}
    {R}

    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``)
    """
    if "I" not in kwargs.keys() or "R" not in kwargs.keys():
        raise GMTInvalidInput("Both 'region' and 'increment' must be specified.")
    kind = data_kind(table)
    with GMTTempFile(suffix=".nc") as tmpfile:
        with Session() as lib:
            if kind == "file":
                file_context = dummy_context(table)
            elif kind == "matrix":
                file_context = lib.virtualfile_from_matrix(matrix=table)
            else:
                raise GMTInvalidInput("Unrecognized data type: {}".format(type(table)))
            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 = build_arg_string(kwargs)
                arg_str = " ".join([infile, arg_str])
                lib.call_module("sphdistance", 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