NCL Home > Documentation > Functions > Interpolation, Ngmath routines

natgrid

Interpolates data from an unstructured (randomly-spaced) grid to a rectilinear grid using natural neighbor interpolation.

Prototype

	function natgrid (
		x  [*] : numeric,  
		y  [*] : numeric,  
		z      : numeric,  
		xo [*] : numeric,  
		yo [*] : numeric   
	)

	return_val  :  float or double

Arguments

x

An array of length npts containing the X coordinates of the input data points.

For lat/lon data, x represents the longitude values.

y

An array of length npts containing the Y coordinates of the input data points.

For lat/lon data, y represents the latitude values.

z

An array of any dimensionality (with the last dimension being npts) containing the functional values of the input data points. That is, z(...,i) is the value of the input function at coordinate (x(i),y(i)) for i=0,npts-1.

xo

A 1D array of any length (NumXOut) containing the X coordinates of the output data grid. The values in xo must be increasing, but need not be equally spaced.

For an output lat/lon grid, xo represents the output longitude values.

yo

A 1D array of any length (NumYOut) containing the Y coordinates of the output data grid. The values in yo must be increasing, but need not be equally spaced.

For an output lat/lon grid, yo represents the output latitude values.

Return value

An array of dimensions N x NumXOut x NumYOut, where N represents all but the last (rightmost) dimension of z, containing the interpolated functional values at the points specified by xo and yo.

If the rightmost two dimensions represent latitude and longitude, then they will be ordered longitude x latitude, which means you need to transpose them before plotting.

The output array will be of type double if any of the input is double, and float otherwise.

Description

This function performs interpolation from data on an unstructured grid to data on a rectilinear grid.

It is part of the Natgrid package, which implements a natural neighbor interpolation method. Much useful information is available at the above link, including the descriptions of many control parameters that can be modified to materially change the behavior of the package. (The functions nngetp and nnsetp are used to access these parameters.)

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

natgrid accepts a set of randomly-positioned 2D point coordinates, together with function values at those coordinates, and returns a set of interpolated function values at coordinates on a user-specified rectangular grid. No missing values are allowed in the input data arrays.

Natgrid culls duplicate points. If any of the x/y/z triples are duplicates, they will automatically be culled. Informational messages are printed indicating which points have been culled. There is an upper limit on the number of such messages, the default being ten. This limit can be adjusted using the control parameter "mdm"; setting "mdm" to zero suppresses all such messages. If two x/y coordinate pairs are duplicates, but the z values are distinct, then a fatal error is issued. The user needs to figure out how to handle such data.

natgrid allows the input arrays to be of any numeric type, but it coerces them to type double and calls the same double-precision code as natgridd. It is important to know this when deciding which of the functions that retrieve aspects and slopes (nngetaspectd, nngetaspects, nngetsloped, and nngetslopes) to call.

natgrid can be used to interpolate at a list of specified points. To do this one must first enter "specified-point mode" by calling nnpntinit, then calling nnpnt to do the interpolation, and finally calling nnpntend to exit "specified-point mode."

See Also

natgrid_Wrap, obj_anal_ic, obj_anal_ic_Wrap, triple2grid, triple2grid2d

Examples

Example 1

begin
  NumXOut = 21
  NumYOut = 21
  ISLIM = 6

  x = (/0.00, 1.00, 0.00, 1.00, 0.40, 0.75/)
  y = (/0.00, 0.00, 1.00, 1.00, 0.20, 0.65/)
  z = (/0.00, 0.00, 0.00, 0.00, 1.25, 0.80/)

  xc = 1.d/(NumXOut-1.) 
  xi = ispan(0,NumXOut-1,1) * xc

  yc = 1.d/(NumYOut-1.) 
  yi = ispan(0,NumYOut-1,1) * yc

  zi = natgrid(x, y, z, xi, yi)

  ; Use natgrid_Wrap if metadata retention is desired
  ; zi = natgrid_Wrap(x, y, z, xi, yi)
end
Example 2

Note that if you are working with lat/lon data, the return array from natgrid will be ordered longitude x latitude. You will need to transpose the data if you need latitude x longitude, or if you plan to plot it. 

  f    = addfile("slp_1988mm.nc", "r")
  Z    = f->slp(0,::-1,:)      ; natgrid requires monotonic increasing y [lat]

;---Generate N random values from the above
  dimz  = dimsizes( Z )
  nlat  = dimz(0)
  mlon  = dimz(1)

  N     = nlat*mlon
  iZ    = generate_unique_indices( N )
  trip  = grid2triple (Z&lon, Z&lat, Z) 

  dlon  = Z&lon(2)-Z&lon(1)
  reps  = random_uniform (-dlon, dlon, N)  ; minor location perturbations

  IOBS  = iZ(0:NOBS)   ; convenience
                       ; clarity only ... create explicit variables  
  rlon  = trip(0,IOBS) + reps(IOBS)  
  rlat  = trip(1,IOBS) + reps(IOBS(::-1))
  rZ    = trip(2,IOBS)

  rlon@units = "degrees_east"
  rlat@units = "degrees_north"

  zgrd  = natgrid_Wrap(rlon, rlat, rZ, Z&lon,Z&lat)    ;  longitude x latitude
  znat  = transpose(zgrd)                              ; latitude x longitude

Errors

If an error code is returned by natgrid, you can look up the meaning of the code in the Natgrid error table.