NCL Home > Documentation > Functions > Regridding

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)