"""
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 build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
__doctest_skip__ = ["sphdistance"]
[docs]
@fmt_docstring
@use_alias(
C="single_form",
D="duplicate",
E="quantity",
I="spacing",
L="unit",
N="node_table",
Q="voronoi",
R="region",
V="verbose",
)
@kwargs_to_strings(I="sequence", R="sequence")
def sphdistance(
data=None, x=None, y=None, outgrid: str | None = None, **kwargs
) -> xr.DataArray | None:
r"""
Create Voronoi distance, node, or natural nearest-neighbor grid on a sphere.
Reads a table containing *lon, lat* columns 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.
Full option list at :gmt-docs:`sphdistance.html`
{aliases}
Parameters
----------
data : str, {table-like}
Pass in (x, y) or (longitude, latitude) values by
providing a file name to an ASCII data table, a 2-D
{table-classes}.
x/y : 1-D arrays
Arrays of x and y coordinates.
{outgrid}
{spacing}
{region}
{verbose}
single_form : bool
For large data sets you can save some memory (at the expense of more
processing) by only storing one form of location coordinates
(geographic or Cartesian 3-D vectors) at any given time, translating
from one form to the other when necessary [Default keeps both arrays
in memory]. Not applicable with ``voronoi``.
duplicate : bool
Used to skip duplicate points since the algorithm cannot handle them.
[Default assumes there are no duplicates].
quantity : str
**d**\|\ **n**\|\ **z**\ [*dist*].
Specify the quantity that should be assigned to the grid nodes [Default
is **d**]:
- **d** - compute distances to the nearest data point
- **n** - assign the ID numbers of the Voronoi polygons that each
grid node is inside
- **z** - assign all nodes inside the polygon the z-value of the center
node for a natural nearest-neighbor grid.
Optionally, append the resampling interval along Voronoi arcs in
spherical degrees.
unit : str
Specify the unit used for distance calculations. Choose among **d**
(spherical degrees), **e** (meters), **f** (feet), **k** (kilometers),
**M** (miles), **n** (nautical miles), or **u** (survey feet).
node_table : str
Read the information pertaining to each Voronoi
polygon (the unique node lon, lat and polygon area) from a separate
file [Default acquires this information from the ASCII segment
headers of the output file]. Required if binary input via `voronoi`
is used.
voronoi : str
Append the name of a file with pre-calculated Voronoi polygons
[Default performs the Voronoi construction on input data].
Returns
-------
ret
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``)
Example
-------
>>> import numpy as np
>>> import pygmt
>>> # Create an array of longitude/latitude coordinates
>>> coords_list = [[85.5, 22.3], [82.3, 22.6], [85.8, 22.4], [86.5, 23.3]]
>>> coords_array = np.array(coords_list)
>>> # Perform a calculation of the distance to
>>> # each point from Voronoi polygons
>>> grid = pygmt.sphdistance(
... data=coords_array, spacing=[1, 2], region=[82, 87, 22, 24]
... )
"""
if kwargs.get("I") is None or kwargs.get("R") is None:
raise GMTInvalidInput("Both 'region' and 'spacing' must be specified.")
with Session() as lib:
with (
lib.virtualfile_in(check_kind="vector", data=data, x=x, y=y) as vintbl,
lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
):
kwargs["G"] = voutgrd
lib.call_module(
module="sphdistance", args=build_arg_list(kwargs, infile=vintbl)
)
return lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)