NCL Website header
NCL Home > Documentation > Functions > Array manipulators, Array creators

dim_pad_modulo

Pad (i.e., expand, append, extend) an existing array such that the size of a specified dimension is a user specified 'modulo' length.

Available in version 6.5.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"      ; These four libraries are automatically
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"       ; loaded from NCL V6.4.0 onward.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"   ; No need for user to explicitly load.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

	function dim_pad_modulo (
		x        ,           
		nMod [1] : integer,  
		dims [1] : integer,  
		opt  [1] : logical   
	)

	return_val  :  typeof(x))

Arguments

x

An array of any dimensionality and type.

nMod

Pad (aka: expand, append, extend) the 'size' of the user specified dimension (dims) to get a 'SIZE' such that (SIZE % nMod)=0. Most commonly, nMod=12 (monthly); =360, 365, 366 (daily).

dims

The dimension number of x to pad. Currently, only dims=0 or 1 is supported.

opt

Currently not used. Set to False.

Description

Padding an array may be necessary when the array dimension size (say,"p") is too small for an application (eg: array operation or function requirement). The dim_pad_modulo uses NCL's 'modulus' operator (%) to compute the remainder of p%nMod. If non-zero, the specified array dimension is expanded such that P%nMod=0 where 'P' is > 'p'. Currently, the padded (appended) values are set to an apprpriate _FillValue.

Meta data are preserved except for the coordinate variable along the dimension specified by dims. If there is no existing dimension name, a new dimension name (modulo_nMod). See Example 1.

FYI: The reason for using additional descriptive words for 'pad' such as "expand", "append", "extend", etc is that other languages use different terms.

See Also

Array manipulators

Examples

Example 1:

Pad (expand, append, extend) an existing array ('y') of size 'ny' (here, 21) to a size such that ny%nMod=0. NCL's reassignment operator [ := ] is used to allow the original array to be over-written (reassigned). Since, 'y' is a one-dimensional array, dims=0. Also, since there is no dimension name, a dimension name modulo_nMod=modulo_12 is created.

  y    = ispan(1, 21, 1)    ; y(ny); y(21)
  Nmod = 12                 ; Nmod < ny
                            ; NCL's reassignment operator [ := ] used to overwrite
  y   := dim_pad_modulo(y,Nmod,0,False)  ; Nmod=12 ==>  y(24) 
  print(y) 

The output is:
  Variable: y
  Type: integer
  Total Size: 48 bytes
              24 values
  Number of Dimensions: 1
  Dimensions and sizes:   [modulo_12 | 24]       ; <=== created dimension name
  Coordinates: 
  Number Of Attributes: 1
    _FillValue :  -2147483647
    Nmod :        12

  (0)     1
  (1)     2
    [SNIP]
  (19)    20
  (20)    21
  (21)    -2147483647     ; added values are set to _FillValue 
  (22)    -2147483647
  (23)    -2147483647
Note: Instead of reassignment, a new array could have been created:

  Y = dim_pad_modulo(y,12,0,False)  ; Y(24) 

Example 2: Same as Example 1 but Nmod=81. Here Nmod is less than 'ny'. The edited output is:


  Variable: y
  Type: integer
  Dimensions and sizes:   [modulo_81 | 81]       ; <=== created dimension name
    _FillValue :  -2147483647
    Nmod :        81
  (0)     1
  (1)     2
    [SNIP]
  (79)    -2147483647     ; added values are set to _FillValue 
  (80)    -2147483647    

Example 3: Read a netCDF file containing monthly values of "Snow Water Equivalent." The file contains values spanning January 1979 thru May 2007. Then, compute the monthly mean climatology that includes the five months (Jan-May) of 2007. The clmMonTLL function requires that there be 12 monthly values per year. Use dim_pad_modulo to expand the array to the required size.


   diri = "./"
   f    = addfile(diri+"swe_mon_jan1979tomay2007smmrssmi.nc","r")    
   swe  = f->swe
   printVarSummary(swe)                    ; [time | 341] x [lat | 60] x [lon | 360] 

   swe := dim_pad_modulo(swe, 12, 0, False)  ; [time_modulo_12 | 348] x [lat | 60] x [lon | 360]
   printVarSummary(swe)

   swe_clm = clmMonTLL(swe)                ; [month | 12] x [lat | 60] x [lon | 360]
   printVarSummary(swe_clm)

The (edited) output is:

  Variable: swe
  Type: float
  Total Size: 29462400 bytes
              7365600 values
  Number of Dimensions: 3
  Dimensions and sizes:	[time | 341] x [lat | 60] x [lon | 360]
  Coordinates: 
              time: [   0..248328]
              lat: [  30..  89]
              lon: [   0.. 359]
  Number Of Attributes: 2
    long_name :	Snow Water Equivalent
    _FillValue :	-999
  (0)	===
  
  Variable: swe                         <<< after dim_pad_modulo
  Type: float
  Total Size: 30067200 bytes
              7516800 values
  Number of Dimensions: 3
  Dimensions and sizes:	[TIME | 348] x [lat | 60] x [lon | 360]
  Coordinates: 
                                                  NOTE:  'time/TIME' coordinates are not present
              lat: [  30..  89]
              lon: [   0.. 359]
  Number Of Attributes: 2
    _FillValue :	-999
    long_name :	Snow Water Equivalent
    Nmod :      12
  (0)	===
  
  Variable: swe_clm
  Type: float
  Total Size: 1036800 bytes
              259200 values
  Number of Dimensions: 3
  Dimensions and sizes:	[month | 12] x [lat | 60] x [lon | 360]
  Coordinates: 
              month: [0..11]
              lat: [  30..  89]
              lon: [   0.. 359]
  Number Of Attributes: 4
    _FillValue :	-999
    long_name :	Snow Water Equivalent
    time_op_ncl :	Climatology: 29 years
    info :	function clmMonTLL: contributed.ncl