
calculate_segment_values
Calculate segment (eg, pentad [5-day], weekly [7-day]) values from high frequency temporal values.
Available in version 6.4.0 and later.
Prototype
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" ; This library is automatically loaded ; from NCL V6.2.0 onward. ; No need for user to explicitly load. function calculate_segment_values ( x : numeric, arith [1] : string, nDim [1] : integer, opt [1] : logical ) return_val : float or double array with with the same rank as x.
Arguments
xArray containing the high frequency data. The rank of x must be <= 4. The x must have an associated coordinate array containing time in units recognized by the cd_calendar function. Currently, this function only works for the Gregorian calendar.
The following array structures are supported. The dimension name 'time' is a place-holder. Any name can be used. The nDim argument specifies the dimension number to be used.
(time) ; nDim=0 (time,npts) (time,ny,nx) (time,nz,ny,nx)arith
A scalar string value which specifies the operation to be performed. Valid values are: "avg" [also, "ave"], "sum", "min", "max". It is required that x have associated with it a coordinate variable named time (ie, x&time) where "time" is recognized by cd_calendar.
nDimThe dimension number of x on which to calculate the statistic. Most commonly, this is 'time'. Currently, only nDim=0 is supported.
optA logical variable to which various optional arguments may be assigned as attributes. These optional arguments alter the default behavior of the function. Must be set to True prior to setting the attributes which are assigned using the @ operator. Currently, there is two recognized attributes.
- If opt=True; the attribute 'nval_crit' (integer) will specify the minimum number of values need to calculate the desired statistic. If fewer values than 'nval_crit' are available, the result will be set to _FillValue. The default is 1 (one).
- If opt=True; the attribute 'segment_length' (integer) will specify the number of days to be used for each segment. Currently, opt@segment_length=7. Hence, the default segments are weekly values. For pentad averages: opt=True and opt@segment_length=5,
Return value
An array of the same rank (shape) as x.
Description
The function uses cd_calendar to extract the year, month, day and hour. All values for a particular segment are used. NOTE: Use of cd_calendar means the units of time are something like: "days/hours/minutes/seconds since ...". If these units are not present as an attribute of 'time', the function will not work.
Currently, this function only works for the Gregorian calendar. If no calendar attribute is present, the default is to use the 'gregorian' calendar. A fatal error message is produced if another calendar is used.
See Also
dim_avg_n, dim_sum_n, dim_min_n, dim_max_n, calculate_monthly_values, calculate_daily_values
Examples
Example 1
Let x(time,lat,lon) where x&time is recognized by cd_calendar. The values of x may contain values separated by any time step. The default segment length is 7 days (ie: weekly segments).
nDim = 0 xSegAvg = calculate_segment_values(x, "avg", nDim, False) xSegSum = calculate_segment_values(x, "sum", nDim, False) xSegMin = calculate_segment_values(x, "min", nDim, False) xSegMax = calculate_segment_values(x, "max", nDim, False)
Example 2:
Read 4x daily values for one year (2008; a leap year) and calculate the daily means. The value are type 'short' with the attributes 'scale_factor' and 'add-offset'. The 'time' dimension is: nDim=0.
f = addfile("foo.2008.nc","r") ; one year of (say) 6-hourly values x = short2flt(f->air) printVarSummary(x) ; [time | 1464] x [level | 17] x [lat | 73] x [lon | 144] opt = True opt@nval_crit = 4 ; require at least 4 values for a segment statistic to be calculated. ; default is one (1) opt@segment_length = 7 ; weekly averages are the default xSeg = calculate_segment_values (x, "avg", 0, opt) printVarSummary(xSeg)The output looks like:
Variable: xSeg Type: float Total Size: 8577792 bytes 2144448 values Number of Dimensions: 4 Dimensions and sizes: [time | 52] x [level | 17] x [lat | 73] x [lon | 144] Coordinates: time: [17593032..17601072] level: [1000..10] lat: [90..-90] lon: [ 0..357.5] Number Of Attributes: 18 _FillValue : 32766 missing_value : 32766 long_name : mean segment Air temperature valid_range : ( 150, 350 ) actual_range : ( 178.73, 318.5 ) units : degK precision : 2 least_significant_digit : 1 GRIB_id : 11 GRIB_name : TMP var_desc : Air temperature dataset : NCEP Reanalysis Daily Averages level_desc : Multiple levels statistic : Mean parent_stat : Individual Obs _FillValue_original : 32766 missing_value_original : 32766 NCL_tag = calculate_segment_values: arith=avg
Example 3:
Read hourly values for spanning multiple files and calculate the daily and monthly means. The 'time' dimension is: nDim=0.
diri = "../" fili = systemfunc("cd "+diri+" ; ls ACCESS_SRF.*.nc") ; all files beginning with 'ACCESS_SRF' nfili = dimsizes(fili) print(fili) varName = (/"snv" , "ts"/) nName = dimsizes(varName) opt = True opt@nval_crit = 10 ; require at least 10 values ndim = 0 f = addfiles(diri+fili, "r") ; read variables from all files do nv=0,nName-1 print("") print("-----------------------------------------------") print("----------- "+varName(nv)+" -----------------") print("-----------------------------------------------") print("") xhr := f[:]->$varName(nv)$ ; (time,lat,lon) printVarSummary(xhr) xdd := calculate_segment_values (xhr, "avg", ndim, opt) printVarSummary(xdd) xmm := calculate_monthly_values (xhr, "avg", ndim, opt) printVarSummary(xmm) end doThe output for the 'snv' variables is:
Variable: fili Type: string Total Size: 16 bytes 2 values Number of Dimensions: 1 Dimensions and sizes: [2] Coordinates: (0) ACCESS_SRF.1980010100.nc (1) ACCESS_SRF.1980020100.nc ; leap year (29 days in Feb. (0) (0) ----------------------------------------------- (0) -----------> snv <----------------- (0) ----------------------------------------------- (0) Variable: xhr Type: float Total Size: 176238720 bytes 44059680 values Number of Dimensions: 3 Dimensions and sizes: [time | 52] x [iy | 141] x [jx | 217] ; 1440 = (24*31)+(24*29) Coordinates: time: [263713..265152] iy: [-1750000..1750000] jx: [-2700000..2700000] Number Of Attributes: 7 long_name : Liquid water equivalent of snow thickness standard_name : lwe_thickness_of_surface_snow_amount units : kg m-2 coordinates : xlat xlon grid_mapping : rcm_map cell_methods : time: mean _FillValue : 1e+20 Variable: xdd Type: float Total Size: 7343280 bytes 1835820 values Number of Dimensions: 3 Dimensions and sizes: [time | 60] x [iy | 141] x [jx | 217] ; 60 = (31+29) Coordinates: time: [263713..265128] iy: [-1750000..1750000] jx: [-2700000..2700000] Number Of Attributes: 9 _FillValue : 1e+20 long_name : Liquid water equivalent of snow thickness standard_name : lwe_thickness_of_surface_snow_amount units : kg m-2 coordinates : xlat xlon grid_mapping : rcm_map cell_methods : time: mean time : 263713 NCL_tag : calculate_segment_values: arith=avg Variable: xmm Type: float Total Size: 244776 bytes 61194 values Number of Dimensions: 3 Dimensions and sizes: [time | 2] x [iy | 141] x [jx | 217] ; 2 months [Jan , Feb] Coordinates: time: [263713..264456] iy: [-1750000..1750000] jx: [-2700000..2700000] Number Of Attributes: 9 _FillValue : 1e+20 long_name : Liquid water equivalent of snow thickness standard_name : lwe_thickness_of_surface_snow_amount units : kg m-2 coordinates : xlat xlon grid_mapping : rcm_map cell_methods : time: mean time : 263713 NCL_tag : calculate_monthly_values: arith=avg