NCL Home > Documentation > Functions > Array manipulators

conform

Expands an array or scalar so that it conforms to the shape of the given variable.

Prototype

	function conform (
		x     ,           
		r     ,           
		ndim  : integer   
	)

	return_val [dimsizes(x)] :  typeof(r)

Arguments

x

An array of any dimensionality.

r

A scalar or an array whose dimensions must be a subset of any of the dimensions of x.

ndim

An array of dimension indexes to indicate which dimensions of x match the dimensions in r. Dimension numbering starts at the left and must be increasing. The leftmost dimension index is 0, the next dimension index is 1, and so on. If r is a scalar, then ndim can have the special value of -1 (see below).

Description

Note: it may be preferable to use the conform_dims function. This function takes as its first argument the dimension sizes of the new array you want to conform to, rather than the array itself.

This function will create a new variable that has the same dimensionality as x and the same type as r. The values of r will be copied to all of the other dimensions.

If r is a scalar and ndims is -1, then the scalar value will be copied to all elements of a new array of the same size as x.

One use of this function is to create a new (and often temporary) variable so that it can be used for something like multiplication between two variables.

The conform function is designed to merge values from two pre-existing arrays. It can not be used to duplicate an array multiple times. Use the conform_dims function, or else use an (inefficient) loop. For example, if you have an array that you want to create K copies of and put in a new variable, then you can do:

  xCopy = conform_dims((/K,N,M/), x, (/1,2/))

or use NCL's new and typeof functions:

    xCopy = new ( (/K,N,M/), typeof(x)) 
    do k=0,K-1
       xCopy(k,:,:) = x
    end do

This function was updated in NCL version 5.0.1 to allow strings as types for the first two input arguments.

See Also

conform_dims

Examples

Example 1

If you have a 3D array x with sizes ntim x nlat x mlon and an array t of length ntim, then the following line:

    tConform = conform (x,t,0) 

will yield an array tConform that is dimensioned ntim x nlat x mlon where the contents of t are propagated to all dimensions of x.

Example 2

Assume you have a 4D array x with named dimensions "time", "lev", "lat" and "lon" and dimensioned ntim x klvl x nlat x mlon. Assume you also have a 2D array dp of size ntim x klvl, and that you want to reorder x to be ntim x nlat x nlon x klev.

You can use conform to work on the reordered grid, in which the ndim arguments refer to the reordered grid:

    dpC = conform (x(time|:,lat|:,lon|:,lev|:), dp, (/0,3/)) 

The dpC array will be dimensioned ntim x nlat x mlon x klvl.

Example 3

Assume T is a 4D array with dimensions ntim x klvl x nlat x mlon and dp is an array of length klvl. If you want to compute the column pressure weighted mean temperature at all times, then use:

  dpC = conform(T, dp, 1)  ; => (ntim,klvl,nlat,mlon)
  T_wgtAve = dim_sum(T*dpC)/dim_sum(dpC)

Example 4

The conform function can easily be used for integration when combined with other functions like dim_sum. Remember that any values that match the _FillValue attribute will be omitted from the sum.

For example, if you have an array q dimensioned nt x ny x nx x nz and an array dz of length nz, then use:

  qInt = dim_sum(q*conform(q,dz,3))  ; qInt(nt,ny,nx)

If you have an array x dimensioned ntim x nlev x nlat x nlon and an array dp of length lev, and you want to use dimension reordering:

  xLev = x(time|:,lat|:,lon|:,lev|:)   ; reorder so lev is rightmost
  xInt = dim_sum( xLev*conform(xLev, dp, 3 )) ; xInt(ntim,nlat,mlon)
  delete (xLev)                        ; only needed on a temporary basis

Example 5

If x is dimensioned ntim x nlat x nlon, and w is of length nlat and contains gaussian weights or the cosine of the latitude, then to perform a weighted average, use:

  sw   = sum(w)                                 ; sum all weights
  xTmp = x(time|:,lon|:,lat|:)                  ; temporary array
  xHov = dim_sum(xTmp, conform(xTmp,w,2) )/sw   ; xHov(ntim,mlon)
  delete (xTmp)

If lat and lon are coordinate arrays associated with x, then coordinate subscripting can be used to select a subset of the data.

For example, assume the region defined by 90E-270E and 30N-60N is of interest:

  latS = 30.    ; for clarity put ranges in variables
  latN = 60.    ; this also facilitates possible future changes
  lonE = 90.
  lonW = 270.

  sw   = sum(w({latS:latN}))            ; sum only weights appropriate
                                        ; for the range being used

  xTmp = x(time|:,{lon|lonE:lonW},{lat|latS:latN})
  xHov = dim_sum(xTmp, conform(xTmp,w({latS:latN}),2))/sw  ; xHov(ntim,mlon)

Example 6

Assume you have two grids grid1 and grid2 dimensioned ntim x nlat x nlon, where ntim is the number of different grids. To get a pattern correlation based on gaussian weights or cosine-of-latitude, where wgt(nlat) is the weight for each latitude, use the escorc function:

   wNew = ndtooned( conform(grid1, wgt, 2) )  

   r = new ( ntim, typeof(grid1) )
     
   do nt=0,ntim-1
      r(nt) = escorc(ndtooned(grid1(nt,:,:))*wNew,ndtooned(grid2(nt,:,:))*wNew)
   end do

Example 7

Assume x is dimensioned ntim x klev x nlat mlon, and that s is a scalar. Then the statement:

   xsALL = conform(x, s, -1)

will create an array xsAll dimensioned ntim x klev x nlat x mlon with every element set to s.