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) -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