NCL Home > Documentation > Functions > General applied math

calculate_monthly_values

Calculate monthly values [avg, sum, min, max] from high frequency temporal values.

Available in version 6.2.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_monthly_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

Array containing the high frequency data. The x must have an associated time coordinate variable in units recognized by the cd_calendar function.

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)
       (time,ne,nz,ny,nx)         ; nDim=0; added for NCL version 6.5.0
       (ne,time,nz,ny,nx)         ; nDim=1

arith

A scalar string value which specifies the operation to be performed. Valid values are: "avg" [also, "ave"], "sum", "min", "max", "var", "std". It is required that x have associated with it a coordinate variable named time (ie, x&time) where "time" is recognized by cd_calendar.

nDim

The dimension of x on which to calculate the statistic. Currently, only nDim=0 or 1 is allowed.

Return value

An array of the same rank as x.

Description

The function uses cd_calendar to extract the year, month, day and hour. All values for a particular month 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.

As an alternative to this function, consider using the Climate Data Operators (CDO). These operators will process all variables on the file. For example:

       cdo monmean foo_hourly_or_daily.nc  foo_monthly_mean.nc
       cdo monmin  foo_hourly_or_daily.nc  foo_monthly_min.nc
       cdo monmax  foo_hourly_or_daily.nc  foo_monthly_max.nc
       cdo monsum  foo_hourly_or_daily.nc  foo_monthly_sum.nc

Examples

Example 1:

Let x(time,lat,lon) where x&time is recognized by cd_calendar. The values of x may contain (say) n-hourly or daily data.

              xMonthAvg = calculate_monthly_values(x, "avg", 0, False)
              xMonthSum = calculate_monthly_values(x, "sum", 0, False)
              xMonthMin = calculate_monthly_values(x, "min", 0, False)
              xMonthMax = calculate_monthly_values(x, "max", 0, False)
              xMonthVar = calculate_monthly_values(x, "var", 0, False)
              xMonthStd = calculate_monthly_values(x, "std", 0, False)

Example 2:

Read daily values (time,level,lat,lon) for one year and calculate the monthly means. The value are type 'short' with a scale_factor and 'add-offset'. The nDim refers to the 'time' dimension (nDim=0).

              f = addfile("air.day.2008.nc","r")
              x = short2flt(f->air)
              printVarSummary(x)

              opt = True
              opt@nval_crit = 12   ; require at least 12 values for the "avg" is calculated.
               
              xMon = calculate_monthly_values (x, "avg", 0,opt)
              printVarSummary(xMon)

The output looks like:

              Variable: xMon
              Type: float
              Total Size: 8577792 bytes
                          2144448 values
              Number of Dimensions: 4
              Dimensions and sizes:   [time | 12] 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 Monthly 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_monthly_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. In this example, the files contain hourly values for two months.


   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_daily_values (xhr, "avg", ndim, opt)
      printVarSummary(xdd)

      xmm := calculate_monthly_values (xhr, "avg", ndim, opt)
      printVarSummary(xmm)
   end do

The output for the 'snv' variables is: