
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
xAn array of any dimensionality and type.
nModPad (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).
dimsThe dimension number of x to pad. Currently, only dims=0 or 1 is supported.
optCurrently 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
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) -2147483647Note: 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