# triple2grid

Places unstructured (randomly-spaced) data onto the nearest locations of a rectilinear grid.

## Prototype

function triple2grid ( x [*] : numeric, y [*] : numeric, data : numeric, xgrid [*] : numeric, ygrid [*] : numeric, option [1] : logical ) return_val [dimsizes(ygrid)][dimsizes(xgrid)] : float or double

## Arguments

*x*

*y*

One-dimensional arrays of the same length containing the coordinates
associated with the data values. For geophysical variables,
*x* and *y* correspond to longitude and latitude
respectively.

*data*

A multi-dimensional array, whose rightmost dimension is the same length
as *x* and *y*, containing the values associated with
the *x* and *y* coordinates. Missing values, indicated
via *data*@_FillValue, may be
present but will be ignored.

*xgrid*

A one-dimensional array of length *M* containing the *x*
coordinates associated with the returned two-dimensional grid. For
geophysical variables, these are longitudes. The coordinates' values
must be monotonically increasing.

*ygrid*

A one-dimensional array of length *N* containing the *y*
coordinates associated with the returned two-dimensional grid. For
geophysical variables, these are latitudes. The coordinates' values
must be monotonically increasing.

*option*

If *option*=False, this function will operate under default
mode with *domain* set to 1 and method set to 0.
**Warning**: *option*=False could result in many of the
target grid point to be set to _FillValue if the number of grid points
is large (ie: a high resolution grid) and the number of observations
relatively small.

If *option*=True, then this variable may have associated with
it the attributes *domain*, *method* and/or *distmx*.

*option*@*method*- An integer value that defaults to 1 if
*option*is True, and 0 otherwise. A value of*option*@*method*=1 means to use the great circle distance formula for distance calculations. *option*@*domain*- A float value that should be set to a value >= 0

(As of NCL V6.4.0, the default is 1.0. The default was previously set to 0.0).If present, the larger this factor the wider the spatial domain allowed to influence grid boundary points. Typically,

*option*@*domain*is 1.0 or 2.0. If*option*@*domain*<= 0.0, then values located outside the grid domain specified by*xgrid*and*ygrid*will not be used. *option*@*distmx*- Setting
*option*@*distmx*allows the user to specify a search radius**(km)**beyond which observations are not considered for nearest neighbor. Only applicable when*option*@*method*= 1. The default*distmx*=1e20 (km) means that every grid point will have a nearest neighbor. It is suggested that users specify some reasonable value for*distmx*.

## Return value

The return array will be *K* x *N* x *M*, where
*K* represents the leftmost dimensions of *data*. It
will be of type double if any of the input is double, and float
otherwise.

## Description

This function puts unstructured data (randomly-spaced) onto the nearest locations of a rectilinear grid.

Use the **triple2grid_Wrap** function if metadata retention is desired.
The interface is identical.

A bug was found in this function in NCL V6.3.0 and
earlier which caused the output grid to be shifted by one cell in some
cases. This bug was fixed in NCL V6.4.0; additionally, the default
value of *domain* option is now set to 1.0 instead of
0.0.

This function does *not* perform interpolation; rather, each
individual data point is assigned to the nearest grid point. It is
possible that upon return, *grid* will contain grid points set
to *data*@_FillValue if no
*x*(*n*),*y*(*n*) are nearby.

For more robust regridding, see the
ESMF regridding examples, which
show how to regrid data from and to rectilinear,
curvilinear, or
unstructured
grids. *Available in version 6.1.0 and later.*

## See Also

**triple2grid_Wrap**,
**ESMF_regrid**,
**obj_anal_ic**,
**obj_anal_ic_Wrap**,
**triple2grid2d**,
**grid2triple**, **natgrid**,
**poisson_grid_fill**

## Examples

**Example 1**

Assume *xlon*, *ylat* and *zVal* are one-dimensional
(1D) arrays of length *KPTS*. Let *lon* and *lat*
be 1D arrays specifying grid locations. Then:

grid =triple2grid(xlon,ylat,zVal, lon,lat, False) ; Use triple2grid_Wrap if metadata retention is desired ; grid =triple2grid_Wrap(xlon,ylat,zVal, lon,lat, False)

Generally, *opt*=False is **not** recommended unless there input triplet has a
**large** number of points.

**Example 2**

Same as Example 1 but observations within 275 km of a grid point will be considered as a "nearest neighbor". The great circle distance formula will be used to calculate distances.

opt = True ; method=1 and domain=1 are set (domain was set to 0 in NCL V6.3.0 and earlier) opt@distmx = 275 ; kilometers grid =triple2grid(xlon,ylat,zVal, lon,lat, opt) ; Use triple2grid_Wrap if metadata retention is desired ; grid =triple2grid_Wrap(xlon,ylat,zVal, lon,lat, opt)